Describer API

Data description module that provides statistical summaries and insights from datasets.

Class Architecture

classDiagram
    class Describer {
        -config: DescriberConfig
        -mode: str
        +__init__(method: str, mode: str, **kwargs)
        +create() void
        +eval(data: dict) dict
        #_configure_implementation(method: str, **kwargs) void
        #_create_evaluator_class() BaseEvaluator
    }

    class DescriberConfig {
        +DEFAULT_DESCRIBING_METHOD: str
        +mode: str
        +method: str
        +method_code: int
        +eval_method: str
        +custom_params: dict
        +__post_init__() void
        #_init_eval_method() void
    }

    class Evaluator {
        <<abstract>>
        -config: EvaluatorConfig
        -_impl: BaseEvaluator
        +__init__(method: str, **kwargs)
        +create() void
        +eval(data: dict) dict
        #_configure_implementation(method: str, **kwargs) void
        #_create_evaluator_class() BaseEvaluator
    }

    class DescriberDescribe {
        +REQUIRED_INPUT_KEYS: list
        +EXEC_GRANULARITY_MAP: dict
        +MODULE_MAP: dict
        -desc_config: DescriberDescribeConfig
        +__init__(config: dict)
        #_eval(data: dict) dict
        #_get_columnwise(columnwise_desc: list) DataFrame
    }

    class DescriberCompare {
        +REQUIRED_INPUT_KEYS: list
        +COMPARE_METHOD_MAP: dict
        -base_describer: DescriberDescribe
        -target_describer: DescriberDescribe
        +__init__(config: dict)
        #_eval(data: dict) dict
        #_apply_comparison(base_df: DataFrame, target_df: DataFrame, method: str) DataFrame
        #_calculate_jsdivergence(base_df: DataFrame, target_df: DataFrame) dict
    }

    class BaseEvaluator {
        <<abstract>>
        +config: dict
        +__init__(config: dict)
        +create() void
        +eval(data: dict) dict
        #_eval(data: dict) dict
    }

    class DescriberDescribeConfig {
        +eval_method: str
        +describe_method: list
        +percentile: float
        +AVAILABLE_DESCRIBE_METHODS: list
        +REQUIRED_INPUT_KEYS: list
        +update_data(data: dict) void
    }

    class DescriberCompareConfig {
        +eval_method: str
        +stats_method: list
        +compare_method: str
        +aggregated_method: str
        +summary_method: str
        +columns_info: dict
        +AVAILABLE_STATS_METHODS: list
        +REQUIRED_INPUT_KEYS: list
        +update_data(data: dict) void
    }

    class EvaluatorConfig {
        <<abstract>>
        +method: str
        +method_code: int
        +eval_method: str
        +custom_params: dict
        +__post_init__() void
        #_init_eval_method() void
    }

    Evaluator <|-- Describer : extends
    EvaluatorConfig <|-- DescriberConfig : extends
    BaseEvaluator <|-- DescriberDescribe : implements
    BaseEvaluator <|-- DescriberCompare : implements
    
    Describer *-- DescriberConfig : uses
    Describer ..> DescriberDescribe : creates
    Describer ..> DescriberCompare : creates
    DescriberDescribe *-- DescriberDescribeConfig : uses
    DescriberCompare *-- DescriberCompareConfig : uses
    DescriberCompare ..> DescriberDescribe : reuses
    
    DescriberDescribeConfig --|> BaseConfig : extends
    DescriberCompareConfig --|> BaseConfig : extends
    DescriberConfig --|> EvaluatorConfig : extends

    class BaseConfig {
        <<abstract>>
        #_logger: Logger
        +__post_init__() void
    }

    %% 馬卡龍配色方案 - 低彩度柔和色調
    style Describer fill:#e1f0ff,stroke:#7db8e8,stroke-width:3px
    style Evaluator fill:#f3e6ff,stroke:#9966cc,stroke-width:2px
    style BaseEvaluator fill:#f3e6ff,stroke:#9966cc,stroke-width:2px
    style DescriberDescribe fill:#ffe6d5,stroke:#ffb380,stroke-width:2px
    style DescriberCompare fill:#ffe6d5,stroke:#ffb380,stroke-width:2px
    style DescriberConfig fill:#f3e6ff,stroke:#9966cc,stroke-width:2px
    style EvaluatorConfig fill:#f3e6ff,stroke:#9966cc,stroke-width:2px
    style DescriberDescribeConfig fill:#f3e6ff,stroke:#9966cc,stroke-width:2px
    style DescriberCompareConfig fill:#f3e6ff,stroke:#9966cc,stroke-width:2px
    style BaseConfig fill:#f3e6ff,stroke:#9966cc,stroke-width:2px

Legend:

• Blue box: Main class
• Orange box: Implementation classes
• Light purple box: Configuration classes
• <|--: Inheritance relationship
• *--: Composition relationship
• ..>: Dependency relationship

Basic Usage

from petsard.evaluator import Describer

# Basic description
describer = Describer(method='describe')
describer.create()
results = describer.eval(data={'data': df})

# Compare mode
describer = Describer(method='describe', mode='compare')
describer.create()
results = describer.eval(data={'base': df1, 'target': df2})

Constructor (init)

Initialize a Describer instance for data description and analysis.

Syntax

def __init__(
    method: str,
    mode: str = "describe",
    **kwargs
)

Parameters

• method : str, required

  • Evaluation method to use
  • Typically use “describe” for Describer
  • Default: No default value, must be specified

• mode : str, optional

  • Operation mode for the describer
  • “describe”: Single dataset description (default)
  • “compare”: Dataset comparison
  • Default: "describe"

• **kwargs : dict, optional

  • Additional parameters passed to the underlying evaluator
  • For describe mode: supports DescriberDescribe parameters
  • For compare mode: supports DescriberCompare parameters

Returns

• Describer
  • Initialized Describer instance

Examples

from petsard.evaluator import Describer

# Basic description mode
describer = Describer(method='describe')

# Compare mode with additional parameters
describer = Describer(
    method='describe',
    mode='compare',
    stats_method=['mean', 'std', 'jsdivergence'],
    compare_method='pct_change'
)

# Custom describe methods
describer = Describer(
    method='describe',
    describe_method=['mean', 'median', 'std', 'corr']
)

Notes

• Mode selection: Choose “describe” for single dataset analysis, “compare” for comparing multiple datasets
• Parameter naming: Compare mode recommends using base/target instead of the legacy ori/syn (still backward compatible)
• Method flexibility: Supports various statistical methods through describe_method parameter
• Recommendation: Use YAML configuration for complex setups
• Backward compatibility: Maintains compatibility with existing Evaluator interface
• Documentation note: This documentation is for internal development team reference only