[comment {-*- tcl -*- doctools manpage}]
[manpage_begin math::filters n 0.1]
[keywords digital]
[keywords filtering]
[copyright {2020 by Arjen Markus}]
[moddesc   {Tcl Math Library}]
[titledesc {Digital filters}]
[category  Mathematics]
[require Tcl 8.6]
[require TclOO]
[require math::filters [opt 0.1]]

[description]
[para]
The [package math::filters] package implements digital filters,
notably Butterworth low-pass and high-pass filters. The procedures
allow to filter an entire data series as well as filter data one
by one.


[section "PROCEDURES"]

The package defines the following public procedures:

[list_begin definitions]

[call [cmd ::math::filters::filterButterworth] [arg lowpass] [arg order] [arg samplefreq] [arg cutofffreq]]

Determine the coefficients for a Butterworth filter of given order. The coefficients are returned as
a list of the x-coefficients, the y-coefficients and the scale. The formula is (n is the filter order):
[example {
                   n             n
    scale * y_k = sum x_(k-i) + sum y_(k-i)
                  i=0           i=1
}]

[list_begin arguments]
[arg_def bool lowpass] Generate a low-pass filter (1) or a high-pass filter (0)
[arg_def integer lowpass] The order of the filter to be generated
[arg_def double samplefreq] Sampling frequency of the data series
[arg_def double cutofffreq] Cut-off frequency for the filter
[list_end]


[call [cmd ::math::filters::filter] [arg coeffs] [arg data]]

Filter the entire data series based on the filter coefficients.

[list_begin arguments]
[arg_def list coeffs] List of coefficients as generated by [emph filterButterworth] (or in fact any similar list of coefficients)
[arg_def list data] Data to be filtered
[list_end]


[call [cmd ::math::filters::filterObj] new [arg coeffs] [arg yinit]]

Create a filter object. The initial x data are taken as zero. The initial y data can be prescribed. If they are not given,
they are taken as zero as well.

[list_begin arguments]
[arg_def list coeffs] List of coefficients as generated by [emph filterButterworth] (or in fact any similar list of coefficients)
[arg_def list yinit] (Optional) initial data for the filter result.
[list_end]


[call [cmd \$filterObj] filter [arg x]]

Filter a single value and return the result.

[list_begin arguments]
[arg_def double x] The value to be filtered
[list_end]


[call [cmd \$filterObj] reset]

Reset the filter object (start anew)

[list_end]

[manpage_end]