Getting started

This page walks you from an empty environment to a first PCA plot of your own images.

1. Requirements

Python 3.12 or newer.
Hardware: any CPU works; an NVIDIA GPU is strongly recommended for speed. See Best practices - performance for sizing.
OS: Linux, macOS, Windows.

2. Installation

Install the published package with pip.

pip install phenome

PyTorch and the Jupyter packages used by the notebooks are included. Pass device to speed up the computation using the GPU.

phenome[full] adds TorchDR and PyKeOps for large GPU analyses. Turn GPU dimensionality reduction on with PhenoMe(..., use_gpu_for_dr=True). It does not move embeddings onto the GPU by itself:

pip install "phenome[full]"

Verify:

python3 -c '
import torch, phenome
print(f"PhenoMe {phenome.__version__} is ready!")
print("GPU:", torch.cuda.is_available(),
      f"({torch.cuda.get_device_name(0)})" if torch.cuda.is_available() else "(CPU-only mode)")
'

Always pass device explicitly so CPU/GPU behavior is obvious in the code, especially for scripts shared with collaborators.

import torch
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

Pass the same device into load_dinov2_model(...) and PhenoMe(...).

Install troubleshooting (click to expand)

Symptom	Suggestion
`torch` not found or wrong CUDA	Reinstall torch from PyTorch get started; match driver and wheel.
Import works but GPU not used	`import torch; print(torch.cuda.is_available())`; ensure `device` is passed into `PhenoMe(...)`.

3. Run your first analysis

The snippet below runs the full pipeline on a folder of images. You can run this in a Python script or a Jupyter Notebook cell.

Set up and start

Load an AI vision model (DINOv2 by default) and create the pipeline.

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)

Find your images

A simple folder is fine. For grouped experiments (conditions, drugs, time points) add labels via folder patterns or spreadsheets.
```
pheno.find_files("path/to/your/images")
```
Extract embeddings (AI descriptions) and properties
```
pheno.process_images(wrapper)
pheno.compute_properties(property_preset="intensity")
```
If your data has plate effects and those metadata keys exist, you can run pheno.correct_batches(batch_metadata_key="plate_id", control_filters={"condition": "Control"}) here.
Visualize your results
```
pheno.plot_pca()
```
To color points, pass a key from pheno.get_available_metadata_keys(). For example, after a folder pattern or spreadsheet created condition, call pheno.plot_pca(color_by="condition"). Add seed=42 to PhenoMe only when you want a reproducible run.

What’s next?

Pick the card that matches your next goal. Each links to the most relevant guide, reference, or notebook - no duplicates of the quickstart above.

Pick a learning pathCurated routes by audience: first day, own dataset, reporting, developer, interpretability.

Preparing your dataOrganize folders, add labels via folder patterns or spreadsheets, and find masks.

Common workflowsRecipes for typical study designs: conditions, doses, time courses, plates.

Understanding propertiesLearn about the physical traits like size and shape that PhenoMe measures.

Reproducibility & performanceSeeds, device selection, batching, and best practices for reliable runs.