opendvp.io.import_thresholds

opendvp.io.import_thresholds#

import_thresholds(gates_csv_path, sample_id=None, scimap=True)#

Read gate thresholds from a CSV file, filter, and optionally log1p-transform for scimap compatibility.

This function loads a CSV file containing gate thresholds, validates required columns, filters out rows with gate values of 0.0 (assumed not gated), optionally selects gates for a specific sample, and can log1p-transform gate values for downstream analysis (e.g., scimap). Logs progress and summary information.

Parameters:

  • gates_csv_path (str or pathlib.Path) – Path to the CSV file containing gate thresholds. Must end with ‘.csv’.

  • sample_id (str or int, optional) – If provided, only gates for this sample will be returned and the output column will be named accordingly.

  • scimap (bool, default True) – If True, applies log1p transformation and column rename, formatting the output for scimap.

Returns:

Filtered DataFrame containing valid gates, with columns ‘markers’ and the sample_id (if scimap=True), or the original columns if scimap=False.

Return type:

pandas.DataFrame

Raises:

ValueError – If the file extension is not ‘.csv’, or required columns are missing.

Examples

>>> gates = import_thresholds("gates.csv", sample_id="sample1", scimap=True)
>>> print(gates.head())
Contents