Data organization

import { FileTree, Aside } from ‘@astrojs/starlight/components’;

Recommended project layout

- project/ - data/ - images/ raw images - masks/ segmentation masks (optional) - metadata.csv experimental metadata - results/ - phenome_results.h5 checkpoint / results - distances.pkl - properties.csv - config.json - figures/ - pca_by_condition.html - distance_distribution.html - scripts/ - process_data.py - analyze_results.py

Naming conventions

Use descriptive, consistent filenames.

# Good
images/Control_30min_rep1_001.tif
images/DrugA_10uM_30min_rep1_001.tif

# Avoid
images/img1.tif
images/experiment_final_v2_new.tif

Consistent names let you reuse the same path templates and CSV lookups across experiments - see Experiment details.

Inspect before processing

Always run inspect_data() between find_files and process_images when you want a full per-image table of shapes, stored dtypes, and ranges. process_images also samples up to 32 images, logs a short processing pipeline at INFO, and warns on suspicious but processable inputs (for example under-used bit depth). Those warnings do not change the data. Known-unprocessable combinations (unsupported dimensions, invalid channel selection, mixed split-channel counts, mixed sizes with no resize and batch_size>1) fail before the model runs.

inspect_df = pheno.inspect_data()
print(inspect_df.head())

shape_groups = inspect_df.groupby(["height", "width", "channels"]).ngroups
if shape_groups > 1:
    print("Warning: multiple image shapes detected - consider resizing.")

Validate inputs

import os

def validate_file_df(file_df) -> bool:
    assert "file_path" in file_df.columns, "Missing 'file_path' column"
    missing = [p for p in file_df["file_path"] if not os.path.exists(p)]
    if missing:
        print(f"Warning: {len(missing)} files not found")
        print(f"Examples: {missing[:3]}")
    return not missing

file_df = pheno.find_files("path/to/images")
if validate_file_df(file_df):
    pheno.process_images(wrapper)

Filtering patterns

Filter returns empty results

Symptom: no images after filtering.

print("Available keys:", pheno.get_available_metadata_keys())

df = pheno.export_dataset_table()
print("Unique conditions:", df["condition"].unique())

dist_df = pheno.compute_reference_distances(
    reference_filters={"condition": "Control"},
)

Common causes:

Case sensitivity - "control" vs "Control".
Whitespace in CSV values.
Column absent from the final file_df (check your metadata function).

Reduce compute by filtering

pheno.process_images(
    wrapper,
    filters={"condition": ["Control", "Drug1"]},
    batch_size=32,
)

Missing properties

Symptom: some images have NaN properties (the framework warns automatically when NaNs are present).

Diagnose:

df = pheno.compute_properties(property_preset="basic")
nan_counts = df.select_dtypes(include=["number"]).isna().sum()
print("Properties with NaNs:", nan_counts[nan_counts > 0].to_dict())

for idx in df[df["area"].isna()].index[:5]:
    print(pheno.get_image_info(idx)["image_path"])

Fixes:

Confirm masks exist for all images (or switch preset to intensity).
Verify property requirements match available data; see Select properties.