cellosaurus.Cellosaurus

class cellosaurus.Cellosaurus(cache_dir: str | Path | None = None, *, update: bool = False, ncit2oncotree_path: str | Path | None = None, oncotree_path: str | Path | None = None)

Bases: object

Cellosaurus cell-line database wrapper.

Parameters:

• cache_dir (str or Path or None) – Directory to cache the downloaded Cellosaurus TXT file. Defaults to ~/.cache/cellosaurus.

• update (bool) – Force re-download of the database file.

• ncit2oncotree_path (str or Path or None) – Path to a CSV mapping NCIt identifiers to OncoTree codes. If None, OncoTree annotations are skipped.

• oncotree_path (str or Path or None) – Path to the OncoTree reference CSV. If None, OncoTree annotations are skipped.

df

Annotated Cellosaurus DataFrame indexed by accession.

Type:

pd.DataFrame

__init__(cache_dir: str | Path | None = None, *, update: bool = False, ncit2oncotree_path: str | Path | None = None, oncotree_path: str | Path | None = None) → None

Methods

__init__([cache_dir, update, ...])
cells_per_gene_fusion([min_cells])	Cell-by-gene-fusion boolean matrix.
cells_per_mutation([min_cells])	Cell-by-mutation boolean matrix.
exclude_contaminated_cells()	Exclude contaminated cell lines.
exclude_non_cancer_cells()	Exclude non-cancer cell lines.
exclude_non_human_cells()	Exclude non-human cell lines.
exclude_problematic_cells()	Exclude problematic cell lines.
export(path)	Export to CSV, dropping complex nested columns.
from_dataframe(df)	Create a Cellosaurus instance from an existing DataFrame.
gene_fusions()	Extract gene fusions per cell line.
head([n])	Return the first n rows.
map_cells(cells[, key_type, strict])	Map cell line names to Cellosaurus identifiers.
mutations()	Extract mutations per cell line.
select_cells(**kwargs)	Subset cell lines by column values.
tnbc()	Return accession identifiers for triple-negative breast cancer lines.

Attributes

accessions	Return all accession identifiers.
columns	Return column names.
data_version	Return the Cellosaurus release version, if available.
shape	Return (n_rows, n_cols).

property accessions: list[str]

Return all accession identifiers.

Returns:

All accession identifiers (the DataFrame index).

Return type:

list of str

cells_per_gene_fusion(min_cells: int = 2) → DataFrame | None

Cell-by-gene-fusion boolean matrix.

Parameters:

min_cells (int) – Minimum number of cells per gene fusion (default 2).

Returns:

Boolean matrix with cell info columns, or None.

Return type:

pd.DataFrame or None

cells_per_mutation(min_cells: int = 2) → DataFrame | None

Cell-by-mutation boolean matrix.

Parameters:

min_cells (int) – Minimum number of cells per mutation (default 2).

Returns:

Boolean matrix with cell info columns, or None.

Return type:

pd.DataFrame or None

property columns: list[str]

Return column names.

Returns:

Column names of the underlying DataFrame.

Return type:

list of str

property data_version: str | None

Return the Cellosaurus release version, if available.

Returns:

Release version string, or None if not recorded.

Return type:

str or None

exclude_contaminated_cells() → Cellosaurus

Exclude contaminated cell lines.

Only filters on Problematic cell line: Contaminated metadata. Less strict than exclude_problematic_cells(); keeps misidentified cell lines.

Returns:

Filtered instance.

Return type:

Cellosaurus

exclude_non_cancer_cells() → Cellosaurus

Exclude non-cancer cell lines.

Returns:

Filtered instance with only cancer cell lines.

Return type:

Cellosaurus

exclude_non_human_cells() → Cellosaurus

Exclude non-human cell lines.

Keeps only cell lines whose sole NCBI taxonomy ID is 9606 (Homo sapiens). Hybrid cell lines are removed.

Returns:

Filtered instance.

Return type:

Cellosaurus

exclude_problematic_cells() → Cellosaurus

Exclude problematic cell lines.

Filters on any Problematic cell line comment. More strict than exclude_contaminated_cells(); also removes misidentified lines.

Returns:

Filtered instance.

Return type:

Cellosaurus

export(path: str | Path) → Path

Export to CSV, dropping complex nested columns.

Parameters:

path (str or Path) – Destination file path.

Returns:

Path to the written file.

Return type:

Path

classmethod from_dataframe(df: DataFrame) → Cellosaurus

Create a Cellosaurus instance from an existing DataFrame.

This bypasses downloading and parsing, useful for testing or working with pre-processed data.

Parameters:

df (pd.DataFrame) – Annotated Cellosaurus DataFrame (already indexed by accession).

Returns:

Instance wrapping the given DataFrame.

Return type:

Cellosaurus

gene_fusions() → dict[str, list[str]]

Extract gene fusions per cell line.

Returns a dict mapping Cellosaurus accession to a list of fusion strings (FUSION_NAME (HGNC1-HGNC2)).

Only human, cancer, non-contaminated cell lines are included.

Returns:

Gene fusions keyed by accession.

Return type:

dict[str, list[str]]

head(n: int = 5) → DataFrame

Return the first n rows.

Parameters:

n (int) – Number of rows to return.

Returns:

The first n rows of the underlying DataFrame.

Return type:

pd.DataFrame

map_cells(cells: list[str], key_type: str = 'cellosaurus_id', *, strict: bool = False) → dict[str, str | None]

Map cell line names to Cellosaurus identifiers.

This function is designed to take input from a spreadsheet, electronic laboratory notebook entry, or cell line provider where names may be inconsistent.

Parameters:

• cells (list[str]) – Cell names (or Cellosaurus accession identifiers).

• key_type (str) – Identifier format to return. One of "cellosaurus_id" (default), "depmap_id", "sanger_model_id", "atcc_id", "cell_line_name".

• strict (bool) – If True, raise on mapping failure. If False, return None for failures.

Returns:

Mapping from input cell name to matched identifier.

Return type:

dict[str, str | None]

Raises:

ValueError – If strict=True and any cell fails to map.

mutations() → dict[str, list[str]]

Extract mutations per cell line.

Returns a dict mapping Cellosaurus accession to a list of mutation strings (GENE_NAME (HGNC_ID)).

Only human, cancer, non-contaminated cell lines are included.

Returns:

Mutations keyed by accession.

Return type:

dict[str, list[str]]

select_cells(**kwargs: object) → Cellosaurus

Subset cell lines by column values.

Only exact matching is supported. Supported column names:

• bto_id

• category

• is_cancer

• is_contaminated

• is_problematic

• ncbi_taxonomy_id

• ncit_disease_id

• ncit_disease_name

• oncotree_code

• oncotree_main_type

• oncotree_name

• oncotree_tissue

• organism

• sex_of_cell

• uberon_id

• uberon_name

Parameters:

**kwargs – Column-name / value pairs. Values can be scalars or lists.

Returns:

Filtered instance.

Return type:

Cellosaurus

Raises:

ValueError – If no keyword arguments are given or an unsupported column is specified.

property shape: tuple[int, int]

Return (n_rows, n_cols).

Returns:

(n_rows, n_cols) of the underlying DataFrame.

Return type:

tuple of int

tnbc() → list[str]

Return accession identifiers for triple-negative breast cancer lines.

Returns:

Cellosaurus accession identifiers.

Return type:

list[str]