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 simple inverse-variance trial weights for noisy multi-trial data

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.

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 variance as a proxy for trial noisiness and does not attempt to estimate structured noise covariance. It is a good default when some trials are visibly noisier than others and you want those trials to contribute less to the aggregate cross-spectra during fitting or bootstrap diagnostics.

Variance is averaged across channels/features so noisier trials contribute less to the final fit.