"""filter1d - Time domain filtering of 1-D data tables"""importwarningsimportpandasaspdfrompygmt.clibimportSessionfrompygmt.exceptionsimportGMTInvalidInputfrompygmt.helpersimportGMTTempFile,build_arg_string,fmt_docstring,use_alias
[docs]@fmt_docstring@use_alias(E="end",F="filter_type",N="time_col",)deffilter1d(data,output_type="pandas",outfile=None,**kwargs):r""" Time domain filtering of 1-D data tables. A general time domain filter for multiple column time series data. The user specifies which column is the time (i.e., the independent variable) via ``time_col``. The fastest operation occurs when the input time series are equally spaced and have no gaps or outliers and the special options are not needed. Read a table and output as a :class:`numpy.ndarray`, :class:`pandas.DataFrame`, or ASCII file. Full option list at :gmt-docs:`filter1d.html` {aliases} Parameters ---------- filter_type : str **type**\ *width*\ [**+h**]. Sets the filter **type**. Choose among convolution and non-convolution filters. Append the filter code followed by the full filter *width* in same units as time column. By default, this performs a low-pass filtering; append **+h** to select high-pass filtering. Some filters allow for optional arguments and a modifier. Available convolution filter types are: - (**b**) Boxcar: All weights are equal. - (**c**) Cosine Arch: Weights follow a cosine arch curve. - (**g**) Gaussian: Weights are given by the Gaussian function. - (**f**) Custom: Instead of *width* give name of a one-column file with your own weight coefficients. Non-convolution filter types are: - (**m**) Median: Returns median value. - (**p**) Maximum likelihood probability (a mode estimator): Return modal value. If more than one mode is found we return their average value. Append **+l** or **+u** if you rather want to return the lowermost or uppermost of the modal values. - (**l**) Lower: Return the minimum of all values. - (**L**) Lower: Return minimum of all positive values only. - (**u**) Upper: Return maximum of all values. - (**U**) Upper: Return maximum of all negative values only. Upper case type **B**, **C**, **G**, **M**, **P**, **F** will use robust filter versions: i.e., replace outliers (2.5 L1 scale off median, using 1.4826 \* median absolute deviation [MAD]) with median during filtering. In the case of **L**\|\ **U** it is possible that no data passes the initial sign test; in that case the filter will return 0.0. Apart from custom coefficients (**f**), the other filters may accept variable filter widths by passing *width* as a two-column time-series file with filter widths in the second column. The filter-width file does not need to be co-registered with the data as we obtain the required filter width at each output location via interpolation. For multi-segment data files the filter file must either have the same number of segments or just a single segment to be used for all data segments. end : bool Include ends of time series in output. The default [False] loses half the filter-width of data at each end. time_col : int Indicates which column contains the independent variable (time). The left-most column is 0, while the right-most is (*n_cols* - 1) [Default is 0]. output_type : str Determine the format the xyz data will be returned in [Default is ``pandas``]: - ``numpy`` - :class:`numpy.ndarray` - ``pandas``- :class:`pandas.DataFrame` - ``file`` - ASCII file (requires ``outfile``) outfile : str The file name for the output ASCII file. Returns ------- ret : pandas.DataFrame or numpy.ndarray or None Return type depends on ``outfile`` and ``output_type``: - None if ``outfile`` is set (output will be stored in file set by ``outfile``) - :class:`pandas.DataFrame` or :class:`numpy.ndarray` if ``outfile`` is not set (depends on ``output_type`` [Default is :class:`pandas.DataFrame`]) """ifkwargs.get("F")isNone:raiseGMTInvalidInput("Pass a required argument to 'filter_type'.")ifoutput_typenotin["numpy","pandas","file"]:raiseGMTInvalidInput("Must specify format as either numpy, pandas, or file.")ifoutfileisnotNoneandoutput_type!="file":msg=(f"Changing `output_type` of filter1d from '{output_type}' to 'file' ""since `outfile` parameter is set. Please use `output_type='file'` ""to silence this warning.")warnings.warn(msg,category=RuntimeWarning,stacklevel=2)output_type="file"elifoutput_type=="file"andoutfileisNone:raiseGMTInvalidInput("Must specify outfile for ASCII output.")withGMTTempFile()astmpfile:withSession()aslib:file_context=lib.virtualfile_from_data(check_kind="vector",data=data)withfile_contextasinfile:ifoutfileisNone:outfile=tmpfile.namelib.call_module(module="filter1d",args=build_arg_string(kwargs,infile=infile,outfile=outfile),)# Read temporary csv output to a pandas tableifoutfile==tmpfile.name:# if user did not set outfile, return pd.DataFrameresult=pd.read_csv(tmpfile.name,sep="\t",comment=">")elifoutfile!=tmpfile.name:# return None if outfile set, output in outfileresult=Noneifoutput_type=="numpy":result=result.to_numpy()returnresult