compensate Module

Utility functions related to compensation tasks

flowutils.compensate.get_spill(text)

Extracts spillover matrix from FCS text entry.

Parameters:: text – Text value from the $SPILL or $SPILLOVER metadata keyword in an FCS file
Returns:: A tuple containing: (spillover matrix new_spill, column headers)

flowutils.compensate.parse_compensation_matrix(compensation, channel_labels, null_channels=None)

Returns a NumPy array with the compensation matrix, where the first row contains the indices of the fluorescent channels

Parameters:

compensation – Compensation matrix: may be a NumPy array, a CSV file path, a pathlib Path object to a CSV or TSV file or a string of CSV text. If a string, both multi-line, traditional CSV, and the single line FCS spill formats are supported. If a NumPy array, we assume the columns are in the same order as the channel labels.
channel_labels – Channel labels from the FCS file’s PnN fields, must be in the same order as they appear in the FCS file
null_channels – Specify any empty channels that were collected and present in the channel_labels argument. These will be ignored when validating and creating the compensation matrix.

Returns:

Compensation matrix as NumPy array where header contains the channel numbers (not indices!)

flowutils.compensate.compensate(event_data, spill_matrix, fluoro_indices=None)

Compensate NumPy event data given spillover matrix.

Parameters:

event_data – NumPy array of the event data
spill_matrix – Compensation matrix as a NumPy array (without headers)
fluoro_indices – List of fluorescent channel indices in given event_data in the order found in the columns of the provided spill_matrix. Required if the number of columns in event_data does not match the spill_matrix or if the order of the columns does not match. If None (default), the event_dataa columns are assumed to match the spill_matrix columns.

Returns:

NumPy array of compensated event data. If fluoro_indices were given, the data is returned with the column order found in event_data, with the non-fluorescent columns unmodified.

flowutils.compensate.inverse_compensate(event_data, spill_matrix, fluoro_indices=None)

Inverse the compensation on NumPy event data given spillover matrix.

Parameters:

event_data – NumPy array of the event data
spill_matrix – Compensation matrix as a NumPy array (without headers)
fluoro_indices – Optional list of indices of the fluorescent channels (only these will be extracted & un-compensated). If None (default), all columns will be un-compensated.

Returns:

NumPy array of un-compensated event data. If fluoro_indices were given, the data is returned with the column order given, with the non-fluorescent columns unmodified.

flowutils.compensate.compensate_spectral_ols(event_data, spill_matrix, fluoro_indices=None)

Compensate spectral event data given a spectral spillover matrix using the ordinary least squares method (OLS). Unlike conventional flow cytometry where one detector is used per fluorochrome, spectral flow cytometry utilizes a larger number of detectors than fluorochromes, resulting in a spectral matrix that is not square, with more columns than rows. The rows (M) in the matrix correspond to the “true” fluorochromes (i.e. those detectors with dedicated fluorochromes). This function assumes the order of the columns in the matrix is such that the first M columns match the row order, and the remaining columns are the extra detectors. Also note that because of the overdetermined system, there is no inverse function for this method of compensation.

Parameters:

event_data – NumPy array of the event data
spill_matrix – Compensation matrix as a NumPy array (without headers)
fluoro_indices – Optional list of indices of the fluorescent channels (only these will be extracted & compensated). If None (default), all columns will be compensated.

Returns:

NumPy array of compensated event data. If fluoro_indices were given, the data is returned with the column order given, with the non-fluorescent columns unmodified.