period_summary

period_summary

Weekly/monthly summary module.

Roll up daily metrics to weekly/monthly summaries: - Weekly summary of KPIs - Monthly totals and averages - Period-over-period comparison

Two modes of operation: 1. From raw signals: weekly_summary(counter_uuid, ...) 2. From pre-computed daily DataFrames: from_daily_data(daily_df)

PeriodSummary

PeriodSummary(
    dataframe: DataFrame, *, time_column: str = "systime"
)

Bases: Base

Aggregate daily metrics into weekly/monthly summaries.

Merge keys: [week_start, week_end] for weekly, [year, month] for monthly.

Two usage patterns:

Pattern A — from raw signals:

summary = PeriodSummary(df)
weekly = summary.weekly_summary(counter_uuid='prod')

Pattern B — pipeline (compose from upstream modules):

# Build a daily DataFrame from any combination of upstream modules
quality = QualityTracking(df).daily_quality_summary('ok', 'nok')
downtime = DowntimeTracking(df).availability_trend('state', window='1D')

# Merge on date
daily = quality.merge(downtime.rename(columns={'period': 'date'}), on='date')

# Roll up to weekly/monthly
weekly = PeriodSummary.from_daily_data(daily, freq='W')
monthly = PeriodSummary.from_daily_data(daily, freq='MS')

from_daily_data staticmethod

from_daily_data(
    daily_df: DataFrame,
    *,
    freq: str = "W",
    date_column: str = "date"
) -> pd.DataFrame

Roll up a pre-computed daily DataFrame to weekly or monthly.

This is the pipeline-friendly entry-point. It accepts any daily DataFrame (e.g. merged output of QualityTracking, DowntimeTracking, OEECalculator) and aggregates numeric columns.

Numeric columns are aggregated as follows: - Columns containing _pct or pct: averaged (mean). - Columns containing parts, quantity, production, minutes: summed. - All other numeric columns: summed.

The output always includes period_start, period_end, and days columns.

Parameters:

Name	Type	Description	Default
daily_df	DataFrame	DataFrame with a date column and numeric metric columns. Expected merge key: [date].	required
freq	str	Pandas frequency string. 'W' = weekly (Monday start), 'MS' = monthly.	'W'
date_column	str	Name of the date column.	'date'

Returns:

Type	Description
DataFrame	DataFrame with period_start, period_end, days, and aggregated
DataFrame	metric columns.

Example::

quality = QualityTracking(df).daily_quality_summary('ok', 'nok')
weekly = PeriodSummary.from_daily_data(quality, freq='W')
# → [period_start, period_end, days, ok_parts, nok_parts,
#    total_parts, quality_pct, ...]

weekly_summary

weekly_summary(
    counter_uuid: str,
    ok_counter_uuid: Optional[str] = None,
    nok_counter_uuid: Optional[str] = None,
    *,
    value_column: str = "value_integer"
) -> pd.DataFrame

Roll up daily production to weekly summaries from raw signals.

For pipeline usage with pre-computed DataFrames, use :meth:from_daily_data instead.

Parameters:

Name	Type	Description	Default
counter_uuid	str	UUID of production counter.	required
ok_counter_uuid	Optional[str]	UUID of good parts counter (optional).	None
nok_counter_uuid	Optional[str]	UUID of defective parts counter (optional).	None
value_column	str	Column containing counter values.	'value_integer'

Returns:

Type	Description
DataFrame	DataFrame with columns:
DataFrame	week_start, week_end, total_production, daily_avg, production_days, [ok_parts, nok_parts, quality_pct]

monthly_summary

monthly_summary(
    counter_uuid: str,
    ok_counter_uuid: Optional[str] = None,
    nok_counter_uuid: Optional[str] = None,
    *,
    value_column: str = "value_integer"
) -> pd.DataFrame

Roll up daily production to monthly summaries from raw signals.

For pipeline usage with pre-computed DataFrames, use :meth:from_daily_data instead.

Parameters:

Name	Type	Description	Default
counter_uuid	str	UUID of production counter.	required
ok_counter_uuid	Optional[str]	UUID of good parts counter (optional).	None
nok_counter_uuid	Optional[str]	UUID of defective parts counter (optional).	None
value_column	str	Column containing counter values.	'value_integer'

Returns:

Type	Description
DataFrame	DataFrame with columns:
DataFrame	year, month, total_production, daily_avg, production_days, [ok_parts, nok_parts, quality_pct]

compare_periods

compare_periods(
    counter_uuid: str,
    period1: tuple[str, str],
    period2: tuple[str, str],
    *,
    value_column: str = "value_integer"
) -> pd.DataFrame

Compare production between two time periods.

Parameters:

Name	Type	Description	Default
counter_uuid	str	UUID of production counter.	required
period1	tuple[str, str]	Tuple of (start_date, end_date) for first period.	required
period2	tuple[str, str]	Tuple of (start_date, end_date) for second period.	required
value_column	str	Column containing counter values.	'value_integer'

Returns:

Type	Description
DataFrame	DataFrame with columns:
DataFrame	metric, period1_value, period2_value, change, change_pct