API Reference

This section provides detailed API documentation for Quick Metric, covering core functions, method definitions, output formats, and pipeline integration.

Module Overview

The main quick_metric module provides the complete public API for the framework. For detailed documentation of individual components, see the specific pages:

• Core Functions - generate_metrics() and core processing functions
• Method Definitions - @metric_method decorator and method management
• Output Formats - Result formatting and transformation utilities
• Filter - Data filtering and selection functions
• Apply Methods - Method application and execution utilities
• Pipeline Integration - Pipeline processing and workflow functions
• Exceptions - Custom exception classes

API Documentation

Note

The documentation below and on following pages is automatically generated from the module docstrings and provides comprehensive coverage of all public functions, classes, and methods

Quick Metric framework for creating metrics from pandas DataFrames.

A framework for applying filters and methods to pandas DataFrames using YAML configurations. Register custom metric methods with decorators and configure data filtering through declarative specifications.

Functions:

Name	Description
generate_metrics : Apply metric configurations to pandas DataFrames
metric_method : Decorator to register custom metric functions
get_method : Retrieve a registered metric method by name
list_method_names : List all registered metric method names
get_registered_methods : Get dictionary of all registered methods
clear_methods : Clear all registered methods from registry

Examples:

Basic usage:

import pandas as pd
from quick_metric import metric_method, generate_metrics

@metric_method
def count_records(data):
    return len(data)

@metric_method
def mean_value(data, column='value'):
    return data[column].mean()

data = pd.DataFrame({'category': ['A', 'B', 'A'], 'value': [10, 20, 30]})
config = {
    'category_a_metrics': {
        'method': ['count_records', 'mean_value'],
        'filter': {'category': 'A'}
    }
}

results = generate_metrics(data, config)
print(results['category_a_metrics']['count_records'])  # 2
print(results['category_a_metrics']['mean_value'])     # 20.0

generate_metrics(data, config, metrics_methods=None, output_format='nested')

Generate metrics from data using configuration (main entry point).

This is the primary entry point for the quick_metric framework. It provides a simple interface for generating metrics from pandas DataFrames using either YAML configuration files or dictionary configurations.

Parameters:

Name	Type	Description	Default
data	DataFrame	The DataFrame to process and generate metrics from.	required
config	Path or Dict	Either a Path object pointing to a YAML configuration file or a dictionary containing metric instructions. If a Path, the YAML file should contain a 'metric_instructions' key with the configuration.	required
metrics_methods	Dict	Dictionary of available methods. If None, uses the default registered methods from METRICS_METHODS.	None
output_format	str or OutputFormat	Format for the output. Options: - "nested": Current dict of dicts format {'metric': {'method': result}} - "dataframe": Pandas DataFrame with columns [metric, method, value, value_type] - "records": List of dicts [{'metric': '...', 'method': '...', 'value': ...}]	"nested"

Returns:

Type	Description
Union[dict, DataFrame, list[dict]]	Results in the specified format. The exact type depends on output_format: - dict: When output_format="nested" (default) - pd.DataFrame: When output_format="dataframe" - list[dict]: When output_format="records"

Examples:

Using a dictionary configuration (default nested format):

import pandas as pd
from quick_metric import generate_metrics, metric_method

@metric_method
def count_records(data):
    return len(data)

data = pd.DataFrame({'category': ['A', 'B', 'A'], 'value': [1, 2, 3]})
config = {
    'category_a_count': {
        'method': ['count_records'],
        'filter': {'category': 'A'}
    }
}
results = generate_metrics(data, config)
# Returns: {'category_a_count': {'count_records': 2}}

Using DataFrame output format:

df_results = generate_metrics(data, config, output_format="dataframe")
# Returns: DataFrame with columns [metric, method, value, value_type]

Using records output format:

records = generate_metrics(data, config, output_format="records")
# Returns: [{'metric': 'category_a_count', 'method': 'count_records', 'value': 2}]

Using a YAML file:

from pathlib import Path
config_path = Path('my_metrics.yaml')
results = generate_metrics(data, config_path)

Raises:

Type	Description
FileNotFoundError	If the config path does not exist.
MetricSpecificationError	If a YAML file doesn't contain 'metric_instructions' key or is invalid. If config parameter or output_format is not a valid type.

Source code in quick_metric/_core.py

def generate_metrics(
    data: pd.DataFrame,
    config: Union[Path, dict],
    metrics_methods: Optional[dict] = None,
    output_format: Union[str, OutputFormat] = "nested",
) -> Union[dict, pd.DataFrame, list[dict]]:
    """
    Generate metrics from data using configuration (main entry point).

    This is the primary entry point for the quick_metric framework. It provides
    a simple interface for generating metrics from pandas DataFrames using
    either YAML configuration files or dictionary configurations.

    Parameters
    ----------
    data : pd.DataFrame
        The DataFrame to process and generate metrics from.
    config : Path or Dict
        Either a Path object pointing to a YAML configuration file or a
        dictionary containing metric instructions. If a Path, the YAML file
        should contain a 'metric_instructions' key with the configuration.
    metrics_methods : Dict, optional
        Dictionary of available methods. If None, uses the default registered
        methods from METRICS_METHODS.
    output_format : str or OutputFormat, default "nested"
        Format for the output. Options:
        - "nested": Current dict of dicts format {'metric': {'method': result}}
        - "dataframe": Pandas DataFrame with columns [metric, method, value, value_type]
        - "records": List of dicts [{'metric': '...', 'method': '...', 'value': ...}]

    Returns
    -------
    Union[dict, pd.DataFrame, list[dict]]
        Results in the specified format. The exact type depends on output_format:
        - dict: When output_format="nested" (default)
        - pd.DataFrame: When output_format="dataframe"
        - list[dict]: When output_format="records"

    Examples
    --------
    Using a dictionary configuration (default nested format):

    ```python
    import pandas as pd
    from quick_metric import generate_metrics, metric_method

    @metric_method
    def count_records(data):
        return len(data)

    data = pd.DataFrame({'category': ['A', 'B', 'A'], 'value': [1, 2, 3]})
    config = {
        'category_a_count': {
            'method': ['count_records'],
            'filter': {'category': 'A'}
        }
    }
    results = generate_metrics(data, config)
    # Returns: {'category_a_count': {'count_records': 2}}
    ```

    Using DataFrame output format:

    ```python
    df_results = generate_metrics(data, config, output_format="dataframe")
    # Returns: DataFrame with columns [metric, method, value, value_type]
    ```

    Using records output format:

    ```python
    records = generate_metrics(data, config, output_format="records")
    # Returns: [{'metric': 'category_a_count', 'method': 'count_records', 'value': 2}]
    ```

    Using a YAML file:

    ```python
    from pathlib import Path
    config_path = Path('my_metrics.yaml')
    results = generate_metrics(data, config_path)
    ```

    Raises
    ------
    FileNotFoundError
        If the config path does not exist.
    MetricSpecificationError
        If a YAML file doesn't contain 'metric_instructions' key or is invalid.
        If config parameter or output_format is not a valid type.
    """
    logger.info("Starting metric generation")

    # Convert string format to enum
    if isinstance(output_format, str):
        try:
            output_format = OutputFormat(output_format)
        except ValueError as e:
            valid_formats = [f.value for f in OutputFormat]
            raise MetricSpecificationError(
                f"Invalid output_format '{output_format}'. Valid options: {valid_formats}",
                method_spec=output_format,
            ) from e

    # Handle different config input types
    if isinstance(config, Path):
        logger.debug(f"Loading configuration from file: {config}")
        metric_instructions = read_metric_instructions(config)
    elif isinstance(config, dict):
        logger.debug("Using provided dictionary configuration")
        metric_instructions = config
    else:
        raise MetricSpecificationError(
            f"Config must be a pathlib.Path object or dict, got {type(config)}", method_spec=config
        )

    # Generate metrics using the existing function
    results = interpret_metric_instructions(
        data=data,
        metric_instructions=metric_instructions,
        metrics_methods=metrics_methods,
    )

    # Convert to requested format
    if output_format != OutputFormat.NESTED:
        logger.debug(f"Converting results to {output_format.value} format")
        results = convert_to_format(results, output_format)

    logger.success("Metric generation completed successfully")
    return results

clear_methods()

Clear all registered methods (for testing).

Source code in quick_metric/_method_definitions.py

def clear_methods() -> None:
    """Clear all registered methods (for testing)."""
    _registry.clear()

get_method(name)

Get a registered method by name.

Source code in quick_metric/_method_definitions.py

def get_method(name: str) -> Callable:
    """Get a registered method by name."""
    return _registry.get_method(name)

get_registered_methods()

Get all registered methods.

Source code in quick_metric/_method_definitions.py

def get_registered_methods() -> dict[str, Callable]:
    """Get all registered methods."""
    return _registry.get_methods()

list_method_names()

Get list of registered method names.

Source code in quick_metric/_method_definitions.py

def list_method_names() -> list[str]:
    """Get list of registered method names."""
    return _registry.list_method_names()

metric_method(func_or_name=None)

Decorator to register a user function as a metric method, or query registered methods.

Can be used in three ways: 1. As a decorator: @metric_method 2. To get all methods: metric_method() 3. To get a specific method: metric_method('method_name')

Parameters:

Name	Type	Description	Default
func_or_name	Callable or str	User function to register when used as decorator, or method name to retrieve.	None

Returns:

Type	Description
Callable or dict	When used as decorator: returns the original function unchanged. When called without args: returns dict of all registered methods. When called with method name: returns the specific method.

Examples:

As a decorator:

@metric_method
def my_custom_metric(data):
    return len(data)

To get all methods:

all_methods = metric_method()
print(list(all_methods.keys()))

To get a specific method:

my_method = metric_method('my_custom_metric')

Source code in quick_metric/_method_definitions.py

def metric_method(func_or_name=None):
    """
    Decorator to register a user function as a metric method, or query registered methods.

    Can be used in three ways:
    1. As a decorator: @metric_method
    2. To get all methods: metric_method()
    3. To get a specific method: metric_method('method_name')

    Parameters
    ----------
    func_or_name : Callable or str, optional
        User function to register when used as decorator, or method name to retrieve.

    Returns
    -------
    Callable or dict
        When used as decorator: returns the original function unchanged.
        When called without args: returns dict of all registered methods.
        When called with method name: returns the specific method.

    Examples
    --------
    As a decorator:

    ```python
    @metric_method
    def my_custom_metric(data):
        return len(data)
    ```

    To get all methods:

    ```python
    all_methods = metric_method()
    print(list(all_methods.keys()))
    ```

    To get a specific method:

    ```python
    my_method = metric_method('my_custom_metric')
    ```
    """
    # Case 1: Called without arguments - return all methods
    if func_or_name is None:
        return _registry.get_methods()

    # Case 2: Called with a string - return specific method
    if isinstance(func_or_name, str):
        return _registry.get_method(func_or_name)

    # Case 3: Called with a function (decorator usage)
    if callable(func_or_name):
        return _registry.register(func_or_name)

    raise ValueError(f"Invalid argument type: {type(func_or_name)}")