Metadata classes

Tier: Public API

Auto-generated

This page is rebuilt from docstrings in phenome.metadata (multiple classes).

See also: Pipeline

@section Metadata

Metadata handling for extensible and configurable file discovery.

This package provides an object-oriented API for extracting and managing metadata from file paths, DataFrames, and custom sources. Metadata is extracted alongside images during file discovery and used to organize results, group analysis, and annotate visualizations.

Metadata extractors (classes):

• MetadataBase: Abstract base class for custom metadata extractors.
• DefaultMetadata: Minimal extractor (file path, filename, auto-generated ID).
• PathTemplateMetadata: Extract metadata by matching file paths against regex patterns.
• DataFrameMetadata: Look up metadata from a DataFrame indexed by file path.

Quick start:

from phenome import PhenoMe, PathTemplateMetadata

# Extract batch and sample ID from paths like: .../batch_1/sample_42.tif
# Use (field) placeholders — not raw regex named groups.
metadata_fn = PathTemplateMetadata(template=r".../batch_(batch)/sample_(sample_id).*")

pm = PhenoMe()
df = pm.find_files("images/", metadata_fn=metadata_fn)
print(df.columns)  # includes file_path, batch, sample_id, ...

Functional helpers: For functional metadata extraction, see phenome.utils.metadata:

• default_metadata_from_path: Simple functional wrapper.
• get_metadata_from_path: Advanced functional wrapper.
• make_dataframe_metadata_fn: Create extractor from DataFrame.

See Also: For factory functions and presets, see phenome.utils.property_factories. For metadata utilities in math operations, see phenome.core.results_metadata.

MetadataBase

Base class for metadata extraction with configurable columns and ID handling.

Subclasses implement _extract to produce raw metadata; the base class ensures a unique id is always present and provides stable key generation for checkpoint matching.

Parameters:

• filename_columns (str or list of str): Column(s) for image filenames. List for multi-channel.
• unique_id_column (str): Column name for unique sample ID (default "id").
• mask_filename_column (str, optional): Column name for mask filename when metadata has explicit mask.
• mask_dir (str, optional): Root directory for mask resolution.
• data_dir (str, optional): Base directory for relative path ID generation.

Construction

Method

__init__

MetadataBase(
    filename_columns: 'str | list[str]' = 'filename',
    unique_id_column: 'str' = 'id',
    mask_filename_column: 'str | None' = None,
    mask_dir: 'str | None' = None,
    data_dir: 'str | None' = None
)

Identifiers

Method

get_id

MetadataBase.get_id(
    self,
    meta: 'dict[str, Any]'
) -> str

Return the unique ID from metadata.

Raises:

• KeyError: If the unique ID column is missing from meta.

Method

ensure_id

MetadataBase.ensure_id(
    self,
    meta: 'dict[str, Any]',
    paths: 'str | list[str]',
    data_dir: 'str | None' = None
) -> str

Inject or return unique ID in meta. Auto-generate if not present.

Parameters:

• meta (dict): Metadata dict (modified in place).
• paths (str or list of str): File path(s) for this sample.
• data_dir (str, optional): Base directory for ID generation. Uses instance data_dir if None.

Returns:

• str: The unique ID (existing or newly generated).

Method

to_stable_key

MetadataBase.to_stable_key(
    self,
    meta: 'dict[str, Any]'
) -> str

Build stable key for checkpoint matching.

Uses the unique ID when present and non-path-like; otherwise delegates to metadata_to_stable_key for a JSON-based stable key.

Extraction

Method

metadata_fn

MetadataBase.metadata_fn(
    self,
    path: 'str',
    data_dir: 'str | None' = None
) -> dict[str, Any]

Extract metadata for a path. Guarantees ‘id’ is present.

Parameters:

• path (str): File path.
• data_dir (str, optional): Base directory for ID generation.

Returns:

• dict: Metadata with file_path, metadata keys, and guaranteed id.

Mask resolution

Method

get_mask_path

MetadataBase.get_mask_path(
    self,
    meta: 'dict[str, Any]'
) -> str | None

Resolve mask path from metadata when mask_filename_column and mask_dir are set.

Returns:

• str or None: Full path to mask file, or None if not resolvable.

Property

mask_dir

Property on MetadataBase

Root directory for mask files.

Property

mask_filename_column

Property on MetadataBase

Column containing mask filename when using explicit mask lookup.

Grouping

Property

group_by

Property on MetadataBase

Column used for multi-channel grouping in find_files.

DefaultMetadata

Minimal metadata extractor: file_path and filename from path.

Single filename column. Auto-generates ID from path when not provided.

PathTemplateMetadata

Metadata extractor from path template with capture groups.

Uses parentheses for capture groups, e.g. .../(drug)/(time)/(crop_name).*. group_by is the last capture group that is not channel_index.

Construction

Method

__init__

PathTemplateMetadata(
    template: 'str',
    filename_columns: 'str | list[str]' = 'filename',
    unique_id_column: 'str' = 'id',
    mask_filename_column: 'str | None' = None,
    mask_dir: 'str | None' = None,
    data_dir: 'str | None' = None
)

Grouping

Property

group_by

Property on PathTemplateMetadata

Return a sample-level capture group, never channel_index.

DataFrameMetadata

Metadata lookup from DataFrame. Supports single and multi-channel modes.

Construction

Method

__init__

DataFrameMetadata(
    metadata_df: 'pd.DataFrame',
    filename_columns: 'str | list[str]' = 'filename',
    unique_id_column: 'str' = 'id',
    mask_filename_column: 'str | None' = None,
    mask_dir: 'str | None' = None,
    data_dir: 'str | None' = None
)

Extraction

Method

metadata_fn

DataFrameMetadata.metadata_fn(
    self,
    path: 'str',
    data_dir: 'str | None' = None
) -> dict[str, Any]

Extract metadata with data_dir-aware partial path lookup.