Skip to content

Result Containers

Several TRF methods return lightweight dataclass-based containers instead of bare tuples. These objects make it easier to keep related arrays together.

Why These Containers Exist

They serve three purposes:

  • they document the shape and meaning of returned arrays
  • they provide small convenience methods such as at(...)
  • they keep related metadata, such as band centers or phase units, attached to the data they describe

CrossSpectralDiagnostics is a public alias of TRFDiagnostics, so users can choose whichever name reads more naturally in their code.

Containers

fftrf.TRFDiagnostics dataclass

Observed-vs-predicted spectral diagnostics for a fitted model.

This container is returned by :meth:fftrf.TRF.cross_spectral_diagnostics and groups together the most useful frequency-domain quantities for checking how well a fitted model reproduces the spectral structure of the observed targets.

Attributes:

Name Type Description
frequencies ndarray

Frequency vector in Hz.
transfer_function ndarray

Complex transfer function copied from the fitted model. Shape is (n_frequencies, n_inputs, n_outputs).
predicted_spectrum ndarray

Diagonal auto-spectrum of the model predictions for each output. Shape is (n_frequencies, n_outputs).
observed_spectrum ndarray

Diagonal auto-spectrum of the observed targets. Shape is (n_frequencies, n_outputs).
cross_spectrum ndarray

Matched predicted-vs-observed cross-spectrum for each output. Shape is (n_frequencies, n_outputs).
coherence ndarray

Magnitude-squared coherence between each predicted output and the corresponding observed target. Shape is (n_frequencies, n_outputs).
Notes

The spectra are computed with the same segmentation, FFT length, window, and optional trial weighting that the estimator uses for its fitted model, unless explicitly overridden at call time.

fftrf.PermutationTestResult dataclass

Permutation-based significance test result for held-out prediction scores.

This container is returned by :meth:fftrf.TRF.permutation_test and keeps the observed prediction score together with the surrogate null distribution used to assess significance.

Attributes:

Name Type Description
observed_score ndarray | float

Score computed on the original aligned evaluation data. This follows the same scalar-vs-array contract as :meth:fftrf.TRF.score: a scalar when scores are averaged and one value per output when average=False.
null_scores ndarray

Aggregated surrogate scores from all permutations. Shape is (n_permutations,) when the score is aggregated to one scalar and (n_permutations, n_outputs) when average=False.
p_value ndarray | float

Permutation p-value(s) computed from :attr:null_scores.
z_score ndarray | float

Standardized score relative to the null distribution mean and standard deviation.
tail str

Tail convention used for the p-value calculation: "greater", "less", or "two-sided".
surrogate str

Surrogate data strategy used to construct the null distribution, for example "circular_shift" or "trial_shuffle".
n_permutations int

Number of surrogate scores stored in :attr:null_scores.

fftrf.FrequencyResolvedWeights dataclass

Frequency-resolved time-domain view of a fitted transfer function.

Attributes:

Name Type Description
frequencies ndarray

Original frequency vector of the fitted transfer function in Hz.
band_centers ndarray

Center frequency of each analysis band in Hz.
filters ndarray

Frequency-domain filter bank used to partition the transfer function. Shape is (n_frequencies, n_bands).
times ndarray

Lag vector in seconds corresponding to the third axis of :attr:weights.
weights ndarray

Frequency-resolved kernel tensor with shape (n_inputs, n_bands, n_lags, n_outputs).
scale str

Spacing used for :attr:band_centers, either "linear" or "log".
value_mode str

Representation stored in :attr:weights. "real" preserves the signed band-limited kernels, "magnitude" stores their absolute value, and "power" stores squared magnitude.
bandwidth float

Gaussian filter width in Hz used for the analysis bands.

at(*, input_index=0, output_index=0)

Return one frequency-by-lag map from the resolved kernel bank.

Parameters:

Name Type Description Default
input_index int

Select the predictor/target pair to extract from the stored 4D tensor.

 0
output_index int

Select the predictor/target pair to extract from the stored 4D tensor.

 0

Returns:

Type Description
ndarray

Array with shape (n_bands, n_lags) for the requested input/output pair.

fftrf.TimeFrequencyPower dataclass

Spectrogram-like time-frequency power derived from a fitted kernel.

This container is returned by :meth:fftrf.TRF.time_frequency_power. It mirrors :class:FrequencyResolvedWeights but stores a smoothed positive power representation instead of signed band-limited kernels.

Attributes:

Name Type Description
frequencies ndarray

Original frequency vector of the fitted transfer function in Hz.
band_centers ndarray

Center frequency of each analysis band in Hz.
filters ndarray

Frequency-domain filter bank used to partition the transfer function. Shape is (n_frequencies, n_bands).
times ndarray

Lag vector in seconds corresponding to the third axis of :attr:power.
power ndarray

Time-frequency power tensor with shape (n_inputs, n_bands, n_lags, n_outputs).
scale str

Spacing used for :attr:band_centers, either "linear" or "log".
method str

Power-estimation method. Currently "hilbert" computes the squared magnitude of the analytic signal for each band-limited kernel.
bandwidth float

Gaussian filter width in Hz used for the analysis bands.

at(*, input_index=0, output_index=0)

Return one frequency-by-lag power map.

Parameters:

Name Type Description Default
input_index int

Select the predictor/target pair to extract from the stored power tensor.

 0
output_index int

Select the predictor/target pair to extract from the stored power tensor.

 0

Returns:

Type Description
ndarray

Array with shape (n_bands, n_lags) for the requested input/output pair.

fftrf.TransferFunctionComponents dataclass

Derived one-pair transfer-function quantities.

This container is returned by :meth:fftrf.TRF.transfer_function_components_at and is meant for one selected input/output pair.

Attributes:

Name Type Description
frequencies ndarray

Frequency vector in Hz.
transfer_function ndarray

Complex transfer-function values for one input/output pair.
magnitude ndarray

Absolute value of the transfer function.
phase ndarray

Unwrapped transfer-function phase, reported in the requested units.
phase_unit str

Unit used for :attr:phase, either "rad" or "deg".
group_delay ndarray

Group delay derived from the unwrapped phase, expressed in seconds.
Notes

Group delay is often easiest to interpret away from frequencies where the transfer-function magnitude is extremely small, because phase-based quantities can become noisy when the complex response approaches zero.