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

Pip installs the published package. Conda uses the pinned environment files in this repository.

Pip

1. Install the package

   pip install phenome

   PyTorch is included. An NVIDIA GPU is used when CUDA is available; the same install runs on CPU.

   For very large GPU datasets, add the optional backends:

   pip install "phenome[full]"

2. Verify the install

   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)")
   '

Conda

1. Clone the repository

   git clone https://github.com/AAitorG/PhenoMe.git
   cd PhenoMe

2. Create an environment for your hardware. These files pin the scientific stack and install this checkout.

   GPU (CUDA)

   conda env create -f envs/environment-gpu.yml
   conda activate phenome-gpu

   CPU

   conda env create -f envs/environment-cpu.yml
   conda activate phenome-cpu

3. Verify the install

   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)")
   '

Device selection

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.
opencv / h5py build errors	Use conda-forge or the full conda env file.
Import works but GPU not used	import torch; print(torch.cuda.is_available()); ensure device is passed into PhenoMe(...).

More in the FAQ - installation.

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.

Ready-to-run version

If you prefer a guided walkthrough with interactive widgets, start with Notebook 01 — Interactive quickstart.

1. 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, seed=42)

2. 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")

3. Extract embeddings (AI descriptions) and properties

   pheno.process_images(wrapper)
   pheno.compute_properties(property_preset="intensity")

   Tip

   If your data has plate effects, you can run pheno.correct_batches(batch_metadata_key="plate_id", control_filters={"condition": "Control"}) here.

4. Visualize your results

   pheno.plot_pca(color_by="condition")

   Replace condition with any metadata column in your dataset. Use pheno.get_available_metadata_keys() to list them. If you have no labels yet, call pheno.plot_pca() with no color_by.

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.