|
| 1 | +""" |
| 2 | +select - Select data table subsets based on multiple spatial criteria. |
| 3 | +""" |
| 4 | +import pandas as pd |
| 5 | +from pygmt.clib import Session |
| 6 | +from pygmt.helpers import ( |
| 7 | + GMTTempFile, |
| 8 | + build_arg_string, |
| 9 | + fmt_docstring, |
| 10 | + kwargs_to_strings, |
| 11 | + use_alias, |
| 12 | +) |
| 13 | + |
| 14 | + |
| 15 | +@fmt_docstring |
| 16 | +@use_alias( |
| 17 | + A="area_thresh", |
| 18 | + D="resolution", |
| 19 | + G="gridmask", |
| 20 | + I="reverse", |
| 21 | + J="projection", |
| 22 | + N="mask", |
| 23 | + R="region", |
| 24 | + V="verbose", |
| 25 | + Z="z_subregion", |
| 26 | + b="binary", |
| 27 | + d="nodata", |
| 28 | + e="find", |
| 29 | + f="coltypes", |
| 30 | + g="gap", |
| 31 | + h="header", |
| 32 | + i="incols", |
| 33 | + o="outcols", |
| 34 | + r="registration", |
| 35 | + s="skiprows", |
| 36 | + w="wrap", |
| 37 | +) |
| 38 | +@kwargs_to_strings(M="sequence", R="sequence", i="sequence_comma", o="sequence_comma") |
| 39 | +def select(data=None, outfile=None, **kwargs): |
| 40 | + r""" |
| 41 | + Select data table subsets based on multiple spatial criteria. |
| 42 | +
|
| 43 | + This is a filter that reads (x, y) or (longitude, latitude) positions from |
| 44 | + the first 2 columns of *data* and uses a combination of 1-7 criteria to |
| 45 | + pass or reject the records. Records can be selected based on whether or not |
| 46 | + they are: |
| 47 | +
|
| 48 | + 1. inside a rectangular region (**region** [and **projection**]) |
| 49 | + 2. within *dist* km of any point in *pointfile* |
| 50 | + 3. within *dist* km of any line in *linefile* |
| 51 | + 4. inside one of the polygons in the *polygonfile* |
| 52 | + 5. inside geographical features (based on coastlines) |
| 53 | + 6. has z-values within a given range, or |
| 54 | + 7. inside bins of a grid mask whose nodes are non-zero |
| 55 | +
|
| 56 | + The sense of the tests can be reversed for each of these 7 criteria by |
| 57 | + using the **reverse** option. |
| 58 | +
|
| 59 | + Full option list at :gmt-docs:`gmtselect.html` |
| 60 | +
|
| 61 | + {aliases} |
| 62 | +
|
| 63 | + Parameters |
| 64 | + ---------- |
| 65 | + data : str or {table-like} |
| 66 | + Pass in either a file name to an ASCII data table, a 2D |
| 67 | + {table-classes}. |
| 68 | + outfile : str |
| 69 | + The file name for the output ASCII file. |
| 70 | + {A} |
| 71 | + resolution : str |
| 72 | + *resolution*\ [**+f**]. |
| 73 | + Ignored unless **mask** is set. Selects the resolution of the coastline |
| 74 | + data set to use ((**f**)ull, (**h**)igh, (**i**)ntermediate, (**l**)ow, |
| 75 | + or (**c**)rude). The resolution drops off by ~80% between data sets. |
| 76 | + [Default is **l**]. Append (**+f**) to automatically select a lower |
| 77 | + resolution should the one requested not be available [Default is abort |
| 78 | + if not found]. Note that because the coastlines differ in details it is |
| 79 | + not guaranteed that a point will remain inside [or outside] when a |
| 80 | + different resolution is selected. |
| 81 | + gridmask : str |
| 82 | + Pass all locations that are inside the valid data area of the grid |
| 83 | + *gridmask*. Nodes that are outside are either NaN or zero. |
| 84 | + reverse : str |
| 85 | + [**cflrsz**]. |
| 86 | + Reverses the sense of the test for each of the criteria specified: |
| 87 | +
|
| 88 | + - **c** select records NOT inside any point's circle of influence. |
| 89 | + - **f** select records NOT inside any of the polygons. |
| 90 | + - **g** will pass records inside the cells with z equal zero of the |
| 91 | + grid mask in **gridmask**. |
| 92 | + - **l** select records NOT within the specified distance of any line. |
| 93 | + - **r** select records NOT inside the specified rectangular region. |
| 94 | + - **s** select records NOT considered inside as specified by **mask** |
| 95 | + (and **area_thresh**, **resolution**). |
| 96 | + - **z** select records NOT within the range specified by |
| 97 | + **z_subregion**. |
| 98 | + {J} |
| 99 | + mask : str or list |
| 100 | + Pass all records whose location is inside specified geographical |
| 101 | + features. Specify if records should be skipped (s) or kept (k) using |
| 102 | + 1 of 2 formats: |
| 103 | +
|
| 104 | + - *wet/dry*. |
| 105 | + - *ocean/land/lake/island/pond*. |
| 106 | +
|
| 107 | + [Default is s/k/s/k/s (i.e., s/k), which passes all points on dry |
| 108 | + land]. |
| 109 | + {R} |
| 110 | + {V} |
| 111 | + z_subregion : str |
| 112 | + *min*\ [/*max*]\ [**+a**]\ [**+c**\ *col*]\ [**+i**]. |
| 113 | + Pass all records whose 3rd column (*z*; *col* = 2) lies within the |
| 114 | + given range or is NaN (use **skiprows** to skip NaN records). If *max* |
| 115 | + is omitted then we test if *z* equals *min* instead. This means |
| 116 | + equality within 5 ULPs (unit of least precision; |
| 117 | + http://en.wikipedia.org/wiki/Unit_in_the_last_place). Input file must |
| 118 | + have at least three columns. To indicate no limit on min or max, |
| 119 | + specify a hyphen (-). If your 3rd column is absolute time then remember |
| 120 | + to supply ``coltypes="2T"``. To specify another column, append |
| 121 | + **+c**\ *col*, and to specify several tests just repeat the |
| 122 | + **z_subregion** option as many times as you have columns to test. |
| 123 | + **Note**: When more than one **z_subregion** option is given then the |
| 124 | + ``reverse="z"`` option cannot be used. In the case of multiple tests |
| 125 | + you may use these modifiers as well: **+a** passes any record that |
| 126 | + passes at least one of your *z* tests [Default is all tests must pass], |
| 127 | + and **+i** reverses the tests to pass record with *z* value NOT in the |
| 128 | + given range. Finally, if **+c** is not used then it is automatically |
| 129 | + incremented for each new **z_subregion** option, starting with 2. |
| 130 | + {b} |
| 131 | + {d} |
| 132 | + {e} |
| 133 | + {f} |
| 134 | + {g} |
| 135 | + {h} |
| 136 | + {i} |
| 137 | + {o} |
| 138 | + {r} |
| 139 | + {s} |
| 140 | + {w} |
| 141 | +
|
| 142 | + Returns |
| 143 | + ------- |
| 144 | + output : pandas.DataFrame or None |
| 145 | + Return type depends on whether the ``outfile`` parameter is set: |
| 146 | +
|
| 147 | + - :class:`pandas.DataFrame` table if ``outfile`` is not set. |
| 148 | + - None if ``outfile`` is set (filtered output will be stored in file |
| 149 | + set by ``outfile``). |
| 150 | + """ |
| 151 | + |
| 152 | + with GMTTempFile(suffix=".csv") as tmpfile: |
| 153 | + with Session() as lib: |
| 154 | + # Choose how data will be passed into the module |
| 155 | + table_context = lib.virtualfile_from_data(check_kind="vector", data=data) |
| 156 | + with table_context as infile: |
| 157 | + if outfile is None: |
| 158 | + outfile = tmpfile.name |
| 159 | + arg_str = " ".join([infile, build_arg_string(kwargs), "->" + outfile]) |
| 160 | + lib.call_module(module="gmtselect", args=arg_str) |
| 161 | + |
| 162 | + # Read temporary csv output to a pandas table |
| 163 | + if outfile == tmpfile.name: # if user did not set outfile, return pd.DataFrame |
| 164 | + try: |
| 165 | + column_names = data.columns.to_list() |
| 166 | + result = pd.read_csv(tmpfile.name, sep="\t", names=column_names) |
| 167 | + except AttributeError: # 'str' object has no attribute 'columns' |
| 168 | + result = pd.read_csv(tmpfile.name, sep="\t", header=None, comment=">") |
| 169 | + elif outfile != tmpfile.name: # return None if outfile set, output in outfile |
| 170 | + result = None |
| 171 | + |
| 172 | + return result |
0 commit comments