Using PhenoMe with LLMs

PhenoMe is a scientific pipeline. Defaults stay as they are (logging, plots, HTML reports, save_results output). If you are an assistant writing analysis code, use the public API below and only pass extra parameters when the user asked for them.

Machine-readable docs (after the site build):

• llms.txt — page index
• llms-small.txt — compact corpus for a context window
• llms-full.txt — full site text

Attach llms-small.txt in ChatGPT or Claude when answering “how do I use PhenoMe?”.

Rules for assistants

1. Import from the public surface: from phenome import PhenoMe, load_dinov2_model. Do not invent methods. Look up names in the function location guide.
2. Canonical order: find_files → process_images → optional compute_properties → analysis / plots.
3. Do not change logging, plot backends, or report sections unless the user asked. Processing steps are already logged at INFO during process_images / compute_properties. Reprint only if asked: print_processing_pipeline().
4. When the user wants a paper-style methods dump, then call export_experiment_config (and optionally include_run_settings=True on the report). The pipeline records settings silently; nothing is written until those calls.
5. Pass device explicitly so CPU/GPU is obvious in shared scripts.

Canonical first analysis

import torch
from phenome import PhenoMe, load_dinov2_model

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
wrapper = load_dinov2_model(model_name="dinov2_vitb14_reg", device=device)
pheno = PhenoMe(device=device, seed=42)

pheno.find_files("path/to/your/images")
pheno.process_images(wrapper)
pheno.compute_properties(property_preset="intensity")
pheno.plot_pca(color_by="condition")

seed=42 is only needed when the user asked for a reproducible run. Omit it to keep the library default (seed=None).

When the user asks to save settings

The run log is silent. Export it explicitly:

pheno.save_results("results/phenome_results.h5")  # HDF5 only; no sibling config file
pheno.export_experiment_config("results/config.json")
pheno.export_methods_markdown("results/methods.md")  # optional paper supplement
pheno.generate_report(
    "results/report.html",
    include_run_settings=True,  # Methods section; default is False
)

export_experiment_config includes seed, environment, processing params, model name (from load_dinov2_model), and recorded steps (property_preset, reference_filters, clustering, …). You do not need to pass model_name= unless you want to override.

Inspect without writing a file: settings = pheno.get_run_settings().

Folder metadata vs spreadsheet

Path template

from phenome import get_metadata_from_path

pheno.find_files(
    "path/to/images",
    metadata_fn=get_metadata_from_path("{condition}/{well}/{filename}"),
)

CSV lookup

See Using a spreadsheet. Only rows that exist in both the folder and the CSV are processed.

Property presets

Use a preset name, not a guessed feature list. Masks are required for shape-based presets; intensity does not need masks.

pheno.compute_properties(property_preset="basic")  # needs masks

Valid presets: none, intensity, shape, basic, standard, complete. Details: Select properties — Presets.

Batch correction

pheno.correct_batches(
    batch_metadata_key="plate_id",
    control_filters={"condition": "Control"},
)

Checkpoint (large datasets)

pheno.process_images(wrapper, checkpoint_path="results/phenome_results.h5")

Reload: find_files first, then pheno.load_results("results/phenome_results.h5").

Verbosity and plot format (caller’s choice)

Do not change these unless asked.

Goal	Parameter
Quieter logs	logging.getLogger("phenome").setLevel(logging.WARNING)
Return a Plotly figure	plot_pca(..., return_fig=True)
Static-ish scatter	plot_pca(..., render_mode="svg")
Report without CDN	generate_report(..., offline_plotly=True) (already the default)
Methods section in the HTML report	generate_report(..., include_run_settings=True)
Reprint the processing pipeline	pheno.print_processing_pipeline()

MCP (optional)

For Cursor or Claude Desktop, install phenome[mcp] and run phenome-mcp. See MCP for PhenoMe.