regressors¶
Provide standalone regressor functions for DesignMatrix.
Each function takes a DesignMatrix as its first argument (dm) and returns
a new DesignMatrix with the requested transformation applied.
Methods:
| Name | Description |
|---|---|
add_dct_basis | Add discrete cosine transform basis functions for high-pass filtering. |
add_poly | Add Legendre polynomial drift terms. |
convolve | Convolve columns with an HRF or custom kernel. |
Classes¶
Methods¶
add_dct_basis¶
add_dct_basis(dm: DesignMatrix, *, duration: float = 180, drop: int = 0, include_constant: bool = True) -> DesignMatrixAdd discrete cosine transform basis functions for high-pass filtering.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dm | DesignMatrix | DesignMatrix to add DCT basis to. | required |
duration | float | Filter duration in seconds. Default: 180. | 180 |
drop | int | Number of low-frequency bases to drop. Default: 0. | 0 |
include_constant | bool | If True, also add a constant/intercept column named .nl_cosine_0 (analogous to .nl_poly_0 in add_poly). The underlying DCT basis drops the constant per SPM convention; set False to match SPM behavior. Default: True. | True |
Returns:
| Name | Type | Description |
|---|---|---|
DesignMatrix | DesignMatrix | New DesignMatrix with DCT basis columns appended, named |
DesignMatrix | .nl_cosine_{i} in the reserved namespace (see RESERVED_PREFIX). |
add_poly¶
add_poly(dm: DesignMatrix, order: int = 0, include_lower: bool = True) -> DesignMatrixAdd Legendre polynomial drift terms.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dm | DesignMatrix | DesignMatrix to add polynomials to. | required |
order | int | Polynomial order (0=intercept, 1=linear, 2=quadratic, ...). Default: 0. | 0 |
include_lower | bool | If True, include all orders from 0 to order. Default: True. | True |
Returns:
| Name | Type | Description |
|---|---|---|
DesignMatrix | DesignMatrix | New DesignMatrix with polynomial columns appended, named |
DesignMatrix | .nl_poly_{order} in the reserved namespace (see RESERVED_PREFIX). |
convolve¶
convolve(dm: DesignMatrix, conv_func: str | np.ndarray = 'hrf', columns: list[str] | None = None) -> DesignMatrixConvolve columns with an HRF or custom kernel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dm | DesignMatrix | DesignMatrix to convolve. | required |
conv_func | str or ndarray | ‘hrf’ for canonical Glover HRF, or custom kernel(s). Can be 1D array (single kernel) or 2D (samples x kernels) | ‘hrf’ |
columns | list of str | Columns to convolve (default: all non-confound columns) | None |
Returns:
| Name | Type | Description |
|---|---|---|
DesignMatrix | DesignMatrix | New DesignMatrix with convolved columns |
Examples:
>>> # Default HRF convolution → produces 'stim_c0'
>>> dm_conv = convolve(dm)>>> # Custom 1-D kernel → produces 'stim_c0'
>>> kernel = np.array([0.5, 1.0, 0.5])
>>> dm_conv = convolve(dm, conv_func=kernel)>>> # Multiple kernels (FIR model) → produces 'stim_c0', 'stim_c1'
>>> kernels = np.array([[1.0, 0.5], [0.5, 1.0]]).T # 2 kernels
>>> dm_conv = convolve(dm, conv_func=kernels)Note
Convolved columns are always renamed to <col>_c{i}; the source column is dropped. dm.convolved records the post-suffix names (the columns that actually exist in the returned dataframe), so downstream metadata propagation through .append() stays in sync with the dataframe.