:author: 周茂
:date: 2024-06-21

.. index:: ! mgd77manage
.. program:: mgd77manage

mgd77manage
===========

这里首先介绍 mgd77 整个包：

mgd77 模块
----------

本模块主要用来管理和处理美国 NGDC (National Geophysical Data Center，现为
National Centers for Environmental Information，NCEI) 机构下的海洋地球物理
数据。在不同的时期，针对上述数据，NCEI 开发了多种数据格式，MGD77 格式为
1977 年针对沿测线重力，磁，测深以及地震等观测开发的格式，目前已经成为国际
数据交换的标准，并在某个版本中加入了制表符分隔的 MGD77T 格式。目前 **mgd77**
主要包括下面 9 个命令：

- :doc:`mgd77manage` 管理 MGD77+ 文件
- :doc:`mgd77convert` 将 MGD77 数据转换为其他格式
- :doc:`mgd77header` 从 A77 文件创建 MGD77 头部信息
- :doc:`mgd77info` 提取 MGD77 文件信息
- :doc:`mgd77list` 提取 MGD77 文件中的数据
- :doc:`mgd77magref` 计算 IGRF 或 CM4 磁场模型
- :doc:`mgd77path` 返回 MGD77 测线路径
- :doc:`mgd77sniffer` MGD77 测线沿轨质量控制
- :doc:`mgd77track` 绘制 MGD77 测线轨迹

下面将做整体介绍：

**1. 前言**

mgd77 模块的主要功能为

- 改进原本的 mgg 工具集有限的功能

- 实现对数据文件增加新的数据列

- 添加新的格式，即 NetCDF 格式，称为 MGD77+ 或 MGD77+ NetCDF 格式

下面介绍维护文件需要的信息和步骤。

**2. 介绍**

**数据位置** ：**$MGD77_HOME** 环境变量为 mgd77 模块的主要目录，其中包含
一个名为 mgd77_paths.txt 的文件，文件内容为不同的路径，这些路径即为
mgd77 数据文件的位置。如果未设置该环境变量，则默认为设置为
**$GMT_SHAREDIR**/mgd77。

**3. 转换**

使用 :doc:`mgd77convert` 可以将 MGD77 文本文件（.mgd77）转换为 MGD77+
NetCDF 格式（.nc）。使用下面的命令可以实现批量转换 ::

    mgd77convert =cruises.lis -Fa -Tc -V -Lwe+l > log.txt

cruises.lis 文件中包含了所有需要转换的文件名。新生成的 nc 文件也可以放在
一个或者多个单独的文件夹中，将其路径列在 mgd77_paths.txt 文件中。建议将
\*.nc 文件夹的路径放在 \*.mgd77 路径之前。使用 **-I** 选项可以选择特定
后缀的文件。

**4. 添加新列**

**mgd77manage** 允许用户添加新数据列到 nc 文件中，包括文本字符串，或从
其他网格模型沿轨采样的点等。最大支持 32 个新数据列。数据提取工具，例如
:doc:`mgd77list` 可用于提取数据列以及用户添加的新列。

**5. 误差源**

在讨论改正 MGD77 数据的误差前，这里首先分析各种观测误差:

#. 头部信息中某些字段不符合 MGD77 规范或缺少该字段时，将会导致错误。
   :doc:`mgd77convert` 在使用较高级别的 **-V** 选项会提示这些错误。
   这些错误通常不会影响数据。

#. 尽管遵循 MGD77 规范，但当特定的数据列编码不正确时，会导致系统误差。
   通常情况下会导致一个固定常数缩放因子，比如，10 或者 0.1，在将 fathom
   转换为 m 时甚至可能出现 1.8288 的因子。

#. 当记录数据或者处理数据时，由于沿轨的纬度、航向或者其他和时间相关的
   因素可能会导致未知的系统误差。这种误差有时可以通过后期的数据分析解决，
   例如沿轨和跨轨的检查，通过数据分析可生成改正项，并应用到数据中改正
   这些误差的影响。但这些改正项在新出现观测数据后可能会变化，因此是
   一种短时间的改正，需要随着数据的加入不断更新。

#. 单个数据或者数据序列可能会超出数据实际范围或者在其他方面突破
   某种限制，这种数据是不符合实际的。此外，即使在实际范围内，也存在
   连续数据突变的情况，这同样是不符合实际的。因此，可以对每个数据点
   生成一个 GOOD 或者 BAD 的标志来标记这些数据。

对于上述误差，目前的策略为，第 1，2 和 4 种误差将通过在 \*.nc 文件
中在元数据提供信息来改正，第 3 种误差的改正则单独保存在改正表中，因为
这些改正通常是不断变化的。

**6. 误差定位**

**mgd77sniffer** 可用来对原始的 MGD77 ASCII 文件进行彻底的沿轨完整性
检查，并生成对应的 \*.e77 错误日志。所有发现的问题都会记录在错误日志
中，如果需要，还会给出建议的改正项。后续专业人员可以验证这些改正项是
否有效。编辑其中的错误并修正改正项，并通过相关的的代码 key 值激活（
请见 :doc:`mgd77sniffer` ）。**mgd77manage** 可以读取这些错误日志，
根据日志中的建议修正错误的头部记录，在读取某些列的时候应用改正项。
如果用户在后续发现其他问题，请重新运行这一步骤，因为所有的 E77 设置
或标志都是根据最新的 E77 文件重新创建的。

**7. 误差改正**

数据提取命令 :doc:`mgd77list` 允许在数据提取时应用改正。过程为首先
剔除带有 BAD 标志的数据，然后应用系统误差改正项，最后，如果制定了改正表，
应用这种暂时的改正。所有这些步骤都需要头部数据，并且可以被用户调整。
此外，用户可以添加自己的标志作为单独的数据列，使用 :doc:`mgd77list`
的逻辑测试来确定输出哪些数据。

下面将介绍 :doc:`mgd77manage` 命令，其他命令见对应文档。

mgd77manage
-----------

:官方文档: :doc:`gmt:supplements/mgd77/mgd77manage`
:简介: 管理 MGD77+ 文件

**mgd77manage** 用来处理在 MGD77+ NetCDF 文件中的自定义列。用户可以删除列，增加列，
更新已经存在的列，或使用 e77 文件进行误差改正。新数据可以来自 ASCII 表文件，或基于
现有的列和理论表达式，或对网格进行沿轨采样得到。新数据将以自定义数据列的形式追加
到 MGD77+ 文件中具体见 `mgd77 模块`_ 。

语法
----

**gmt mgd77manage**
*GEODAS-ids*
[ :option:`-A`\ **a**\|\ **c**\|\ **d**\|\ **D**\|\ **e**\|\ **E**\|\ **g**\|\ **i**\|\ **n**\|\ **t**\|\ **T**\ *fileinfo*\ [**+f**]\ ]
[ :option:`-D`\ *abbrev1*,\ *abbrev2*,... ]
[ :option:`-E`\ *empty* ]
[ :option:`-F` ]
[ :option:`-I`\ *abbrev*/*name*/*unit*/**c**/*scale*/*offset*/*comment* ]
[ :option:`-N`\ *unit* ]
[ :option:`-R`\ *region* ]
[ :option:`-V`\ [*level*] ]
[ :option:`-bi`\ *binary* ]
[ :option:`-di`\ *nodata*\ [**+c**\ *col*] ]
[ :option:`-j`\ *flags* ]
[ :option:`-n`\ *flags* ]
[ :doc:`--PAR=value </conf/overview>` ]

输入数据
--------

.. include:: explain_ncid.rst_

可选选项
--------

.. option:: -A

**-A**\ **a**\|\ **c**\|\ **d**\|\ **D**\|\ **e**\|\ **E**\|\ **g**\|\ **i**\|\ **n**\|\ **t**\|\ **T**\ *fileinfo*\ [**+f**]
    添加新的数据列。如果文件中已经存在相同名称的列，则无法添加。**+f** 选项可以
    强制覆盖，但是在某些情况下，这种强行覆盖会失败，需要先删除对应的列，然后再
    添加，出现这种情况时，会警告提示。新增的列时可以使用如下代码，其含义如下：

    - **a** 追加包含要添加的列的文件名。文件的行数必须与 MGD77+ 文件中相同。如果
      不指定文件名，则从标准输入中读取。

    - **c** 从现有的数据或者公式创建新列，用于改正或者作为参考场。其后可以再接一
      个字符，字符的含义如下：

      - **c** 从未改正的测深中减去 Carter 改正

      - **g** IGF 重力参考场（也称为“正常重力”）；使用头部信息中的代码确定计算的公
        式，如果未设置或者无效，则默认使用 IGF1980；代码含义如下：

        - 1 Heiskanen 1924

        - 2 International 1930

        - 3 IGF1967

        - 4 IGF1980

      - **m** IGRF 总磁场参考场

      - **r** 重新计算的磁异常 rmag = mtfx - IGRF，追加 1 或者 2 表示使用的字段

    - **d** 指定一个包含两列数据的文件名，第一列为沿轨距离，第二列为数值。如果
      不指定文件，则从标准输入中读取。MGD77+ 文件中有对应的距离则将被新值取代，
      在其他距离，设置为 NaN。 使用 :option:`-N` 设置距离单位，通过 :option:`-j` 选择距离
      计算方式。

    - **D** 与 **d** 功能类似，但在没有给定距离的点，内插得到其更新值

    - **e** 从当前路径或者 $MGD77_HOME/E77 路径中寻找 :doc:`mgd77sniffer` 生成
      的 *GEODAS_ID.e77* E77 日志，使用该日志检查数据并修改头部信息，为某些系统
      误差提供改正项（例如缩放尺度和偏移量），指定某个异常应用观测值中重新计算（
      例如：从  **mtf1** 和 最新的 IGRF 计算 **mag** ），并增加或者更新特殊的列
      标记 **flag** 。所有的固定修改项（例如：由于源机构使用了错误的单位，需要对
      字段进行缩放）将作为属性写入到 NetCDF MGD77+ 文件中，并在 :doc:`mgd77list`
      读取数据时自动应用该缩放值。通过交叉分析确定的临时的校正不保存在数据文件中，
      而是保存在改正表中（见 :doc:`mgd77list` ）。默认情况下，e77 文件中每个头段
      行的第一个字符（?, Y，N）用来表示是否应该应用响应的改正，其中只有 Y 会被改
      正。对 **-Ae** 进一步使用子选项可以修改这种行为，**h** 忽略所有的头段信息
      提供的改正，**f** 忽略所有固定固定校正值，**n** , **v** 和 **s** 将忽略
      与导航，数据值以及其变化率的标志。使用 **-Ae+f** 将使用新的值替换文件中任何
      现有的 E77 改正。最后，如果 E77 文件没有被验证，则其改正值将不会被应用。使
      用 **-AE** 来忽略验证状态。

    - **g** 沿着 MGD77+ 文件给出的轨迹，使用双三次插值对 GMT 地理网格进行插值，
      后面追加 GMT 网格文件名。

    - **i** 沿 MGD77+ 文件轨迹使用双三次插值内插 Sandwell/Smith 墨卡托 \*.img
      网格。追加 img 网格文件名，一个缩放尺度（通常为 1 或者 0.1），img 文件格式
      （0-3）以及一个可选的网格最大纬度[80.738]，用逗号分隔。文件格式模式中：

        - 0 代表 img 文件没有约束代码，返回所有数据

        - 1 代表 img 文件有约束代码，返回所有数据

        - 2 代表 img 文件有约束代码，返回只在约束点的数据，其他地方为 NaN

        - 3 代表 img 文件有约束代码，在约束点返回 1，其他地方为 0

    - **n** 追加一个两列表文件名第一列为记录编号，从 0 开始，第二列为数据值，如果
      不指定文件，则从标准输入中读取。使用对应的数据替换 MGD77+ 中的数据，其他数据
      则设置为 NaN

    - **t** 追加一个两列表文件名，第一列为绝对时间，第二列为数据值，如果不指定
      文件，则从标准输入中读取。MGD77+ 文件中时间与数据中相对应的会被替换，其他数据
      设置为 NaN。使用大写的 **T** 选项，将会进行内插。

.. option:: -D

**-D**\ *abbrev1*,\ *abbrev2*,...
    给定一个逗号分隔的行缩写列表，从 MGD77+ 文件中删除这些数据。如果要替换数据
    则不应该使用该选项，而是使用 **-A...+f** 。由于不能从 NetCDF 文件中删除变量，
    所以必须创建一个新的文件，其中不包含被剔除的列。一旦文件被创建，则临时删除
    旧文件，将新文件命名为旧文件，然后移除旧文件。

.. option:: -E

**-E**\ *empty*
    指定单独的字符用来替换空字符串值，例如：“9” 将会把空字符串替换为 “999....”，
    默认为 9。

.. option:: -F

**-F**
    强制模式。当激活该模式时，可以强制删除或者替换标准的 MGD77 文件中列。用户
    需要慎重。

.. option:: -I

**-I**\ *abbrev*/*name*/*unit*/**c**/*scale*/*offset*/*comment*
    除了文件信息，还可以为新增的列指定属性等信息。可指定所选数据的缩写（16 个字符
    或者更小，仅使用小写字母、数字或下划线），详细描述名声、单位、数据类型（上述
    以 **c** 为例，下面会介绍各种数据类型缩写），缩放参数 scale 以及 offset，以及
    其他说明（小于 128 字符）。

    数据类型可选项包括：

    - **c** 字符

    - **b** Byte 类型

    - **s** short 整数类型

    - **f** float 浮点数类型

    - **i** int 整数类型

    - **d** double 浮点数类型

    - **t** text 文本类型

    如果选择了文本数据类型，则 :option:`-A` 讨论中的“值”指的是本文数据，插值对于该类型不
    适用，包含多个单词的值需要加上引号。

.. option:: -N

**-N**\ *unit*
    指定距离单位（见 `距离单位`_ ）[默认为 **-Nk** （km）]。
    只在 **-Ag**\|\ **i** 使用时可用。

.. include:: explain_-R.rst_

.. include:: explain_-V.rst_

.. include:: explain_-bi.rst_

.. include:: explain_-di.rst_

.. include:: explain_distcalc.rst_

.. include:: explain_-n.rst_

.. include:: explain_help.rst_

.. include:: explain_distunits.rst_

示例
----

在 Geosat/ERS-1 得到的 11.2 版本的海洋重力场中内插 01010047.nc 和 01010008.nc ，
将内插结果写到文件中，类型为 2-byte 短整形，单位为 mGal \* 10 ::

    gmt mgd77manage 01010047 01010008 -Ai10/1/grav.11.2.img \
        -Isatgrav/"Geosat/ERS-1 gravity"/"mGal"/s/10/0/"Sandwell/Smith version 11.2" -V

使用一个滤波后的磁观测数据添加到 01010047.nc 作为新的列，类型为 float，在对应
的时间内插该磁观测数据 ::

    gmt mgd77manage 01010047 -ATmymag.tm -Ifiltmag/"Intermediate-wavelength \
        magnetic residuals"/"nTesla"/f/1/0/"Useful for looking for isochrons" -V

从所有的 MGD77+ 文件中删除 satfaa、coastdist 以及 satvgg 列 ::

    gmt mgd77manage =allmgd77.lis -Dsatfaa,coastdist,satvgg -V

从所有的 MGD77+ 文件中创建 IGRF 字段，4 字节浮点数类型 ::

    gmt mgd77manage =allmgd77.lis -Acm -Iigrf/"IGRF reference \
        field"/"nTesla"/f/1/0/"IGRF version 10 for 1990-2010" -V

Credits
-------

IGRF 基于英国地质调查局的 Susan Macmilan 编写的 Fortran 程序，由 Algrave 大学的 Joaquim 通过
f2c 转换到 C 语言，最终 Paul Wessel 改成 GMT 风格。

参考
----

MDG77 格式见
`http://www.ngdc.noaa.gov/mgg/dat/geodas/docs/mgd77.txt. <http://www.ngdc.noaa.gov/mgg/dat/geodas/docs/mgd77.txt>`__

IGRF 见 `<https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html>`__

相关模块
--------

:doc:`mgd77convert`,
:doc:`mgd77header`,
:doc:`mgd77list`,
:doc:`mgd77magref`,
:doc:`mgd77info`,
:doc:`mgd77track`,
:doc:`mgd77sniffer`,
:doc:`mgd77track`
