Preprocessing Helpers

ffTRF intentionally keeps preprocessing lightweight. The helpers below are small utilities for common signal-preparation tasks that often come up before TRF fitting.

Typical Use Cases

split a waveform into positive and negative half-wave regressors
resample derived regressors to match the target sampling rate
compute heuristic inverse-variance trial weights in controlled cases where total variance is a defensible proxy for noise

These helpers do not try to replace a full preprocessing pipeline. They are meant to cover the small but common operations that are convenient to keep next to the estimator API. In particular, inverse-variance weighting is not a general data-quality estimator: genuine neural effects can change trial variance too. Compare it with an unweighted fit and prefer prespecified artifact or noise measures when available.

`fftrf.half_wave_rectify(signal)`

Split a waveform into positive and negative half-wave components.

Parameters:

Name	Type	Description	Default
`signal`	`ndarray`	One-dimensional waveform, envelope, or other continuous regressor. Values above zero are routed into the positive output and values below zero are routed into the negative output. The input is converted to a floating-point NumPy array before the split is performed.	required

Returns:

Type	Description
`positive, negative:`	Arrays with the same shape as `signal`. `positive` contains the positive half-wave and `negative` contains the magnitude of the negative half-wave. Both outputs are non-negative. At every sample, exactly one of them is non-zero unless the original sample value is zero.

Notes

Modeling positive and negative polarities separately can be useful when the sign of a waveform carries different predictive structure. A common use case is constructing separate regressors for compression-like or rectification-like hypotheses in auditory models without losing the timing of the original waveform.

`fftrf.resample_signal(signal, orig_fs, target_fs, axis=0, max_denominator=10000)`

Resample a signal using polyphase filtering.

Parameters:

Name	Type	Description	Default
`signal`	`ndarray`	Input signal or array. The function accepts 1D or multi-dimensional arrays and only resamples along `axis`.	required
`orig_fs`	`float`	Original sampling rate in Hz. This must describe the spacing of the samples already present in `signal`.	required
`target_fs`	`float`	Target sampling rate in Hz. The returned array is sampled on this new grid.	required
`axis`	`int`	Axis along which resampling should be performed. By default the helper assumes the first axis is time, which matches the rest of `ffTRF`.	`0`
`max_denominator`	`int`	Controls the rational approximation used to derive the integer up/down factors for :func:`scipy.signal.resample_poly`. Larger values allow a closer approximation when the ratio between `orig_fs` and `target_fs` is not a simple rational number, at the cost of a more complex resampling filter.	`10000`

Returns:

Type	Description
`ndarray`	Resampled signal with the same number of non-time dimensions as the input.

Notes

This is a practical helper for bringing derived regressors to the same sampling rate as the target signal before fitting a model. Polyphase resampling is usually preferable to naive interpolation because it combines rate conversion with proper anti-alias filtering.

`fftrf.inverse_variance_weights(trials)`

Compute normalized inverse-variance weights for a list of trials.

Parameters:

Name	Type	Description	Default
`trials`	`Sequence[ndarray]`	Sequence of trial arrays. Each trial may be 1D or 2D. For 2D arrays, the variance is averaged across columns to obtain one scalar variance estimate per trial. Trials with larger variance therefore receive smaller weights.	required

Returns:

Type	Description
`ndarray`	One normalized weight per trial. The weights sum to 1 and can be passed directly to `TRF.train(..., trial_weights=weights)`.

Notes

This helper is intentionally simple: it treats total variance as a proxy for trial noisiness and does not estimate structured noise covariance. Neural or evoked signal differences can also change total variance, so these weights are a heuristic rather than a general default. Use them only when larger variance is defensibly attributable to poorer data quality, compare against an unweighted fit, and report the weighting rule.

Variance is averaged across channels/features before the inverse is taken.