Function location guide

Audience

	Meaning
✅ Public	Part of the main workflow. Use via `PhenoMe` or top-level imports.
🔧 Advanced	For power users extending the pipeline (custom models, metadata, properties, plugins).
🔒 Internal	Used by the pipeline internally. Rarely needed directly.

Index

Section	Module
Top-level	`phenome`
Pipeline methods	`PhenoMe`
Metadata	`phenome.metadata`
Utilities	`phenome.utils`
I/O	`phenome.io`
Plugins	`phenome.plugins`
Core	`phenome.core`
Report	`phenome.report.generator`
Mixins	`phenome.mixins`

Module one-liners

Module	One-line role
`phenome`	Stable imports: `PhenoMe`, model loader, metadata helpers, property factories.
`phenome.pipeline`	`PhenoMe` orchestrator wiring mixins into one user class.
`phenome.metadata`	OOP metadata extractors (`MetadataBase`, path / DataFrame sources).
`phenome.utils`	Model wrappers, transforms, device helpers, metadata + property utilities.
`phenome.io`	`read_image`, `FileDiscovery`, `CheckpointManager`, array layout helpers.
`phenome.plugins`	Registries for properties, metadata extractors, report sections.
`phenome.core`	Results container, DR, correlation, interpretability, export, validation.
`phenome.report.generator`	`ReportConfig` and standalone HTML report generation.
`phenome.mixins`	Implementation pieces behind `PhenoMe` (dataset, viz, distances, …).

Typical import blocks

from phenome import PhenoMe, load_dinov2_model

from phenome import get_metadata_from_path, make_dataframe_metadata_fn

from phenome.metadata import MetadataBase, PathTemplateMetadata, DataFrameMetadata

from phenome.io import read_image, FileDiscovery, CheckpointManager

Top-level (`phenome`)

Import	Description	Tier	Extended docs
`create_blur_effect_function`	Create property function that computes focus sharpness.	✅	Select properties · Property interpretation
`create_concentric_ring_function`	Create property function that computes stats per concentric ring (edge to core).	✅	Select properties · Property interpretation
`create_entropy_function`	Create property function that computes Shannon entropy of intensity distribution.	✅	Select properties · Property interpretation
`create_intensity_function`	Create intensity property function over entire image (no mask).	✅	Select properties · Property interpretation
`create_masked_intensity_function`	Create intensity property function over masked pixels only (mask > 0.5).	✅	Select properties · Property interpretation
`create_regionprops_function`	Create property function that extracts skimage regionprops from a mask.	✅	Select properties · Property interpretation
`create_texture_function`	Create property function that computes GLCM texture features within the mask.	✅	Select properties · Property interpretation
`DataFrameMetadata`	Metadata lookup from DataFrame. Supports single and multi-channel modes.	✅	Metadata Classes
`default_metadata_from_path`	Simple, dataset-agnostic metadata extractor used by default.	✅	Utilities · Experiment Details
`DefaultMetadata`	Minimal metadata extractor: file_path and filename from path.	✅	Metadata Classes
`get_metadata_from_path`	Create metadata extractor function from a path template.	✅	Utilities · Experiment Details
`get_preset_property_functions`	Return a preset dict of property functions for use with compute_properties.	✅	Select properties · Property interpretation
`load_dinov2_model`	Load a DINOv2 model and return a DinoV2ModelWrapper ready for processing.	✅	Model Wrappers
`make_dataframe_metadata_fn`	Build metadata function using a dataframe for metadata lookup.	✅	Utilities · Experiment Details
`MetadataBase`	Base class for metadata extraction with configurable columns and ID handling.	✅	Metadata Classes
`PathTemplateMetadata`	Metadata extractor from path template with capture groups.	✅	Metadata Classes
`PhenoMe`	Main class for phenotyping analysis using deep learning embeddings.	✅	Pipeline
`PhenoMeResults`	Typed container for per-image phenotyping data (`PhenoMe.results`).	✅	Pipeline

Pipeline methods (on `PhenoMe`)

All public — this is the main API surface on PhenoMe.

Import	Description	Tier	Extended docs
`analyze_group_enrichment`	Compute z-score enrichment of properties per group (e.g. cluster labels).	✅	Pipeline
`checkpoint_context`	Context manager that loads a checkpoint and guarantees it is closed on exit.	✅	Pipeline
`clear_temporal_data`	Remove all temporal images (metadata[‘source’] == ‘NEW’) from the session.	✅	Pipeline
`compute_clustering`	Perform clustering and store labels in `metadata[i]['cluster']` for each image.	✅	Pipeline
`compute_component_correlation`	Correlate dim-reduction components with phenotypic properties.	✅	Pipeline
`compute_embedding_property_correlations`	Compute correlations between embedding dimensions and phenotypic scalar properties.	✅	Pipeline
`compute_multivariate_interpretability`	Explain a dimensionality reduction component using LASSO or Random Forest.	✅	Pipeline
`compute_properties`	Compute per-image properties using presets and/or custom functions.	✅	Pipeline
`compute_reference_distances`	Compute distances from all images to reference group.	✅	Distances
`correct_batches`	Correct plate-to-plate variation using control wells per batch.	✅	Pipeline
`create_colab_interactive_explorer`	Launch the short Colab explorer for this pipeline’s results.	✅	Interactive Explorer
`create_interactive_explorer`	Launch the interactive explorer for this pipeline’s results.	✅	Interactive Explorer
`detect_outliers`	Detect outliers based on distance to centroid.	✅	Pipeline
`embedding_dim`	Return the embedding dimensionality, or 0 if unavailable.	✅	Pipeline
`export_dataset_table`	Export the dataset as a table (CSV, Parquet, or Excel).	✅	Pipeline
`export_experiment_config`	Export experiment configuration for reproducibility.	✅	Pipeline
`export_methods_markdown`	Write a markdown methods summary from the silent run log.	✅	Pipeline
`find_files`	Discover image and mask files from directories, extract metadata, and cache internally.	✅	Pipeline
`find_prototypes`	Find images closest to each group centroid.	✅	Pipeline
`generate_report`	Generate a comprehensive standalone HTML report from phenotyping results.	✅	Pipeline
`get_available_metadata_keys`	Return sorted metadata keys.	✅	Pipeline
`get_available_property_keys`	Return sorted list of property keys stored in results.	✅	Pipeline
`get_embeddings`	Return embeddings for the given row indices.	✅	Pipeline
`get_image_info`	Return metadata, properties, and optional distance for image idx.	✅	Pipeline
`get_processing_pipeline`	Return the session processing pipeline, or None if none was recorded.	✅	Pipeline
`get_run_settings`	Return the silent run log as a JSON-serializable dict.	✅	Pipeline
`has_embeddings`	Return True if embedding data is available (lazy or eager).	✅	Pipeline
`image_preview_png_bytes`	Rasterize the same view as `plot_image_by_index` to PNG bytes.	✅	Visualization
`inspect_data`	Inspect image and mask dimensions, shapes, dtypes, and data ranges.	✅	Pipeline
`load_embeddings`	Load an embeddings checkpoint into the pipeline.	✅	Pipeline
`load_properties`	Load a properties checkpoint into the pipeline.	✅	Pipeline
`load_results`	Load and use an existing results/checkpoint file.	✅	Pipeline
`plot_centroids`	Plot centroids of groups in reduced embedding space.	✅	Visualization
`plot_counts`	Plot count of images grouped by metadata using Plotly.	✅	Visualization
`plot_image_by_index`	Plot a specific image by its index.	✅	Visualization
`plot_pca`	Plot PCA of embeddings, properties, or combined features (Plotly, WebGL by default).	✅	Visualization
`plot_tsne`	Plot t-SNE of embeddings, properties, or combined features (Plotly, WebGL by default).	✅	Visualization
`plot_umap`	Plot UMAP of embeddings, properties, or combined features (Plotly, WebGL by default).	✅	Visualization
`print_distance_summary`	Print distance summary statistics without plotting. Safe to use when enable_plots=False.	✅	Visualization
`print_processing_pipeline`	Print the ordered processing pipeline for this session.	✅	Pipeline
`process_images`	Extract embeddings from images using a pretrained or custom model.	✅	Pipeline
`process_temporal_images`	Process new images in-memory (temporary) and append to the current session.	✅	Pipeline
`property_stats_by_group`	Group properties, compute per-group statistics, and optionally print a table.	✅	Pipeline
`reset`	Reset all stored data to a clean state.	✅	Pipeline
`reset_properties`	Reset only the computed properties.	✅	Pipeline
`save_results`	Save results to HDF5 (atomic write or in-place flush).	✅	Pipeline
`set_file_df`	Set the internal file DataFrame used for processing.	✅	Pipeline
`summarize_embedding_property_correlations`	Summarize embedding-property correlations, optionally plot, and/or return a Plotly figure.	✅	Pipeline
`top_properties_different_from_reference`	For each non-reference group, return the top k properties that most differentiate it from the reference.	✅	Pipeline
`transfer_metadata_to_properties`	Transfer specified metadata columns to properties.	✅	Pipeline

Metadata (`phenome.metadata`)

Import	Description	Tier	Extended docs
`DataFrameMetadata`	Metadata lookup from DataFrame. Supports single and multi-channel modes.	✅	Metadata Classes
`DefaultMetadata`	Minimal metadata extractor: file_path and filename from path.	✅	Metadata Classes
`MetadataBase`	Base class for metadata extraction with configurable columns and ID handling.	✅	Metadata Classes
`PathTemplateMetadata`	Metadata extractor from path template with capture groups.	✅	Metadata Classes

Utilities (`phenome.utils`)

Import	Description	Tier	Extended docs
`create_blur_effect_function`	Create property function that computes focus sharpness.	✅	Properties · Select properties · Property interpretation
`create_concentric_ring_function`	Create property function that computes stats per concentric ring (edge to core).	✅	Properties · Select properties · Property interpretation
`create_entropy_function`	Create property function that computes Shannon entropy of intensity distribution.	✅	Properties · Select properties · Property interpretation
`create_intensity_function`	Create intensity property function over entire image (no mask).	✅	Properties · Select properties · Property interpretation
`create_masked_intensity_function`	Create intensity property function over masked pixels only (mask > 0.5).	✅	Properties · Select properties · Property interpretation
`create_regionprops_function`	Create property function that extracts skimage regionprops from a mask.	✅	Properties · Select properties · Property interpretation
`create_texture_function`	Create property function that computes GLCM texture features within the mask.	✅	Properties · Select properties · Property interpretation
`DataFrameMetadata`	Metadata lookup from DataFrame. Supports single and multi-channel modes.	✅	Metadata Classes
`default_metadata_from_path`	Simple, dataset-agnostic metadata extractor used by default.	✅	Utilities · Experiment Details · Metadata
`DefaultMetadata`	Minimal metadata extractor: file_path and filename from path.	✅	Metadata Classes
`DinoV2ModelWrapper`	Heritage wrapper for DINOv2 models from Meta AI.	🔧	Model Wrappers
`get_default_device`	Return a default device for phenotyping operations.	🔧	Utilities
`get_metadata_from_path`	Create metadata extractor function from a path template.	✅	Utilities · Experiment Details · Metadata
`get_preset_property_functions`	Return a preset dict of property functions for use with compute_properties.	✅	Properties · Select properties · Property interpretation
`load_dinov2_model`	Load a DINOv2 model and return a DinoV2ModelWrapper ready for processing.	✅	Model-Wrapper · Model Wrappers
`log_computing`	Log a one-line status when a step cannot report a progress bar.	✅	Utilities
`make_dataframe_metadata_fn`	Build metadata function using a dataframe for metadata lookup.	✅	Utilities · Experiment Details · Metadata
`MetadataBase`	Base class for metadata extraction with configurable columns and ID handling.	✅	Metadata Classes
`ModelWrapper`	Base wrapper for vision model embedding extraction.	🔧	Model Wrappers
`normalize_by_dtype_max`	Normalize an image to [0, 1] using effective intensity scale inference.	🔒	Utilities
`PadToSize`	Pad image (C, H, W) equally on all sides to pad_size.	🔧	Utilities
`PathTemplateMetadata`	Metadata extractor from path template with capture groups.	✅	Metadata Classes
`ProgressCallback`	Type alias: `(current, total, desc) -> None` GUI progress hook.	✅	Utilities
`quantile_normalize`	Apply quantile normalization to each channel independently.	✅	Utilities
`report_progress`	Invoke callback if provided; no-op when `None`.	✅	Utilities
`resolve_intensity_scale`	Infer how to normalize image intensities to [0, 1].	✅	Utilities
`scale_minmax`	Apply min-max scaling to each channel independently.	🔒	Utilities
`set_determinism`	Set random seeds for reproducibility across all frameworks.	🔧	Utilities
`track`	Wrap iterable in a `tqdm` progress bar.	✅	Utilities
`TransformBuilder`	Builds torchvision transform pipelines for image preprocessing.	🔧	Utilities
`TypeMaxNorm`	Normalize image by effective intensity scale (shared with normalize_by_dtype_max).	🔧	Utilities

I/O (`phenome.io`)

Import	Description	Tier	Extended docs
`align_by_metadata`	Compute metadata-based alignment for checkpoint resume.	🔧	Utilities
`align_by_paths`	Compute path-based alignment for properties checkpoint resume.	🔧	Utilities
`CheckpointManager`	Crash-safe incremental checkpoint backed by a single HDF5 file.	🔧	Utilities · HDF5 Protocol
`ensure_hwc`	Ensure image is in (H, W, C) format.	🔒	Utilities
`FileDiscovery`	Finds image files and extracts metadata from directories.	🔧	Utilities · HDF5 Protocol
`read_image`	Read an image and return as a numpy array.	🔧	Utilities

Plugins (`phenome.plugins`)

All advanced — for extending the pipeline.

Import	Description	Tier	Extended docs
`get_blob_properties`	Extract blob properties using Difference of Gaussians (DoG) blob detection.	🔧	Plugins · Extending · Select properties
`get_metadata_extractor`	Get a registered metadata extractor by name.	🔧	Plugins · Extending
`get_property`	Get a registered property function by name.	🔧	Plugins · Extending · Plugins
`get_report_sections`	Return all registered report section generators.	🔧	Plugins · Extending
`list_properties`	Return names of all registered property functions.	🔧	Plugins · Extending · Plugins
`my_custom_max_intensity`	Use as a template for creating custom property functions.	🔧	Plugins · Extending
`register_metadata_extractor`	Register a custom metadata extractor.	🔧	Plugins · Extending · Plugins
`register_property`	Register a custom property function.	🔧	Plugins · Extending · Plugins
`register_report_section`	Register a custom report section generator.	🔧	Plugins · Extending · Plugins

Core (`phenome.core`)

Advanced helpers for custom scripts extending or bypassing the pipeline.

Import	Description	Tier	Extended docs
`append_property_columns`	Add property columns to a Tier-A DataFrame.	🔧	Utilities
`build_combined_features`	Build combined embedding + property matrix with balanced normalization.	🔒	Utilities
`build_export_dataframe`	Build a DataFrame with the complete dataset for export.	🔧	Utilities
`build_metadata_columns`	Build dict of metadata columns suitable for DataFrame creation.	🔧	Utilities
`clean_correlation_inputs`	Clean correlation inputs by removing NaN/inf values.	🔧	Utilities
`compute_distance_correlation`	Compute distance correlation between x and y.	🔧	Utilities
`compute_entropy`	Compute entropy of data using histogram (PyTorch on GPU/CPU).	🔧	Utilities
`compute_lasso_interpretability`	Explain a target variable y using a LASSO model on features x.	🔧	Utilities
`compute_mutual_info`	Compute MI-derived correlation coefficient between x and y.	🔧	Utilities
`compute_pearson_correlation`	Compute Pearson correlation between x and y using torch.corrcoef on GPU/CPU.	🔧	Utilities
`compute_rf_interpretability`	Explain a target variable y using a Random Forest model on features x.	🔧	Utilities
`compute_spearman_correlation`	Compute Spearman rank correlation between x and y using scipy.	🔧	Utilities
`filter_indices`	Return indices that satisfy provided metadata filters and exclusions.	🔧	Utilities
`get_all_metadata_keys`	Get sorted unique metadata keys present in results.	🔧	Utilities
`get_metadata_value`	Safely fetch a metadata value for an image index.	🔧	Utilities
`get_metadata_value_from_dict`	Get value from a single metadata dict with case-insensitive key matching.	🔧	Utilities
`IMAGE_INDEX`	str(object=‘’) -> str	🔧	Utilities
`IMAGE_NAME`	str(object=‘’) -> str	🔧	Utilities
`IMAGE_PATH`	str(object=‘’) -> str	🔧	Utilities
`is_per_image_df`	Return whether `df` satisfies the per-image DataFrame contract (Tier A).	🔧	Utilities
`metadata_to_stable_key`	Build a deterministic, portable key from metadata for matching across devices.	🔒	Utilities
`optimize_property_types`	Reduce memory usage of property values.	🔒	Utilities
`per_image_dataframe`	Build a Tier-A per-image DataFrame.	🔧	Utilities
`PhenoMeProtocol`	Protocol describing attributes and methods mixins expect from PhenoMe.	🔧	Utilities
`PhenoMeResults`	Typed container for per-image phenotyping data (`PhenoMe.results`).	🔧	Utilities
`prepare_embedding_dataframe`	Create a DataFrame with embedding/reduction coordinates, metadata, and properties.	🔧	Utilities
`reorder_tier_a_columns`	Place Tier-A id columns first, then metadata, then remaining columns.	🔧	Utilities
`run_dimensionality_reduction`	Run dimensionality reduction using pipeline data and return DataFrame.	🔧	Utilities
`run_dimensionality_reduction_matrix`	Run dimensionality reduction on a raw matrix (pure, no pipeline).	🔧	Utilities
`TIER_A_EXCLUDE_FROM_PROPERTIES`	frozenset() -> empty frozenset object	🔧	Utilities
`validate_results`	Check that pipeline results have consistent lengths across all arrays.	🔒	Utilities

Report (`phenome.report.generator`)

Import	Description	Tier	Extended docs
`ReportConfig`	Configuration for report generation. Pass to generate_report via config=.	✅	Report
`generate_report`	Generate comprehensive standalone HTML report from phenotyping results.	✅	Report

Mixins (`phenome.mixins`)

Prefer using PhenoMe; these classes implement its methods.

Import	Description	Tier	Extended docs
`collate_fn`	Custom collate function that handles failed loads and split/combined channels.	🔒	Pipeline
`create_colab_interactive_explorer`	Launch the interactive explorer built only for Google Colab.	✅	Interactive Explorer
`create_interactive_explorer`	Launch an interactive explorer for phenotyping results in Jupyter.	✅	Interactive Explorer
`EmbeddingExtractor`	Extracts embeddings from images using a ModelWrapper and DataLoader.	🔒	Pipeline
`PhenoMeAnalysis`	Pipeline providing analysis methods for PhenoMe.	🔒	Pipeline
`PhenoMeBatchCorrection`	Mixin: `correct_batches()` for plate / batch effects.	🔒	Pipeline
`PhenoMeDataset`	Dataset for loading and preprocessing images for phenotyping analysis.	🔒	Pipeline
`PhenoMeDistances`	Provides distance computation methods for PhenoMe.	🔒	Distances
`PhenoMeInteractive`	High-performance interactive explorer for PhenoMe results.	✅	Interactive Explorer
`PhenoMeProperties`	Pipeline providing property computation and reporting for PhenoMe.	🔒	Pipeline · Properties
`PhenoMeVisualization`	Pipeline class providing visualization methods for PhenoMe.	🔒	Visualization

Function location guide

Audience

Index

Module one-liners

Typical import blocks

Top-level (phenome)

Pipeline methods (on PhenoMe)

Metadata (phenome.metadata)

Utilities (phenome.utils)

I/O (phenome.io)

Plugins (phenome.plugins)

Core (phenome.core)

Report (phenome.report.generator)

Mixins (phenome.mixins)