src.processing.calculator

Share of Search metrics calculation.

Module Contents

class src.processing.calculator.MetricsCalculator[source]

Calculate Share of Search metrics and derivatives.

Calculate Share of Search percentages.

Parameters:

df – DataFrame with columns: date, query, value

Returns:

DataFrame with added share_of_search column

Raises:

CalculationError – If calculation fails

calculate_period_metrics(df: pandas.DataFrame, group_by: str = 'query') → pandas.DataFrame[source]

Calculate aggregate metrics per query.

Parameters:

  • df – DataFrame with share_of_search column

  • group_by – Column to group by (default: query)

Returns:

DataFrame with aggregate metrics per query

calculate_trend_direction(df: pandas.DataFrame) → pandas.DataFrame[source]

Calculate trend direction (rising/stable/falling).

Parameters:

df – DataFrame with date and share_of_search columns

Returns:

DataFrame with added trend_direction column

calculate_momentum(df: pandas.DataFrame, periods: int = 3) → pandas.DataFrame[source]

Calculate momentum (rate of change).

Parameters:

  • df – DataFrame with share_of_search column

  • periods – Number of periods to look back

Returns:

DataFrame with added momentum column

calculate_volatility(df: pandas.DataFrame, window: int = 4) → pandas.DataFrame[source]

Calculate rolling volatility for all queries.

Parameters:

  • df – DataFrame with share_of_search column

  • window – Rolling window size

Returns:

DataFrame with added volatility column

calculate_volatility_value(df: pandas.DataFrame, query: str, window: int = 4) → float[source]

Calculate volatility value for a specific query.

Parameters:

  • df – DataFrame with share_of_search column

  • query – Query to calculate volatility for

  • window – Rolling window size

Returns:

Volatility value (standard deviation) for the query

detect_anomalies(df: pandas.DataFrame, column: str = 'share_of_search', threshold: float = 2.5) → pandas.DataFrame[source]

Detect anomalies using z-score method.

Parameters:

  • df – DataFrame to analyze

  • column – Column to check for anomalies

  • threshold – Z-score threshold for anomaly detection

Returns:

DataFrame with added is_anomaly and z_score columns

calculate_market_concentration(df: pandas.DataFrame) → Dict[str, float][source]

Calculate Herfindahl-Hirschman Index (HHI) for market concentration.

Parameters:

df – DataFrame with share_of_search column

Returns:

Dictionary with HHI metrics

calculate_all_metrics(df: pandas.DataFrame, smoothing_window: int = 3) → pandas.DataFrame[source]

Calculate all available metrics.

Parameters:

  • df – Input DataFrame with date, query, value columns

  • smoothing_window – Window for smoothing calculations

Returns:

DataFrame with all calculated metrics