Querying from Provenance Files

yProv4ml offers a set of directives to easily extract the information logged from the provenance.json file.

from yprov4ml import (
    list_activities, 
    list_entities, 
    get_parameter, 
    list_parameters,
    list_metrics, 
    list_metric_paths, 
    get_metric
)

import json
data = json.load(open(path_to_prov_json))     

Listing Functions

def list_activities(source : dict | str) -> list[str]
def list_entities(source : dict | str, entity_type: str | None = None) -> list[str]

• list_activities: Retrieves a list of all activity names stored in the provenance document.
• list_entities: Retrieves a list of entity names from the provenance document. Can be filtered by passing an explicit entity_type (e.g., "provml:Metric").

Parameter Retrieval

def get_parameter(source : dict | str, name: str, param: str, unwrap: bool = True) -> Any

Retrieves a single parameter value associated with a specified activity or entity key name.

def list_parameters(data : dict | str, name: str | None = None, unwrap: bool = True) -> dict[str, Any]

Retrieves a dictionary of key-value parameters. If name is omitted, it aggregates parameters across all entities and activities in the file.

Metric Management

def list_metrics(data : dict | str, context: str | None = None, source: str | None = None) -> pd.DataFrame

Summarizes all metric entities recorded in the provenance JSON into a single Pandas DataFrame with metadata columns (label, context, source, csv_path).

def list_metric_paths(data : dict | str, context: str | None = None, source : str | None = None, file_type : str | None = None) -> dict[str, str]

Returns a dictionary mapping metric entity identifiers to their underlying dataset file paths.

def get_metric(data : dict | str, name: str | None = None, context: str | None = None, source : str | None = None)

Fetches and automatically loads the data object for a metric (named in the format {name}_{context}_{source}) using the appropriate reader.

Project Helpers

def list_runs_in_proj(path: str | Path) -> list[Path]
def list_provjson_in_proj(path : str | Path) -> list[Path]

• list_runs_in_proj: Returns paths to all run subdirectories found within a given project folder.
• list_provjson_in_proj: Searches across run directories to locate all available .json provenance files.