mgd77list - Extract data from MGD77 files
mgd77list NGDC-ids -Fcolumns[,logic][:bittests] [ -A[+]c|d|f|m|tcode ] [ -Cf|g|e ] [ -DA|astartdate ] [ -DB|bstopdate ] [ -E ] [ -Gastartrec ] [ -Gbstoprec ] [ -Iignore ] [ -L[corrtable] ] [ -Nd|sunit ] [ -Qa|c|vmin/max ] [ -Rregion ] [ -Sastartdist[unit] ] [ -Sbstopdist[unit] ] [ -T[m|e] ] [ -V[level] ] [ -Wweight ] [ -Z+|- ] [ -bo<binary> ] [ -h<headers> ]
Note: No space is allowed between the option flag and the associated arguments.
mgd77list reads <NGDC-id>.[mgd77|nc] files and produces an ASCII [or binary] table. The <NGDC-id>.[mgd77|nc] files contain track information such as leg-id, time and position, geophysical observables such as gravity, magnetics, and bathymetry, and control codes and corrections such as Eotvos and diurnal corrections. The MGD77+ extended netCDF files may also contain additional user columns (for a listing of available columns, use mgd77info -C, and to learn how to add your own custom columns, see mgd77manage). The user may extract any combination of these parameters, any of 8 computed quantities (distance, heading, course-change, velocity, Carter correction, Eotvos correction and gravity and magnetic global reference fields), calendar sub-units of time (year, month, day, hour, min, sec), the NGDC id, and finally a preset weight (see -W). A sub-section can be specified by passing time- or distance-intervals along track or by selecting a geographical region. Finally, each output record may be required to pass any number of logical tests involving data values or bit flags. If multiple cruises are requested then they are separated by segment headers.
Can be one or more of five kinds of specifiers:
(See mgd77info -L for agency and vessel codes). The ”.mgd77” or ”.nc” extensions will automatically be appended, if needed (use -I to ignore certain file types). Cruise files will be looked for first in the current directory and second in all directories listed in $MGD77_HOME/mgd77_paths.txt [If $MGD77_HOME is not set it will default to $GMT_SHAREDIR/mgd77].
The required columns string must be a comma-separated list of parameter abbreviations given in the desired output order. Any parameters given in UPPER case must not be NaN in a record for output to occur. Unless specified separately, the output format (if ASCII) is controlled by the GMT parameter FORMAT_FLOAT_OUT. The available column abbreviations for information stored in the files (some columns may be NaN) are:
In addition, the following derived navigational quantities can be requested:
Finally, the following computed quantities can be requested:
The following short-hand flags are also recognized:
As an option, logical tests may be added for any of the observations by appending ,logic, which is itself composed of one or more comma-separated instructions of the form parOPvalue, where par is one of the parameters listed above, OP is a logical operator (<, <=, =, !=, >=, >, |), and value is a constant used in the comparison. Floating point parameters are compared numerically; character parameters are compared lexically (after leading and trailing blanks have been removed). The bit comparison (|) means that at least one of the bits in value must be turned on in par. At least one of the tests must be true for the record to be output, except for tests using UPPER case parameters which all must be true for output to occur. Note that specifying a test does not imply that the corresponding column will be included in the output stream; it must be present in columns for that to occur. Note: some of the operators are special UNIX characters and you are advised to place quotes around the entire argument to -F.
Finally, for MGD77+ files you may optionally append :bittests which is : (a colon) followed by one or more comma-separated +-col terms. This compares specific bitflags only for each listed column. Here, + means the chosen bit must be 1 (ON) whereas - means it must be 0 (OFF). All bit tests given must be passed. By default, MGD77+ files that have the special MGD77_flags column present will use those flags, and observations associated with ON-bits (meaning they are flagged as bad) will be set to NaN; append : with no trailing information to turn this behavior off (i.e., no bit flags will be consulted).
Determines how the carter correction term is calculated. Below, C(twt) stands for the Carter-corrected depth (it also depends on lon, lat), U(twt, v) is the uncorrected depth (= twt * v / 2) using as v the “Assumed Sound Velocity” parameter in the MGD77 header (if it is a valid velocity, otherwise we default to 1500 m/s); alternatively, append your preferred velocity v in m/s, TU(depth, v) is the 2-way travel time estimated from the (presumably) uncorrected depth, and TC(depth) is the 2-way travel time obtained by inverting the (presumably) corrected depth using the Carter correction formula. Select from
-Ac1[,v] returns difference between U(twt, v) and depth [Default].
-Ac2[,v] returns difference between U(twt, v) and Carter (twt).
-Ac4[,v] returns difference between (assumed uncorrected) depth and Carter (TU(depth)).
-Ac8[,v] returns difference between U(TC(depth), v) and depth.
Determines how the depth column output is obtained:
-Ad1 returns depth as stored in the data set [Default].
-Ad2[,v] returns calculated uncorrected depth U(twt, v).
-Ad4 returns calculated corrected depth C(twt).
Determines how the faa column output is obtained. If ngrav (i.e., the International Gravity reference Field (IGF), or “normal gravity”) is required it is selected based on the MGD77 header parameter “Theoretical Gravity Formula Code”; if this code is not present or is invalid we default to 4. Alternatively, append the preferred field (1-4) to select 1 (Heiskanen 1924), 2 (IGF 1930), 3 (IGF 1967) or 4 (IGF 1980). Select from
-Af1[,field] returns faa as stored in the data set [Default]. Optionally, sets the IGF field to use if you also have requested ngrav as an output column in -F.
-Af2[,field] returns the difference between gobs and ngrav (with optional field directive).
-Af4[,field] returns the combination of gobs + eot - ngrav (with optional field directive).
-Af8[,field] returns the combination of gobs + pred_eot - ngrav (with optional field directive).
Determines how the mag column output is obtained. There may be one or two total field measurements in the file (mtf1 and mtf2), and the column msens may state which one is the leading sensor (1 or 2; it may also be undefined). Select from
-Am1 returns mag as stored in the data set [Default].
-Am2 returns the difference between mgfx and igrf, where x is the leading sensor (1 or 2) indicated by the msens data field (defaults to 1 if unspecified).
-Am4 returns the difference between mgfx and igrf, where x is the sensor (2 or 1) not indicated by the msens data field (defaults to 2 if unspecified).
-Amc<offset>[unit] Apply a correction that tries to compensate the fact that the magnetic field was not acquired at the same position as the navigation refer (ship’s position). This is accomplished by re-interpolating the total magnetic field to what it would have had if it was measured at the ship’s position (remember, it probably was measured <offset> meters behind). Due to this interpolation step, bad navigation, namely too many repeated points, may cause troubles. Measures are taken to minimize this effect but they aren’t 100% full prof. The interpolation method is controlled by the GMT default GMT_INTERPOLANT. Append e for meter, f for feet, k for km, m for miles, n for nautical miles, or u for survey feet [Default is e (meters)].
Append a one-letter code to select the procedure for along-track distance calculation (see -N for selecting units):
f Flat Earth distances.
g Great circle distances [Default].
e Geodesic distances on current GMT ellipsoid.
To get a (distance, heading, gravity, bathymetry) listing from 01010047.mgd77, starting at June 3 1971 20:45 and ending at distance = 5000 km, use the following command:
gmt mgd77list 01010047 -Da1971-06-03T20:45 -Sb5000 -Fdist,azim,faa,depth > myfile.d
To make input for blockmean and surface using free-air anomalies from all the cruises listed in the file cruises.lis, but only the data that are inside the specified area, and make the output binary:
gmt mgd77list `cat cruises.lis` -Flon,lat,faa -R-40/-30/25/35 -bo > allgrav.b
To extract the locations of depths exceeding 9000 meter that were not interpolated (btc != 1) from all the cruises listed in the file cruises.lis:
gmt mgd77list `cat cruises.lis` -F"depth,DEPTH>9000,BTC!=1" > really_deep.d
To extract dist, faa, and grav12_2 from records whose depths are shallower than 3 km and where none of the requested fields are NaN, from all the MGD77+ netCDF files whose cruise ids are listed in the file cruises.lis, we try
gmt mgd77list `cat cruises.lis` -E -Ia -F"dist,faa,grav12_2,depth<3000" > \ shallow_grav.d
To extract dist, faa, and grav12_2 from all the MGD77+ netCDF files whose cruise ids are listed in the file cruises.lis, but only retrieve records whose bitflag for faa indicates BAD values, we try
gmt mgd77list `cat cruises.lis` -E -Ia -F"dist,faa,grav12_2:+faa" > bad_grav.d
To output lon, lat, mag, and faa from all the cruises listed in the file cruises.lis, but recalculate the two residuals based on the latest reference fields, try:
gmt mgd77list `cat cruises.lis` -Flon,lat,mag,faa -Af2,4 -Am2 > data.d
When recalculated anomalies are requested (either explicitly via the -A option or implicitly via E77 metadata in the MGD77+ file) we only do so for the records whose original anomaly was not a NaN. This restriction is implemented since many anomaly columns contains corrections, usually in the form of hand-edited changes, that cannot be duplicated from the corresponding observation.
The IGRF calculations are based on a Fortran program written by Susan Macmillan, British Geological Survey, translated to C via f2c by Joaquim Luis, U Algarve, and adapted to GMT-style by Paul Wessel.
The equations used are reproduced here using coefficients extracted directly from the source code (let us know if you find errors):
(1) g = 978052.0 * [1 + 0.005285 * sin^2(lat) - 7e-6 * sin^2(2*lat) + 27e-6 * cos^2(lat) * cos^2(lon-18)]
(2) g = 978049.0 * [1 + 0.0052884 * sin^2(lat) - 0.0000059 * sin^2(2*lat)]
(3) g = 978031.846 * [1 + 0.0053024 * sin^2(lat) - 0.0000058 * sin^2(2*lat)]
(4) g = 978032.67714 * [(1 + 0.00193185138639 * sin^2(lat)) / sqrt (1 - 0.00669437999013 * sin^2(lat))]
The correction table is an ASCII file with coefficients and parameters needed to carry out corrections. Comment records beginning with # are allowed. All correction records are of the form
cruiseID observation correction
where cruiseID is a NGDC prefix, observation is one of the abbreviations for geophysical observations listed under -F above, and correction consists of one or more terms that will be summed up and then subtracted from the observation before output. Each term must have this exact syntax:
factor[*[function]([scale](abbrev[-origin]))[^power]]
where terms in brackets are optional (the brackets themselves are not used but regular parentheses must be used as indicated). No spaces are allowed except between terms. The factor is the amplitude of the basis function, while the optional function can be one of sin, cos, or exp. The optional scale and origin can be used to translate the argument (before giving it to the optional function). The argument abbrev is one of the abbreviations for observations listed above. If origin is given as T it means that we should replace it with the value of abbrev for the very first record in the file (this is usually only done for time). If the first record entry is NaN we revert origin to zero. Optionally, raise the entire expression to the given power, before multiplying by the amplitude. The following is an example of fictitious corrections to the cruise 99999999, implying the depth should have the Carter correction removed, faa should have a linear trend removed, the magnetic anomaly (mag) should be corrected by a strange dependency on ship heading and latitude, and gobs needs to have 10 mGal added (hence given as -10):
99999999 depth 1.0*((carter))
99999999 faa 14.1 1e-5*((time-T))
99999999 mag 0.5*cos(0.5*(azim-19))^2 1.0*exp(-1e-3(lat))^1.5
99999999 gobs -10
The Marine Geophysical Data Exchange Format - MGD77, see http://www.ngdc.noaa.gov/mgg/dat/geodas/docs/mgd77.txt
IGRF, see http://www.ngdc.noaa.gov/IAGA/vmod/igrf/