create_censor_mask

bidsaid.qc.create_censor_mask(input_data, column_name=None, threshold=None, n_dummy_scans=0, has_header=True, verbose=False)[source]

Create a censor mask where 0 indicates volumes to censor and 1 indicates volumes to keep.

Parameters

input_datastr, Path, pandas.DataFrame, or NDArray: Input data containing values to threshold. Can be a path to a text file (where delimiter is whitespace, tabs, or commas), a DataFrame, or a 1D numpy array.
column_namestr or None, default=None: Name of the column to extract from DataFrame or file. If None and input is a DataFrame/file, uses the first column.
thresholdfloat or None, default=None: Values exceeding this threshold will be censored (set to 0 in mask). If None, no threshold-based censoring is applied.
n_dummy_scansint, default=0: Number of non-steady-state scans to censor.
has_headerbool, default=True: Whether the input file has a header row. Only used when input_data is a file path.
verbosebool, default=False: Logs “INFO” level information if True.

Returns

NDArray: Binary mask array where 1 = keep, 0 = censor.

Examples

Censor only dummy scans:

>>> censor_mask = create_censor_mask(data, n_dummy_scans=4)

Censor based on framewise displacement threshold:

>>> censor_mask = create_censor_mask(
...            confounds_df,
...            column_name="framewise_displacement",
...            threshold=0.5
...            )

Censor both dummy scans and high motion volumes:

>>> censor_mask = create_censor_mask(
...            "confounds.tsv",
...            column_name="framewise_displacement",
...            threshold=0.5,
...            n_dummy_scans=4
...            )