Python API

CellView provides a Python API for loading plate data directly into pandas DataFrames from your Jupyter notebooks or analysis scripts. This page covers everything you need to get your data into Python and start analysing it.

Full signatures and argument docs are in the generated API reference.

Loading data

The primary function you will use is cellview_load_data. Call it with one or more OMERO plate IDs, or pass an experiment name or ID to load all plates from that experiment at once.

from cellview.api import cellview_load_data

# Load a single plate
df, variable_names = cellview_load_data(12345)

# Load several plates together (useful for combining biological replicates)
df, variable_names = cellview_load_data(12345, 12346, 12347)

# Load all plates from an experiment by name
df, variable_names = cellview_load_data(experiment="palb_washout")

# Load all plates from an experiment by numeric ID
df, variable_names = cellview_load_data(experiment=6)

Auto-import behaviour

Note

If a plate ID you request is not yet in your local CellView database, cellview_load_data will attempt to import it from OMERO automatically. This requires network access to your OMERO server and valid credentials configured in your .env file. The import runs silently in the background — if it succeeds, you get your data as normal; if it fails (e.g. no network access), an error is raised with a clear message.

To import data manually before a session without network access, use the CLI: cellview import plate <plate_id>.

Understanding the return values

cellview_load_data always returns a two-element tuple: (df, variable_names).

The DataFrame (df)

df is a standard pandas DataFrame. Each row represents one segmented cell. The following columns are always present:

  • plate_id — the OMERO plate ID (integer) the cell came from
  • cell_line — the name of the cell line (e.g. "RPE", "HeLa")
  • well_id — the well identifier (e.g. "B03")
  • experiment — the experiment name the plate belongs to
  • condition — the treatment condition label for that well

If the experiment included an EdU channel (S-phase marker), two additional columns are present:

  • cell_cycle — cell cycle phase assigned to each cell: G1, S, G2, Polyploid, or SubG1
  • cell_cycle_detailed — same as cell_cycle but with Mitotic as a subclassification within G2/M (requires H3P channel)

All single-cell measurement columns follow a naming pattern of {measurement}_{channel}_{compartment}, for example:

  • area_nucleus — nucleus area in pixels
  • intensity_mean_DAPI_nucleus — mean DAPI intensity in the nucleus
  • integrated_int_DAPI_norm — DAPI integrated intensity, normalised to mode (proxy for DNA content)

The variable names list (variable_names)

variable_names is a Python list of strings. It contains the names of any flexible experimental metadata variables that were stored when the plate was imported — for example ["Drug", "Concentration", "Timepoint"].

These variables become regular columns in df, so you can use them directly for filtering and grouping. The list is returned separately because it tells you which columns are experimental metadata versus measurement columns — useful when you want to loop over conditions programmatically.

df, variable_names = cellview_load_data(12345, 12346)
print(variable_names)  # ['Drug', 'Concentration']

# Filter to control wells
ctrl = df[df["Drug"] == "DMSO"]

# Group by condition and compute median nucleus area
df.groupby("Drug")["area_nucleus"].median()

Combining with omero-screen-plots

The DataFrame returned by cellview_load_data is designed to work directly with the omero-screen-plots package. Here is a short complete example that loads two replicate plates, inspects the condition variables, then generates a combined cell cycle plot and a nucleus area comparison.

from cellview.api import cellview_load_data
from omero_screen_plots import combplot_cellcycle, feature_plot

# Load two replicate plates from the same experiment
df, variable_names = cellview_load_data(12345, 12346)

# Inspect what condition variables are available
print(variable_names)        # e.g. ['Drug', 'Concentration']
print(df["Drug"].unique())   # e.g. ['DMSO', 'Drug_A', 'Drug_B']

# Define which conditions to compare (order controls plot order)
conditions = ["DMSO", "Drug_A", "Drug_B"]

# Combined cell cycle plot: scatter + stacked bar in one figure
fig, axes = combplot_cellcycle(
    df=df,
    conditions=conditions,
    condition_col="Drug",
    selector_col="cell_line",
    selector_val="RPE",
    save=True,
    file_format="svg",
)

# Nucleus area boxplot across the same conditions
fig, ax = feature_plot(
    df=df,
    feature="area_nucleus",
    conditions=conditions,
    condition_col="Drug",
)
Note

If you have an AI coding assistant (such as Claude) available in your notebook environment, it can help you write plotting calls based on the explore guide context. Run cellview explore from the terminal to launch a pre-configured notebook environment where AI assistants automatically receive the plotting API documentation.

Advanced: dependency injection API

cellview_load_data_with_injection is the underlying implementation called by cellview_load_data. It accepts an optional conn parameter, which allows you to pass an explicit database connection — useful when writing tests or when you need fine-grained control over which database is used. In normal analysis workflows, prefer cellview_load_data.

Legacy API

cellview_load_data_legacy is a singleton-based version kept for backward compatibility with older notebooks. Prefer cellview_load_data for all new code.