target_tracking

target_tracking

Target vs actual comparison module.

Generic module for comparing any metric to targets: - Shift/daily target comparison - Variance analysis - Target achievement tracking over time

TargetEvents

TargetEvents(
    dataframe: DataFrame,
    *,
    time_column: str = "systime",
    shift_definitions: (
        dict[str, tuple[str, str]] | None
    ) = None
)

Bases: Base

Compare any production metric to targets.

Every plant has daily/shift targets. This module provides a generic way to compare actual performance against those targets.

Merge keys: [date, shift] for shift-level, [date] for daily.

Pipeline example::

target = TargetEvents(df)
result = target.compare_to_target('counter', {'shift_1': 450})
# → merge with PerformanceLossEvents.performance_by_shift() on [date, shift]
# → merge with QualityEvents.nok_by_shift() on [date, shift]
# → result['status'] column enables filtering/alerting

Example usage

tracker = TargetEvents(df)

Compare counter to fixed target

result = tracker.compare_to_target( metric_uuid='production_counter', targets={'shift_1': 450, 'shift_2': 450, 'shift_3': 400}, )

Achievement summary over time

summary = tracker.target_achievement_summary( metric_uuid='production_counter', daily_target=1300, )

compare_to_target

compare_to_target(
    metric_uuid: str,
    targets: dict[str, float],
    *,
    value_column: str = "value_integer",
    handle_resets: bool = True,
    production_day: bool = True
) -> pd.DataFrame

Compare actual metric to per-shift targets.

Parameters:

Name	Type	Description	Default
metric_uuid	str	UUID of the metric signal (counter).	required
targets	dict[str, float]	Dict mapping shift names to target values.	required
value_column	str	Column containing metric values.	'value_integer'
handle_resets	bool	When True (default), treat a decreasing counter as a reset and count the production after the reset instead of losing it, so actual is the reset-aware total. The increments are computed once over the whole signal and booked to the shift of the reading that reports them, so the shifts add up to the signal total. The result gains a resets column with the number of resets observed in each shift. When False, actual is simply max(0, last - first) and a shift containing a reset reports too little.	True
production_day	bool	When True, the post-midnight portion of an overnight shift (e.g. 22:00 -> 06:00) is attributed to the shift's start date, so each (date, shift) group is one contiguous interval (the default). When False, readings are grouped by their raw calendar date; a night shift is then split across two dates and, with handle_resets=False, its group spans the whole day so last - first sweeps in other shifts' production. Only affects schedules with an overnight shift.	True

Returns:

Type	Description
DataFrame	DataFrame with columns:
DataFrame	date, shift, actual, target, variance, achievement_pct, status
DataFrame	resets (only when handle_resets=True)

target_achievement_summary

target_achievement_summary(
    metric_uuid: str,
    daily_target: float,
    *,
    value_column: str = "value_integer",
    handle_resets: bool = True
) -> pd.DataFrame

Summarize target achievement over time.

Parameters:

Name	Type	Description	Default
metric_uuid	str	UUID of the metric signal (counter).	required
daily_target	float	Daily production target.	required
value_column	str	Column containing metric values.	'value_integer'
handle_resets	bool	When True (default), treat a decreasing counter as a reset and count the production after the reset instead of losing it, so actual is the reset-aware daily total, with increments booked to the day of the reading that reports them so the days add up to the signal total. The result gains a resets column with the number of resets observed each day. When False, actual is simply max(0, last - first) and a day containing a reset reports too little.	True

Returns:

Type	Description
DataFrame	DataFrame with columns:
DataFrame	date, actual, target, variance, achievement_pct, status
DataFrame	resets (only when handle_resets=True)

target_hit_rate

target_hit_rate(
    metric_uuid: str,
    daily_target: float,
    *,
    value_column: str = ...,
    as_frame: Literal[True] = ...
) -> pd.DataFrame

target_hit_rate(
    metric_uuid: str,
    daily_target: float,
    *,
    value_column: str = ...,
    as_frame: Literal[False]
) -> dict[str, float | int]

target_hit_rate(
    metric_uuid: str,
    daily_target: float,
    *,
    value_column: str = "value_integer",
    as_frame: bool = True
) -> pd.DataFrame | dict[str, float | int]

How often are targets met?

Parameters:

Name	Type	Description	Default
metric_uuid	str	UUID of the metric signal (counter).	required
daily_target	float	Daily production target.	required
value_column	str	Column containing metric values.	'value_integer'
as_frame	bool	When True (default), return a one-row DataFrame (see below). as_frame=False returns the dictionary form; it is deprecated, emits a DeprecationWarning and will be removed in the next major release.	True

Returns:

Name	Type	Description
	DataFrame | dict[str, float | int]	With as_frame=True (default), a one-row summary DataFrame with
columns	DataFrame | dict[str, float | int]
	DataFrame | dict[str, float | int]	start, end, duration_seconds: first analysed day's midnight to the midnight after the last day (tz-aware in the data's tz; NaT / 0 without data)
	DataFrame | dict[str, float | int]	total_days: Number of days analyzed.
	DataFrame | dict[str, float | int]	days_on_target: Days where target was met.
	DataFrame | dict[str, float | int]	hit_rate_pct: Percentage of days meeting target.
	DataFrame | dict[str, float | int]	avg_achievement_pct: Average achievement across days.
	DataFrame | dict[str, float | int]	With as_frame=False (deprecated), a dict with the keys
	DataFrame | dict[str, float | int]	total_days, days_on_target, hit_rate_pct, avg_achievement_pct.