"""
filter1d - Time domain filtering of 1-D data tables
"""
from typing import Literal
import numpy as np
import pandas as pd
from pygmt.clib import Session
from pygmt.exceptions import GMTInvalidInput
from pygmt.helpers import (
build_arg_list,
fmt_docstring,
use_alias,
validate_output_table_type,
)
[docs]
@fmt_docstring
@use_alias(
E="end",
F="filter_type",
N="time_col",
)
def filter1d(
data,
output_type: Literal["pandas", "numpy", "file"] = "pandas",
outfile: str | None = None,
**kwargs,
) -> pd.DataFrame | np.ndarray | None:
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
----------
{output_type}
{outfile}
filter_type : str
**type**\ *width*\ [**+h**].
Set 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
Indicate which column contains the independent variable (time). The
left-most column is 0, while the right-most is (*n_cols* - 1)
[Default is ``0``].
Returns
-------
ret
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``)
"""
if kwargs.get("F") is None:
raise GMTInvalidInput("Pass a required argument to 'filter_type'.")
output_type = validate_output_table_type(output_type, outfile=outfile)
with Session() as lib:
with (
lib.virtualfile_in(check_kind="vector", data=data) as vintbl,
lib.virtualfile_out(kind="dataset", fname=outfile) as vouttbl,
):
lib.call_module(
module="filter1d",
args=build_arg_list(kwargs, infile=vintbl, outfile=vouttbl),
)
return lib.virtualfile_to_dataset(vfname=vouttbl, output_type=output_type)