PlexoraViewer

from plexora import PlexoraViewer

PlexoraViewer(
    datasource,
    data_dir=None,
    proxy='auto',
    height=850,
    width='100%',
    base_url=None,
    plugins=None,
    tool=None,
    overlay=None,
    channels=None,
    memory=False,
    start=True,
)

Displaying it -- as a Jupyter cell's last expression, or by calling .iframe() or .open() -- starts a sidecar Plexora server (or reuses one already running for this project) and shows the viewer. In local Jupyter, JupyterLab and VS Code it renders as an iframe pointing at 127.0.0.1; on JupyterHub, Open OnDemand and Colab it is proxied through the notebook server's own origin instead, since a direct localhost URL would point at the browser's machine rather than the kernel's.

When to useCopy Anchor Link

Constructed directly when a project already exists and only the display options need choosing. To register data and open a viewer on it in one call, use plexora.view() or the from_files, from_anndata and from_memory classmethods instead.

Constructor parametersCopy Anchor Link

RaisesCopy Anchor Link

PropertiesCopy Anchor Link

urlCopy Anchor Link

url

The viewer's address, as a string, including its token and launch state.

Starts the sidecar (or confirms the one already running) if this viewer has not started yet, then returns the exact URL used everywhere the viewer is shown: the iframe src, .open(), and the printed fallback for a hosted notebook. Only this entry URL carries the token -- the server trades it for a scoped cookie on the first request, so nothing else needs to carry it.

MethodsCopy Anchor Link

from_filesCopy Anchor Link

@classmethod
from_files(
    name,
    image,
    segmentation,
    features,
    x,
    y,
    id_column='CellID',
    celltype_column=None,
    channel_names=None,
    copy=False,
    data_dir=None,
    **viewer_kwargs,
)

Register a project from files on disk, then open a viewer on it.

A thin wrapper around plexora.register_datasource followed by the constructor. Everything not listed under Args is forwarded to PlexoraViewer.__init__ as **viewer_kwargs.

import plexora

viewer = plexora.PlexoraViewer.from_files(
    "tonsil", image="slide.ome.tif", segmentation="mask.tif",
    features="cells.csv", x="X_centroid", y="Y_centroid")

from_anndataCopy Anchor Link

@classmethod
from_anndata(
    name,
    image,
    features=None,
    adata=None,
    segmentation=None,
    coordinate_source=None,
    obsm_key=None,
    x=None,
    y=None,
    feature_source='X',
    layer=None,
    feature_obs_columns=None,
    obs_id_field=None,
    celltype_column=None,
    subset_by=None,
    subset_value=None,
    channel_names=None,
    copy=False,
    data_dir=None,
    to_disk=False,
    **viewer_kwargs,
)

Register an AnnData-backed project, then open a viewer on it.

Give either features (a path to an existing .h5ad) or adata (a live AnnData object held in this kernel), not both. A live object is served directly from this kernel's memory rather than written to disk first, so the loop this is for -- annotate, look, annotate again -- costs no disk write and no re-import, and viewer.refresh(adata) picks up the next edit. Pass to_disk=True to write it to <data_dir>/<name>.h5ad and read that instead -- worth it when the project should outlive this kernel, or the table is large enough that a second copy in memory is the wrong trade.

coordinate_source, obsm_key, x, y, feature_source and layer say where in the AnnData to find coordinates and feature values; leaving them unset auto-detects adata.obsm["spatial"] for coordinates and reads features from adata.X.

import plexora

viewer = plexora.PlexoraViewer.from_anndata(
    "tonsil", image="slide.ome.tif", adata=adata)

from_memoryCopy Anchor Link

@classmethod
from_memory(
    name,
    image=None,
    *,
    data_dir=None,
    tool=None,
    overlay=None,
    channels=None,
    proxy='auto',
    height=850,
    width='100%',
    base_url=None,
    plugins=None,
    start=True,
    **data_kwargs,
)

Register a project from objects this kernel is holding, then open a viewer on it.

plexora.view(name, adata=..., ...) dispatches here. Every data argument in **data_kwargs -- adata, table, segmentation, sdata and the rest that plexora.register_memory_datasource accepts -- is snapshotted and served from this kernel rather than written to disk; image may be a path (read from disk as usual) or an in-memory array. Calling this again with the same name replaces the snapshots and re-reads the table, which is what makes the notebook loop -- annotate, call again, look -- cheap.

When to use. When the data to display lives in this kernel's variables rather than in files. For a project already saved to disk, construct PlexoraViewer directly or call plexora.view(name).

import plexora

viewer = plexora.PlexoraViewer.from_memory(
    "tonsil", image="slide.ome.tif", adata=adata)

startCopy Anchor Link

start()

Start the sidecar server this viewer needs, or reuse one already running.

Called automatically by the constructor when start=True (the default), so calling it directly is only needed after constructing with start=False. Displaying the viewer, .url and .open() all call it too, so it never needs to be called more than once by hand.

refreshCopy Anchor Link

refresh(adata=None, table=None, image=None, segmentation=None, **data_kwargs)

Push the next round of annotation to a viewer serving in-memory data.

The second half of the notebook loop this viewer is for: annotate, refresh(), look. Whatever is passed here is re-snapshotted and re-described -- so an obs column that did not exist a cell ago reaches the project's vocabulary and can be chosen as an overlay -- and whatever is left as None is left alone, tiles and all.

Only works for a project registered from memory (plexora.view(..., adata=...), or from_anndata/from_memory); a project that reads its data from files has nothing here to refresh from.

iframeCopy Anchor Link

iframe()

Return the viewer's iframe for display, starting the server first.

Equivalent to letting the viewer display itself as a cell's last expression, except the result can be handed to IPython.display.display() explicitly, and it is the reliable way to show a viewer on Colab, where a bare cell expression cannot resolve the port under "Run all" or after a reconnect.

openCopy Anchor Link

open()

Open the viewer in a new browser tab, when that is possible from here.

Works for a direct 127.0.0.1 URL -- ordinary local Jupyter and VS Code. For a hosted notebook (JupyterHub, Open OnDemand, Colab) the URL is a path on the notebook server's own origin rather than a full address, so it is printed instead of being opened.

ExamplesCopy Anchor Link

import plexora

viewer = plexora.PlexoraViewer("tonsil", tool="cell_explorer",
                               overlay="leiden")
viewer  # displays the iframe as the cell's last expression

NotesCopy Anchor Link

tool, overlay and channels are ephemeral: they belong to this one viewer and are never written to the project, so a notebook that opens the same project with a different overlay every cell does not overwrite what was last set up by hand in the browser. The project's saved channels and saved overlay are still exactly what a plain plexora.view(name) restores.

RelatedCopy Anchor Link

GuidesCopy Anchor Link