x2sys_init - Initialize data baes for track data files

x2sys_init TAG [ -Ddeffile ] [ -F ] [ -Gd|g ] [ -Idx[dy] ] [ -Rwest/east/south/north ] [ -V ] [ -Wsize ]

x2sys_init initializes a set of data bases that are particular to one kind of track data. These data and their associated data bases are given a short-hand notation called a system TAG. The TAG remembers settings such as file format, whether the data are geographic or not, and the binning resolution for track indexes. Running x2sys_init is a prerequisite to running x2sys_binlist which will create a crude representation of where data track go; this serves as input to the x2sys_put too which updates the track data base. Then, x2sys_get can be used to find which tracks and data are available inside a given region.

TAG

The unique name of this data type system.

No space between the option flag and the associated arguments

-D

Definition file for this data set. [x2sys.def]

-G

Selects geographical coordinates. Append d for discontinuity at the Dateline (makes longitude go from -180 to + 180) or g for discontinuity at Greenwhich (makes longitude go from 0 to 360 [Default]).

-R

xmin, xmax, ymin, and ymax specify the Region of interest. For geographic regions, these limits correspond to west, east, south, and north and you may specify them in decimal degrees or in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left and upper right map coordinates are given instead of wesn. The two shorthands -Rg -Rd stand for global domain (0/360 or -180/+180 in longitude respectively, with -90/+90 in latitude). For calendar time coordinates you may either give relative time (relative to the selected TIME_EPOCH and in the selected TIME_UNIT; append t to -JX|x), or absolute time of the form [date]T[clock] (append T to -JX|x). At least one of date and clock must be present; the T is always required. The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock string must be of the form hh:mm:ss[.xxx]. The use of delimiters and their type and positions must be as indicated (however, input/output and plotting formats are flexible).

-V

Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].

-W

Sets maximum time gap (in user units) allowed between points on either side of a crossover [Default is Infinity].

If you have a large set of track data files you can organize them using the x2sys tools. Here we will outline the steps. Let us assume that your track data file format consist of 2 header records with text information followed by any number of data records with 6 columns (lat, lon, time, obs1, obs2, obs3). We will call this the "line" format. First we create the line.def file:

# Define file for the line format

#ASCII # File is ascii

#SKIP 2 # Skip 2 header records

#name intype NaN-proxy? NaN-proxy scale offset oformat

lon a N 0 1 0 %10.5lf

lat a N 0 1 0 %9.5lf

time a N 0 1 0 %7.1lf

obs1 a N 0 1 0 %7.2lf

obs2 a N 0 1 0 %7.2lf

obs3 a N 0 1 0 %7.2lf

For ascii data the intype format is always a, Nan-proxy? should be Y if there are certain values (e.g., -9999) that is used to represent missing data (NaNs). If so, the NaN-proxy values should be set accordingly (otherwise it is ignored). The scale and offset is applied to the data after it is read (first scaled, then offset), whereas the oformat is used by some programs for formatted output.

Next we create the TAG and the databases for these line track files. Assuming these are geographic and that we want to keep track of the data distribution at a 1 x 1 degree resolution, we may run

x2sys_init LINE -V -G -Dline -R0/360/-90/90 -I1/1

where we have call the tag LINE. When x2sys tools will try to read your line data files they will look in the file TAG_paths.txt for a list of all the directories to examine. Therefore, create such a file (here LINE_paths.txt) and stick the full paths to your data directories there. All TAG-related files will be expected to be in the directory pointed to by $X2SYS_HOME.

create tbf file(s)

Once the (empty) TAG database have been initialize we go through a two- step process to populate them. First we run x2sys_binlist on all our track files to create one (or more) multi-segment track binindex files (tbf). These contain information on which 1x1 degree bins each track has visited and which observations (in your case obs1, obs2, obs3) where actually observed (not all tracks may have all the kinds of observations). Next, the track binindex files are fed to x2sys_put which will insert the information into the tag databases.

search

Now you may use x2sys_get to find all the tracks within a certain sub-region, and optionally limit the search to those tracks that have a particular combination of observables.

MGD77 or GMT

Definition files already exist for MGD77 files, the old *.gmt files manipulated by the mgg supplements, and plain x,y,z tracks. To initiate new track databases to be used with MGD77 data from NGDC, try

x2sys_init MGD77 -V -Dmgd77 -R0/360/-90/90 -I1/1

and the other steps are similar.

binary files

Let us pretend that your line files actually were binary files with a 128-byte header structure (to be skipped) followed by the data records and where lon, lat, time are double precision numbers while the three observations are 2-byte integers which must be multiplied by 0.1. Finally, the first two observations may be 32000 which means there is no data. All that is needed is a different line.def file:

# Define file for the line format

#BINARY # File is now binary

#SKIP 128 # Skip 128 bytes

#name intype NaN-proxy? NaN-proxy scale offset oformat

lon d N 0 1 0 %10.5lf

lat d N 0 1 0 %9.5lf

time d N 0 1 0 %7.1lf

obs1 h Y 32000 0.1 0 %6.1lf

obs2 h Y 32000 0.1 0 %6.1lf

obs3 h N 0 0.1 0 %6.1lf

The rest of the steps are identical. The accepted intype flags are c fir sugned 1-byte character (-127,+128), u for unsigned byte (0-255), h for signed 2-byte integers (-32767,+32767), i for signed 4-byte integers (-2,147,483,648,+2,147,483,648), f for 4-byte floating points and d for 8-byte double precision floating points.

x2sys_binlist(1gmt) x2sys_get(1gmt) x2sys_put(1gmt)