Skip to content

Compensations

CellEngine API: Compensations

A compensation is a list of channel names and a corresponding square matrix. The matrix is technically a "spill" or "spillover" matrix, which is inverted to yield the compensation matrix; most applications refer to the spill matrix as a compensation matrix, however.

In the Python SDK, the matrix is represented by a Pandas DataFrame.

Properties

Properties are getter methods and setter methods representing the underlying CellEngine object. Properties are the snake_case equivalent of those documented on the CellEngine API unless otherwise noted.

Special Constants

cellengine.UNCOMPENSATED: UncompensatedType = 0 module-attribute

Apply no compensation.

cellengine.FILE_INTERNAL: FileInternalType = -1 module-attribute

Use the file's internal compensation matrix, if available. If not available, an error will be returned from API requests.

cellengine.PER_FILE: PerFileType = -2 module-attribute

Use the compensation assigned to each individual FCS file. Not a valid value for FcsFile.compensation.

Methods

cellengine.resources.compensation.Compensation

A class representing a CellEngine compensation matrix.

N property

channels: List[str] property writable

dataframe: DataFrame property writable

dataframe_as_html property

Return the compensation matrix dataframe as HTML.

experiment_id: str property

id: str property

Alias for _id.

name: str property writable

spill_matrix: List[float] property writable

apply(file, inplace=True, **kwargs) 

apply(
    file: FcsFile, inplace: Literal[True] = ..., **kwargs
) -> None

apply(
    file: FcsFile, inplace: Literal[False] = ..., **kwargs
) -> DataFrame

Compensate an FcsFile's data.

Parameters:

Name Type Description Default
file FcsFile

The FcsFile to compensate.

 required
inplace bool

If True, modify the FcsFile.events with the result. If False, return the compensated events.

 True
**kwargs Dict

All arguments accepted by FcsFile.get_events are accepted here. If the file's events have already been retrieved with the same kwargs provided here, those stored events will be used. Otherwise, the file's events will be retrieved from CellEngine.

 {}

Returns: DataFrame: if inplace=True, updates FcsFile.events for the target FcsFile

create(experiment_id, name, channels=None, spill_matrix=None, dataframe=None) classmethod 

create(
    experiment_id: str,
    name: str,
    channels: List[str],
    spill_matrix: List[float],
    dataframe: Optional[None],
) -> Compensation

create(
    experiment_id: str, name: str, *, dataframe: DataFrame
) -> Compensation

Create a new compensation.

Specify either dataframe or channels and spill_matrix.

Parameters:

Name Type Description Default
experiment_id str

the ID of the experiment.

 required
name str

The name of the compensation.

 required
channels List[str]

The names of the channels to which this compensation matrix applies.

 None
spill_matrix List[float]

The row-wise, square spillover matrix. The length of the array must be the number of channels squared.

 None
dataframe DataFrame

A square pandas DataFrame with channel names in [df.index, df.columns].

 None

delete()

from_spill_string(spill_string) staticmethod

Creates a Compensation from a spill string (a file-internal compensation). This can be used with FcsFile.spill_string. The compensation is not saved to CellEngine.

get(experiment_id, _id=None, name=None) classmethod

update()

Save changes to this Compensation to CellEngine.