Skip to content
PhenoMePhenoMe

Preparing your data

A short guide on how PhenoMe expects images, masks, and metadata (experiment labels) to be organized.

1. Do I need to add labels (metadata)?

Section titled “1. Do I need to add labels (metadata)?”
You need… How to set up
Just visual fingerprints / properties per file A simple folder is enough.
Plots or reports split by biology (drug, dose, time, etc.) Add a folder pattern, spreadsheet, or custom script.

2. Common folder layouts

Section titled “2. Common folder layouts”

Single folder

Section titled “Single folder”
  • Directoryimages/
    • img001.tif
    • img002.tif
 
pheno.find_files("images/")

Default metadata includes path and filename. Add a template or CSV when you need condition, drug, etc.

Grouped by folder

Section titled “Grouped by folder”
  • Directorydata/
    • DirectoryControl/
      • a.tif
    • DirectoryTreated/
      • b.tif

Use a folder pattern (see Adding experiment info — folder patterns):

from phenome import get_metadata_from_path


metadata_fn = get_metadata_from_path(".../(condition)/(filename).*")
pheno.find_files("data", metadata_fn=metadata_fn)

3. Using a spreadsheet (CSV)

Section titled “3. Using a spreadsheet (CSV)”

Use this when your labels are in a table.

  1. PhenoMe scans your image files.
  2. Each file is matched to a spreadsheet row (usually by filename).
  3. Only the overlap is kept - files not in the spreadsheet are skipped.

Details and options: Adding experiment info — Using a spreadsheet.

import pandas as pd
from phenome import make_dataframe_metadata_fn


df = pd.read_csv("metadata.csv")
metadata_fn = make_dataframe_metadata_fn(df)
pheno.find_files("images/", metadata_fn=metadata_fn)

4. Adding masks

Section titled “4. Adding masks”

If you need to measure physical traits like cell shape, add masks when calling find_files (see Adding experiment info — Finding masks).

A typical layout is a parallel mask tree:

  • Directoryproject/
    • Directoryimages/
      • Directoryplate1/
        • A01.tif
        • A02.tif
    • Directorymasks/
      • Directoryplate1/
        • A01.tif
        • A02.tif
 
pheno.find_files("images", mask_dir="masks")

5. Common study designs

Section titled “5. Common study designs”
Design Suggested approach See also
Drug screening (plate + compound + dose) Spreadsheet with filename, compound, dose, etc. Example notebooks
Time course (images over time) Folder pattern (timepoint)/(filename).* or spreadsheet. Workflows
Multiple repeats Include replicate in spreadsheet or folder name. Best practices - data organization

6. Troubleshooting

Section titled “6. Troubleshooting”
Problem What to check
plot_pca(color_by='condition') fails That name must be a metadata key — run pheno.get_available_metadata_keys().
Spreadsheet row count != image count How overlap works - FAQ.
Filter returns no images Exact string match and keys - Best practices - data organization.
Masks not found Check mask folder and naming - Adding experiment info — Finding masks.

Learn more

Section titled “Learn more”
Adding experiment infoSpreadsheets, folder patterns, and custom scripts.
Metadata APIClasses for unique IDs, mask resolution, and centralised config.
Notebook 02 - Loading & InspectionRunnable example with path templates, CSV lookup, and multi-channel data.