Quick Metric

Welcome to Quick Metric - a framework for quickly creating metrics using easy-to-edit YAML configs and reusable methods to filter, calculate, and transform data.

Purpose

Quick Metric empowers data scientists and analysts to:

• Define custom metric methods using simple decorators
• Configure complex data filtering via YAML or dictionary configurations
• Apply multiple metrics to pandas DataFrames consistently
• Integrate metrics generation into data processing pipelines
• Keep metric definitions separate from data processing logic

Key Features

• @metric_method Decorator - Register custom metric functions with a simple decorator
• Core Functions - Main entry points: generate_metrics() and interpret_metric_instructions()
• Multiple Output Formats - Results as nested dict, pandas DataFrame, or list of records
• Data Filtering - Complex filtering logic with YAML configuration support
• Method Application - Execute methods on filtered data with error handling
• Pipeline Integration - Seamless integration with oops-its-a-pipeline workflows

Quick Start

Clone the repository:

git clone <repository-url>
cd quick_metric

Install Quick Metric and its dependencies:

uv (recommended)pip

uv venv && source .venv/bin/activate
uv pip install -e .

python -m venv .venv && source .venv/bin/activate
pip install -e .

Basic usage example:

from quick_metric import metric_method, generate_metrics
import pandas as pd

# Define custom metric methods
@metric_method
def count_records(data):
    """Count the number of records."""
    return len(data)

@metric_method  
def mean_value(data, column='value'):
    """Calculate mean of a column."""
    return data[column].mean() if column in data.columns else 0.0

# Create data and configuration
data = pd.DataFrame({
    'category': ['A', 'B', 'A', 'C'],
    'value': [10, 20, 15, 30],
    'status': ['active', 'inactive', 'active', 'active']
})

config = {
    'active_category_a': {
        'method': ['count_records', 'mean_value'],
        'filter': {
            'and': {
                'category': 'A',
                'status': 'active'
            }
        }
    }
}

# Generate metrics
results = generate_metrics(data, config)
print(results['active_category_a']['count_records'])  # 2
print(results['active_category_a']['mean_value'])     # 12.5

Output Formats

Quick Metric supports multiple output formats to suit different use cases:

# Default nested dictionary format (backward compatible)
nested_results = generate_metrics(data, config)
# Returns: {'metric_name': {'method_name': result}}

# DataFrame format (perfect for analysis and visualization)
df_results = generate_metrics(data, config, output_format="dataframe")
# Returns: pandas DataFrame with columns [metric, method, value, value_type]

# Records format (ideal for APIs and databases)
records_results = generate_metrics(data, config, output_format="records")
# Returns: [{'metric': 'metric_name', 'method': 'method_name', 'value': result}]

Pipeline Integration

Quick Metric integrates seamlessly with oops-its-a-pipeline:

from oops_its_a_pipeline import Pipeline, PipelineConfig
from quick_metric.pipeline import create_metrics_stage

class Config(PipelineConfig):
    model_config = {'arbitrary_types_allowed': True}
    data = your_dataframe
    config = your_metrics_config

pipeline = Pipeline(Config()).add_stage(create_metrics_stage())
results = pipeline.run("analysis")

Getting Started

New to Quick Metric? Start with our Getting Started guide to learn the fundamentals and begin using the framework in your analytical workflows.

API Reference

Explore the complete API Reference for detailed documentation of all modules, classes, and functions.