diff --git a/pygmt/x2sys.py b/pygmt/x2sys.py index 064ecdb2c43..5cd1efeec2d 100644 --- a/pygmt/x2sys.py +++ b/pygmt/x2sys.py @@ -72,16 +72,15 @@ def x2sys_init(tag, **kwargs): r""" Initialize a new x2sys track database. - x2sys_init is the starting point for anyone wishing to use x2sys; it - initializes a set of data bases that are particular to one kind of track - data. These data, their associated data bases, and key parameters are given - a short-hand notation called an x2sys TAG. The TAG keeps track of settings - such as file format, whether the data are geographic or not, and the - binning resolution for track indices. + Serves as the starting point for x2sys and initializes a set of data bases + that are particular to one kind of track data. These data, their associated + data bases, and key parameters are given a short-hand notation called an + x2sys TAG. The TAG keeps track of settings such as file format, whether the + data are geographic or not, and the binning resolution for track indices. - Before you can run x2sys_init you must set the environmental parameter - X2SYS_HOME to a directory where you have write permission, which is where - x2sys can keep track of your settings. + Before you can run :meth:`pygmt.x2sys_init` you must set the environmental + parameter X2SYS_HOME to a directory where you have write permission, which + is where x2sys can keep track of your settings. Full option list at :gmt-docs:`supplements/x2sys/x2sys_init.html` @@ -93,56 +92,57 @@ def x2sys_init(tag, **kwargs): The unique name of this data type x2sys TAG. fmtfile : str - Format definition file prefix for this data set [See Format Definition - Files for more information]. Specify full path if the file is not in - the current directory. + Format definition file prefix for this data set (see + :gmt-docs:`GMT's Format Definition Files + ` + for more information). Specify full path if the file is not in the + current directory. Some file formats already have definition files premade. These include: - - mgd77 (for plain ASCII MGD77 data files) - - mgd77+ (for enhanced MGD77+ netCDF files) - - gmt (for old mgg supplement binary files) - - xy (for plain ASCII x, y tables) - - xyz (same, with one z-column) - - geo (for plain ASCII longitude, latitude files) - - geoz (same, with one z-column). + - **mgd77** (for plain ASCII MGD77 data files) + - **mgd77+** (for enhanced MGD77+ netCDF files) + - **gmt** (for old mgg supplement binary files) + - **xy** (for plain ASCII x, y tables) + - **xyz** (same, with one z-column) + - **geo** (for plain ASCII longitude, latitude files) + - **geoz** (same, with one z-column). suffix : str Specifies the file extension (suffix) for these data files. If not given we use the format definition file prefix as the suffix (see - *fmtfile*). + ``fmtfile``). discontinuity : str **d**\|\ **g**. Selects geographical coordinates. Append **d** for discontinuity at the - Dateline (makes longitude go from -180 to + 180) or **g** for + Dateline (makes longitude go from -180 to +180) or **g** for discontinuity at Greenwich (makes longitude go from 0 to 360 [Default]). If not given we assume the data are Cartesian. spacing : str or list *dx*\[/*dy*]. - *dx* [and optionally *dy*] is the grid spacing. Append **m** to + *dx* and optionally *dy* is the grid spacing. Append **m** to indicate minutes or **s** to indicate seconds for geographic data. These spacings refer to the binning used in the track bin-index data base. units : str or list - **d**\|\ **s**\ - **c**\|\ **e**\|\ **f**\|\ **k**\|\ **m**\|\ **n**\|\ **u** . + **d**\|\ **s**\ *unit*. Sets the units used for distance and speed when requested by other programs. Append **d** for distance or **s** for speed, then give the - desired unit as: + desired *unit* as: - **c** - Cartesian userdist or userdist/usertime - **e** - meters or m/s - **f** - feet or feet/s - - **k** - km or kms/hr + - **k** - km or km/hr - **m** - miles or miles/hr - **n** - nautical miles or knots - **u** - survey feet or survey feet/s - Default is ``units=["dk", "se"]`` (km and m/s) if *discontinuity* is - set, and ``units=["dc", "sc"]`` otherwise (Cartesian units). + [Default is ``units=["dk", "se"]`` (km and m/s) if ``discontinuity`` is + set, and ``units=["dc", "sc"]`` otherwise (e.g., for Cartesian units)]. {R} {V} @@ -150,11 +150,11 @@ def x2sys_init(tag, **kwargs): gap : str or list **t**\|\ **d**\ *gap*. Give **t** or **d** and append the corresponding maximum time gap (in - user units; this is typically seconds [Infinity]), or distance (for - units, see ``units``) gap [Default is infinity]) allowed between the - two data points immediately on either side of a crossover. If these - limits are exceeded then a data gap is assumed and no COE will be - determined. + user units; this is typically seconds [Default is infinity]), or + distance (for units, see ``units``) gap [Default is infinity]) allowed + between the two data points immediately on either side of a crossover. + If these limits are exceeded then a data gap is assumed and no COE will + be determined. {j} """ @@ -182,13 +182,13 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): r""" Calculate crossovers between track data files. - x2sys_cross is used to determine all intersections between ("external - cross-overs") or within ("internal cross-overs") tracks (Cartesian or - geographic), and report the time, position, distance along track, heading - and speed along each track segment, and the crossover error (COE) and mean - values for all observables. By default, x2sys_cross will look for both - external and internal COEs. As an option, you may choose to project all - data using one of the map-projections prior to calculating the COE. + Determines all intersections between ("external cross-overs") or within + ("internal cross-overs") tracks (Cartesian or geographic), and report the + time, position, distance along track, heading and speed along each track + segment, and the crossover error (COE) and mean values for all observables. + By default, :meth:`pygmt.x2sys_cross` will look for both external and + internal COEs. As an option, you may choose to project all data using one + of the map projections prior to calculating the COE. Full option list at :gmt-docs:`supplements/x2sys/x2sys_cross.html` @@ -207,7 +207,7 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): in the current directory and second in all directories listed in $X2SYS_HOME/TAG/TAG_paths.txt (if it exists). [If $X2SYS_HOME is not set it will default to $GMT_SHAREDIR/x2sys]. (Note: MGD77 files will - also be looked for via $MGD77_HOME/mgd77_paths.txt and \\*.gmt files + also be looked for via $MGD77_HOME/mgd77_paths.txt and .gmt files will be searched for via $GMT_SHAREDIR/mgg/gmtfile_paths). outfile : str @@ -221,7 +221,8 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): combitable : str Only process the pair-combinations found in the file *combitable* [Default process all possible combinations among the specified files]. - The file *combitable* is created by *x2sys_get*'s -L option + The file *combitable* is created by :gmt-docs:`x2sys_get's -L option + `. runtimes : bool or str Compute and append the processing run-time for each pair to the @@ -230,7 +231,8 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): is to use the knowledge of run-times to split the main process in a number of sub-processes that can each be launched in a different processor of your multi-core machine. See the MATLAB function - split_file4coes.m that lives in the x2sys supplement source code. + `split_file4coes.m + `_. override : bool or str **S**\|\ **N**. @@ -238,7 +240,7 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): unaffected). By default, we determine if the data are closer to one pole than the other, and then we use a cylindrical polar conversion to avoid problems with longitude jumps. You can turn this off entirely - with *override* and then the calculations uses the original data (we + with ``override`` and then the calculations uses the original data (we have protections against longitude jumps). However, you can force the selection of the pole for the projection by appending **S** or **N** for the south or north pole, respectively. The conversion is used @@ -267,10 +269,10 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): not calculate a COE. Specify: - **l** sets lower speed [Default is 0]. - - **u** sets upper speed [Default is Infinity]. - - **h** does not limit the speed but sets a lower speed below which \ - headings will not be computed (i.e., set to NaN) [Default calculates \ - headings regardless of speed]. + - **u** sets upper speed [Default is infinity]. + - **h** does not limit the speed but sets a lower speed below which + headings will not be computed (i.e., set to NaN) [Default + calculates headings regardless of speed]. For example, you can use ``speed=["l0", "u10", "h5"]`` to set a lower speed of 0, upper speed of 10, and disable heading calculations for @@ -288,12 +290,14 @@ def x2sys_cross(tracks=None, outfile=None, **kwargs): Returns ------- - crossover_errors : pandas.DataFrame or None + crossover_errors : :class:`pandas.DataFrame` or None Table containing crossover error information. - Return type depends on whether the outfile parameter is set: + Return type depends on whether the ``outfile`` parameter is set: - - pandas.DataFrame table with (x, y, ..., etc) if outfile is not set - - None if outfile is set (track output will be stored in outfile) + - :class:`pandas.DataFrame` with (x, y, ..., etc) if ``outfile`` is not + set + - None if ``outfile`` is set (track output will be stored in the set in + ``outfile``) """ with Session() as lib: file_contexts = []