create_boolean_label_combination#

create_boolean_label_combination(adata, obs_key_1, match_values_1, obs_key_2, match_values_2, operator, output_obs_key, true_label, false_label, overwrite=False)[source]#

Combine two categorical observation columns using boolean operators.

Creates a new binary label based on whether cells match specified values in both input observation columns, using the specified boolean operator.

Parameters:
adataad.AnnData

AnnData object with observations to combine.

obs_key_1str

First observation column name in adata.obs.

match_values_1List[str]

Values in obs_key_1 to match (considered “true” for boolean logic).

obs_key_2str

Second observation column name in adata.obs.

match_values_2List[str]

Values in obs_key_2 to match (considered “true” for boolean logic).

operatorstr

Boolean operator - ‘AND’, ‘OR’, or ‘XOR’.

output_obs_keystr

Name for new combined observation column.

true_labelstr

Label for cells matching the boolean criteria.

false_labelstr

Label for cells not matching the boolean criteria.

overwritebool, default False

If True, overwrites existing output_key. If False, raises error if output_key exists.

Returns:
ad.AnnData

Modified AnnData object with new observation column.

Raises:
KeyError

If obs_key_1 or obs_key_2 don’t exist in adata.obs.

ValueError

If operator is not ‘AND’, ‘OR’, or ‘XOR’.

KeyError

If output_obs_key already exists in adata.obs and overwrite=False.

TypeError

If match_values_1 or match_values_2 are not lists.

ValueError

If any values in match_values_1 not found in obs_key_1.

ValueError

If any values in match_values_2 not found in obs_key_2.

Examples

AND: Both conditions must be true

>>> adata = create_boolean_label_combination(
...     adata,
...     obs_key_1='treatment',
...     match_values_1=['control'],
...     obs_key_2='cell_cycle',
...     match_values_2=['G0'],
...     operator='AND',
...     output_obs_key='control_G0',
...     true_label='control_G0',
...     false_label='other'
... )

OR: Either condition true

>>> adata = create_boolean_label_combination(
...     adata,
...     obs_key_1='treatment',
...     match_values_1=['control', 'vehicle'],
...     obs_key_2='cell_cycle',
...     match_values_2=['G0', 'G1'],
...     operator='OR',
...     output_obs_key='quiescent_or_control',
...     true_label='positive',
...     false_label='other'
... )

XOR: Exactly one condition true (exclusive or)

>>> adata = create_boolean_label_combination(
...     adata,
...     obs_key_1='marker_A',
...     match_values_1=['positive'],
...     obs_key_2='marker_B',
...     match_values_2=['positive'],
...     operator='XOR',
...     output_obs_key='single_positive',
...     true_label='single_positive',
...     false_label='double_or_negative'
... )
Parameters:
Return type:

AnnData