`append`¶

Provide standalone DesignMatrix concatenation functions.

These functions implement the append/concatenation logic extracted from DesignMatrix methods, following the “functional core” pattern.

Methods:

Name	Description
`append`	Concatenate design matrices.
`append_horizontal`	Concatenate matrices horizontally by adding columns.
`append_vertical`	Concatenate matrices vertically with optional confound separation.
`append_vertical_with_separation`	Concatenate vertically with automatic confound separation.
`get_starting_run_idx`	Determine the next run index for multi-run appending.
`identify_columns_to_separate`	Identify columns that need run-specific separation.
`match_column_pattern`	Match columns against a pattern with wildcard support.

Classes¶

Methods¶

`append`¶

append(dm: DesignMatrix, other: DesignMatrix, *, axis: int = 0, keep_separate: bool = True, unique_cols: list[str] | None = None, fill_na: int | float | None = 0, as_confounds: bool = False, progress_bar: bool = False) -> DesignMatrix

Concatenate design matrices.

Parameters:

Name	Type	Description	Default
`dm`	`DesignMatrix`	The base design matrix.	required
`other`	`DesignMatrix, DataFrame, or list`	Matrix/matrices to append. For `axis=1` (horizontal), also accepts a pandas or polars DataFrame (or list thereof); the new columns are treated as nuisance regressors (tracked in `.confounds` on the result). For `axis=0` (vertical), all items must be `DesignMatrix`.	required
`axis`	`int`	0 for row-wise (vertical), 1 for column-wise (horizontal).	`0`
`keep_separate`	`bool`	Whether to separate confound columns across runs (only axis=0).	`True`
`unique_cols`	`list of str`	Additional columns to keep separated (supports wildcards).	`None`
`fill_na`	`int, float, or None`	Value to fill NaN/null entries introduced by the concatenation. Pass `None` to preserve nulls. Default: 0.	`0`
`as_confounds`	`bool`	Only applies to `axis=1`. When True, all columns contributed by `other` are tracked as nuisance regressors in the result’s `.confounds` — so they’re skipped by `.convolve()` and kept separate across runs in later vertical appends. Useful when `other` is a pre-built DesignMatrix of confounds that hasn’t already marked its columns. Default: False.	`False`
`progress_bar`	`bool`	Print messages about confound separation. Default: False.	`False`

Returns:

Name	Type	Description
`DesignMatrix`	`DesignMatrix`	Concatenated design matrix.

`append_horizontal`¶

append_horizontal(dm: DesignMatrix, to_append: list[DesignMatrix], fill_na: int | float | None, as_confounds: bool = False) -> DesignMatrix

Concatenate matrices horizontally by adding columns.

Parameters:

Name	Type	Description	Default
`dm`	`DesignMatrix`	Base DesignMatrix instance.	required
`to_append`	`list of DesignMatrix`	Matrices whose columns to add.	required
`fill_na`	`int, float, or None`	Value to fill NaN/null entries with. Pass `None` to preserve nulls.	required
`as_confounds`	`bool`	If True, mark all columns contributed by `to_append` as nuisance/confounds in the result.	`False`

Returns:

Name	Type	Description
`DesignMatrix`	`DesignMatrix`	New DesignMatrix with columns from all matrices.

`append_vertical`¶

append_vertical(dm: DesignMatrix, to_append: list[DesignMatrix], keep_separate: bool, unique_cols: list[str] | None, fill_na: int | float | None, *, progress_bar: bool) -> DesignMatrix

Concatenate matrices vertically with optional confound separation.

Parameters:

Name	Type	Description	Default
`dm`	`DesignMatrix`	Base DesignMatrix instance.	required
`to_append`	`list of DesignMatrix`	Matrices to stack below dm.	required
`keep_separate`	`bool`	Whether to separate confound columns across runs.	required
`unique_cols`	`list of str`	Additional columns to keep separated (supports wildcards).	required
`fill_na`	`int, float, or None`	Value to fill NaN/null entries with. Pass `None` to preserve nulls.	required
`progress_bar`	`bool`	Print messages about confound separation.	required

Returns:

Name	Type	Description
`DesignMatrix`	`DesignMatrix`	New DesignMatrix with rows from all matrices.

`append_vertical_with_separation`¶

append_vertical_with_separation(dm: DesignMatrix, to_append: list[DesignMatrix], unique_cols: list[str] | None, fill_na: int | float | None, *, progress_bar: bool) -> DesignMatrix

Concatenate vertically with automatic confound separation.

Creates run-specific columns (e.g., .nl_r0_poly_0, .nl_r1_poly_0) that are active only in their respective runs (sparse representation).

Parameters:

Name	Type	Description	Default
`dm`	`DesignMatrix`	Base DesignMatrix instance.	required
`to_append`	`list of DesignMatrix`	Matrices to stack below dm.	required
`unique_cols`	`list of str`	Additional columns to keep separated (supports wildcards).	required
`fill_na`	`int, float, or None`	Value to fill NaN/null entries with. Pass `None` to preserve nulls.	required
`progress_bar`	`bool`	Print messages about confound separation.	required

Returns:

Name	Type	Description
`DesignMatrix`	`DesignMatrix`	Concatenated DesignMatrix with run-separated confound columns and multi=True.

`get_starting_run_idx`¶

get_starting_run_idx(dm: DesignMatrix) -> int

Determine the next run index for multi-run appending.

Parameters:

Name	Type	Description	Default
`dm`	`DesignMatrix`	DesignMatrix instance to inspect.	required

Returns:

Name	Type	Description
`int`	`int`	Next run index (0 if not multi-run, max_existing_idx + 1 otherwise).

`identify_columns_to_separate`¶

identify_columns_to_separate(dm: DesignMatrix, all_dms: list[DesignMatrix], unique_cols: list[str] | None) -> set

Identify columns that need run-specific separation.

Parameters:

Name	Type	Description	Default
`dm`	`DesignMatrix`	The base design matrix (used for context only).	required
`all_dms`	`list of DesignMatrix`	All matrices being concatenated.	required
`unique_cols`	`list of str`	User-specified columns to separate (supports wildcards).	required

Returns:

Name	Type	Description
`set`	`set`	Column names that should be separated with run prefixes.

`match_column_pattern`¶

match_column_pattern(columns: list[str], pattern: str) -> list[str]

Match columns against a pattern with wildcard support.

Parameters:

Name	Type	Description	Default
`columns`	`list of str`	Column names to search.	required
`pattern`	`str`	Pattern to match (supports ‘’ as wildcard). - 'motion’ matches motion_x, motion_y - ‘*_motion’ matches x_motion, y_motion - ‘exact’ matches only ‘exact’	required

Returns:

Type	Description
`list [ str ]`	list of str: Column names matching the pattern.

append

append¶

Classes¶

Methods¶

append¶

append_horizontal¶

append_vertical¶

append_vertical_with_separation¶

get_starting_run_idx¶

identify_columns_to_separate¶

match_column_pattern¶

`append`¶

`append`¶

`append_horizontal`¶

`append_vertical`¶

`append_vertical_with_separation`¶

`get_starting_run_idx`¶

`identify_columns_to_separate`¶

`match_column_pattern`¶