eelbrain.BoostingResult

class eelbrain.BoostingResult(y, x, tstart, tstop, scale_data, delta, mindelta, error, selective_stopping, y_mean, y_scale, x_mean, x_scale, _h, _isnan, t_run, basis, basis_window, splits=None, n_samples=None, _y_info=<factory>, _y_dims=None, i_test=None, i_validate=None, l1_residual=None, l2_residual=None, l1_total=None, l2_total=None, r=None, r_rank=None, r_l1=None, train_l1_residual=None, train_l2_residual=None, train_l1_total=None, train_l2_total=None, train_r=None, train_r_rank=None, train_r_l1=None, partition_results=None, version=16, algorithm_version=-1, execution_context=None, y_pred=None, fit=None)[source]

Result from boosting

Fit metrics are computed from all time points in y.

  • For models estimated with cross-validation (test=1, the default), y_pred in each test segment is predicted from the averaged TRF from the corresponding training runs (each non-test segment used as validation set once), and the different test segments are then concatenated to compute the fit-metrics in comparison with y.

  • For models estimated with test=0, fit metrics are not computed (None), because they could only be computed from the same data that were used to estimate the TRF, and would overestimate the model’s predictive power (see the test parameter of boosting()). With partition_results=True, the fit of each run to its validation and training data is available in BoostingResult.partition_results.

Parameters:
h

The temporal response function (the average of all TRFs from the different runs/partitions). Whether h is an NDVar or a tuple of NDVar depends on whether the x parameter to boosting() was an NDVar or a sequence of NDVar.

Type:

NDVar | tuple of NDVar

h_scaled

h scaled such that it applies to the original input y and x. If boosting was done with scale_data=False, h_scaled is the same as h.

Type:

NDVar | tuple of NDVar

h_source

If h was constructed using a basis, h_source represents the source of h before being convolved with the basis.

Type:

NDVar | tuple of NDVar

h_time

Time dimension of the kernel.

Type:

UTS

r

Correlation between the measured response y and the predicted response h * x. With cross-validation (the default, boosting() with test=1), each partition of y is predicted using the h estimated from the corresponding training partitions. With test=0, r is None (see above). For vector data, measured and predicted responses are normalized, and r is computed as the average dot product over time. The type of r depends on the y parameter to boosting(): If y is one-dimensional, r is scalar, otherwise it is a NDVar. Note that r does not take into account the model’s ability to predict the magnitude of the response, only its shape; for a measure that reflects both, consider using proportion_explained.

Type:

float | eelbrain._data_obj.NDVar

r_rank

As r, the Spearman rank correlation.

Type:

float | NDVar

t_run

Time it took to run the boosting algorithm (in seconds).

Type:

float

error

The error evaluation method used.

Type:

str

residual

The residual of the final result

  • error='l1': the sum of the absolute differences between y and h * x.

  • error='l2': the sum of the squared differences between y and h * x.

For vector y, the error is defined based on the distance in space for each data point.

Type:

float | NDVar

delta

Kernel modification step used.

Type:

float

mindelta

Mindelta parameter used.

Type:

float

n_samples

Number of samples in the data described by the fit metrics (all data unless only a single test partition was evaluated).

Type:

int

proportion_explained

The proportion of the variation in y that is explained by the model. Calculated as 1 - (variation(residual) / variation(y)). Variation is caculated as the l1 or l2 norm, depending on the error that was used for model fitting. Note that this does not correspond to r**2 even for error='l2', because residuals are not guaranteed to be orthogonal to predictions. As for r, this is None for models estimated with test=0.

Type:

float | NDVar

scale_data

Scale_data parameter used.

Type:

bool

y_mean

Mean that was subtracted from y.

Type:

eelbrain._data_obj.NDVar | float

y_scale

Scale by which y was divided.

Type:

eelbrain._data_obj.NDVar | float

x_mean

Mean that was subtracted from x.

Type:

eelbrain._data_obj.NDVar | float | tuple[eelbrain._data_obj.NDVar | float, …]

x_scale

Scale by which x was divided.

Type:

eelbrain._data_obj.NDVar | float | tuple[eelbrain._data_obj.NDVar | float, …]

splits

Data splits used for cross-validation. Use Splits.plot() to visualize the cross-validation scheme.

Type:

eelbrain._trf.shared.Splits

partition_results

If boosting() is called with partition_results=True, this attribute contains the results for the individual test partitions (test=1), or for the individual validation partitions (test=0). For validation partitions, fit metrics (e.g., r) reflect the fit to the validation data, and train_* attributes the fit to the training data. Note that the fit to the validation data is also biased upward, because the validation data determined when boosting stopped. BoostingResult.partition_result_data() combines them in a Dataset.

Type:

list[eelbrain._trf._boosting.BoostingResult]

i_test

Index of the test partition whose data the fit metrics describe (see Split.i_test): set for results in BoostingResult.partition_results of models estimated with test=1, and for results from Boosting.evaluate_fit() with i_test. None when fit metrics pool all test partitions.

Type:

int

i_validate

For results in BoostingResult.partition_results of models estimated with test=0: index of the validation partition (see Split.i_validate).

Type:

int

train_r, train_r_rank, train_r_l1, train_residual, train_proportion_explained

Fit to the training data (only for results in BoostingResult.partition_results of models estimated with test=0).

algorithm_version

Version of the algorithm with which the model was estimated

  • -1: results from before this attribute was added

  • 0: Normalize x after applying basis

  • 1: Numba implementation

  • 2: Cython multiprocessing implementation (Eelbrain 0.38)

  • 3: Cython based convolution (Eelbrain 0.40)

Type:

int

execution_context

Information on the context in which the model was estimated.

Type:

dict[str, str | tuple[str, …]]

Examples

To compare the fit of models estimated with different loss metrics (error parameter) calculate the proportion of explained variance, for example:

data = datasets._get_continuous()
trf_l1 = boosting('y', 'x1', 0, 1, data=data, error='l1', partitions=3)
trf_l2 = boosting('y', 'x1', 0, 1, data=data, error='l2', partitions=3)
l1_explained_variance = 1 - (trf_l1.l2_residual / trf_l1.l2_total)
l2_explained_variance = 1 - (trf_l2.l2_residual / trf_l2.l2_total)

Methods

cross_predict([x, data, scale, name])

Predict responses to x using complementary training data

partition_result_data()

Results from the different partitions in a Dataset