# Exploring data


# Overview

`cellview explore` is the quickest way to go from a plate ID to a working analysis notebook. It copies a pre-built template notebook into your personal explore library (`~/.cellview/explore/`), injects the plate IDs you care about, and opens the notebook in JupyterLab or VS Code -- ready to run.

You do not need to know where the data lives, how to connect to the database, or how to write loading code. CellView handles all of that; you start with data already in a `DataFrame`.

Every flag accepted by `cellview explore` and `cellview template` is listed in the generated [CLI reference](../reference/cli/index.md).


# Launching the explorer


## By plate ID

If you know which plate (or plates) you want to look at, pass the IDs directly:

``` bash
cellview explore 12345
cellview explore 12345 12346 12347
```

When you provide multiple plate IDs, CellView creates a single combined notebook that loads all of them together. The notebook is saved at:

``` text
~/.cellview/explore/plates/12345/explore_plate_12345.ipynb
```

(For multiple plates the directory is named after the first ID in the list.)

JupyterLab opens automatically at that notebook.


## By experiment

If you want to load all plates belonging to an experiment, use `--experiment`. You can identify the experiment by name or by its numeric ID:

``` bash
cellview explore --experiment palb_washout
cellview explore --experiment 6
```

The notebook is placed in a folder that mirrors the project/experiment hierarchy in the database:

``` text
~/.cellview/explore/MyProject/palb_washout/explore_exp_6.ipynb
```

> **Note: Note**
>
> Use `cellview experiment` to see the names and IDs of all experiments currently in your database.


## Opening in VS Code instead of JupyterLab

Pass `--code` to open the notebook in VS Code rather than JupyterLab:

``` bash
cellview explore 12345 --code
```

VS Code opens with the entire `~/.cellview/explore/` library as the workspace (so you can see all your notebooks in the sidebar) and jumps directly to the new notebook. This works particularly well with AI coding assistants such as Claude Code or GitHub Copilot, because a `CLAUDE.md` file is placed in the explore library automatically -- it documents the full plotting API and is read by the assistant the moment it opens the workspace.

To make VS Code your default editor without typing `--code` every time, set the environment variable in your shell profile:

``` bash
export CELLVIEW_EDITOR=vscode
```


# What happens when you run `explore`

Here is what CellView does behind the scenes each time you run the command:

1.  **Looks up plates.** If you used `--experiment`, CellView queries the database for all plate IDs that belong to that experiment. If you gave plate IDs directly, it uses those.

2.  **Checks for an existing notebook.** If a notebook for this exact set of plates or this experiment already exists in the explore library, CellView reuses it. This means you can close the editor, come back later, and run the same command to reopen exactly where you left off. Use `--fresh` to override this behaviour.

3.  **Copies and patches the template.** The chosen template is copied to the correct subfolder in `~/.cellview/explore/` and the `PLATE_IDS` line is replaced with the actual IDs.

4.  **Migrates legacy notebooks (if needed).** Older flat-layout notebooks (created before the project/experiment subfolder structure was introduced) are moved into the new layout automatically.

5.  **Launches the editor.** JupyterLab or VS Code opens with the notebook ready to run.

6.  **Optionally launches Napari.** Unless you passed `--no-napari`, Napari starts in the background so you can view raw microscopy images alongside your analysis.


# The explore library and `CLAUDE.md`

`~/.cellview/explore/` is your personal analysis library. Every notebook you create with `cellview explore` is stored here, organised into subfolders by project and experiment (or by plate ID). Nothing is deleted automatically -- old notebooks accumulate over time and you can return to any of them at any point.

A `CLAUDE.md` file is placed in this directory when it is first created. It contains complete documentation of:

- [cellview_load_data](../reference/api.cellview_load_data.md#cellview.api.cellview_load_data) and its arguments
- All plot functions from `omero_screen_plots` with their parameters
- Common patterns for filtering and grouping data

When you open the explore library in VS Code with `--code`, any AI coding assistant that supports project context files (Claude Code, GitHub Copilot, Cursor, etc.) reads this file automatically. The assistant then knows the entire CellView API without you needing to explain it -- you can ask questions like "plot the cell cycle distribution for RPE cells only" and get working code immediately.

> **Note: Note**
>
> The `CLAUDE.md` file is updated when you upgrade CellView. If you customise it, your changes may be overwritten on upgrade. Keep personal notes in a separate file in the same directory.


# Notebook structure

A freshly created notebook from the default `cellcycle` template contains the following cells, in order:

``` text
[Markdown]  # Explore -- Plate 12345
[Code]      PLATE_IDS = [12345]
[Code]      from cellview.api import cellview_load_data
[Code]      df, variable_names = cellview_load_data(*PLATE_IDS)
[Code]      ... template-specific analysis cells ...
```

The `PLATE_IDS` cell is the only part of the template that CellView modifies. Everything else comes from the template as-is, so what you see next depends on which template you chose.

The default `cellcycle` template adds cells that produce:

- A summary table of cell counts per condition
- A combined cell cycle plot (stacked bar + phase quantification)
- A feature comparison plot for nucleus area

You can edit, delete, or add cells freely -- the notebook is yours.


# The `--fresh` flag

By default, running `cellview explore 12345` a second time simply reopens the existing notebook. This is intentional: it lets you accumulate your own analysis in the notebook without losing it.

Use `--fresh` when you want to start again from a clean template:

``` bash
cellview explore 12345 --fresh
```

This is also useful after a CellView upgrade that ships an improved template -- `--fresh` gives you the new version.

> **Note: Note**
>
> `--fresh` overwrites the existing notebook. If you want to keep your previous work, rename or copy the file before running `--fresh`.


# Using a Marimo notebook

CellView templates can be Marimo reactive notebooks (`*.py` files) as well as standard Jupyter notebooks. Marimo notebooks re-run cells automatically when their inputs change, which can be useful for interactive exploration.

If the selected template is a Marimo file, CellView opens it with:

``` bash
marimo edit explore_plate_12345.py
```

Everything else works the same way -- the `PLATE_IDS` line is patched, the file is placed in the correct subfolder, and the editor is launched for you.

> **Note: Note**
>
> Marimo must be installed separately. Run `uv add marimo` (or `pip install marimo`) if you see a "command not found" error.


# Managing templates


## Listing templates

To see all templates that CellView knows about, including their format and a short description:

``` bash
cellview template list
```


## Using a different template

Pass `--template` with the template name:

``` bash
cellview explore 12345 --template drug_screen
```


## Adding your own template

You can register a notebook you have already created as a named template:

``` bash
cellview template add ~/my_analysis.ipynb --name drug_screen \
    --description "Dose-response analysis"
```

Alternatively, drop the file directly into `~/.cellview/templates/`. CellView checks this directory in addition to its built-in templates, and user templates take priority when names collide. After dropping a file there, register it with:

``` bash
cellview template sync
```


## Template conventions

For CellView to inject plate IDs correctly, your template must contain exactly this line somewhere near the top:

``` python
PLATE_IDS: list[int] = []
```

CellView replaces the right-hand side with the actual list of plate IDs at launch time. Everything else in the file is left untouched.

The first markdown cell in the notebook is used as the short description shown by `cellview template list`.


## Syncing templates to the database

If you add template files to `~/.cellview/templates/` manually (without using `cellview template add`), run:

``` bash
cellview template sync
```

This scans both the built-in package templates and your personal template directory, and registers any new files in the database.


## Removing a template record

``` bash
cellview template remove drug_screen
```

This removes the database record for the named template. The file itself is **not** deleted -- only the registration entry is removed.


## Showing template details

``` bash
cellview template show drug_screen
```

Displays the full path, format, description, and registration date for a specific template.


# Example: creating your own template

The following walkthrough shows how to create a reusable template from scratch for a dose-response experiment.

**Step 1 -- Create the templates directory** (if it does not already exist):

``` bash
mkdir -p ~/.cellview/templates
```

**Step 2 -- Start from an existing notebook or create a new one.**

If you already have a working notebook that you want to reuse, copy it:

``` bash
cp ~/notebooks/dose_response_analysis.ipynb \
    ~/.cellview/templates/dose_response.ipynb
```

Or open JupyterLab and create a new notebook in `~/.cellview/templates/`.

**Step 3 -- Add the required** `PLATE_IDS` **line** near the top of the notebook, in its own code cell:

``` python
PLATE_IDS: list[int] = []
```

Make sure this line appears exactly as shown -- CellView uses it as a target for injection.

**Step 4 -- Add a markdown description** as the first cell of the notebook. This text is shown by `cellview template list`:

``` text
# Dose-Response Analysis
Analyse viability and cell cycle distribution across drug concentrations.
```

**Step 5 -- Save the file** as `~/.cellview/templates/dose_response.ipynb`.

**Step 6 -- Test it:**

``` bash
cellview explore 12345 --template dose_response
```

CellView will copy the template, inject the plate IDs, and open the notebook. If everything looks correct, register it properly so it appears in the list:

``` bash
cellview template add ~/.cellview/templates/dose_response.ipynb \
    --name dose_response \
    --description "Dose-response viability and cell cycle analysis"
```