asset_health_index

asset_health_index

Asset health index: fuse several degradation signals into one score.

DegradationDetectionEvents scores one signal at a time. A real asset degrades across several of them at once -- vibration climbs while the bearing temperature drifts and the motor current gets noisier -- and a per-signal score cannot say how healthy the machine is, only how healthy one of its sensors looks.

This detector evaluates every configured signal over the same window grid, scores each with the same drift / variance / trend penalty model used by :meth:~ts_shape.events.maintenance.degradation_detection.DegradationDetectionEvents.health_score, and fuses the per-signal scores into a single weighted asset index. Each signal carries a failure mode label, so the fused row also names the mode that dominates the loss of health, and a confidence level that reports how much of the configured signal weight actually had data in the window.

AssetHealthIndexEvents

AssetHealthIndexEvents(
    dataframe: DataFrame,
    asset_id: str,
    signals: Mapping[str, str | Mapping[str, Any]],
    *,
    event_uuid: str = "maint:asset_health",
    value_column: str = "value_double",
    time_column: str = "systime",
    uuid_column: str = "uuid"
)

Bases: Base

Maintenance: multi-signal asset health fusion.

Each asset is described by a mapping of signal UUID to a failure mode (and optionally a weight)::

AssetHealthIndexEvents(
    df,
    asset_id="press-01",
    signals={
        "vib:press-01": "bearing",
        "temp:press-01": {"failure_mode": "thermal", "weight": 2.0},
        "curr:press-01": {"failure_mode": "electrical"},
    },
)

A bare string is shorthand for {"failure_mode": <str>, "weight": 1.0}. Weights express failure-mode criticality: a thermal runaway that scraps the tool should outweigh a slow bearing drift.

Methods: - health_index: fused 0-100 asset score per window. - health_events: point events when the index crosses warning/critical. - signal_contributions: per-signal breakdown of the health loss. - maintenance_forecast: days until the index reaches a critical level.

Initialize the asset health index.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Timeseries frame holding every configured signal.	required
asset_id	str	Identifier of the asset the signals belong to. It is emitted as source_uuid so the event log binds the rows to one asset object.	required
signals	Mapping[str, str | Mapping[str, Any]]	Mapping of signal UUID to failure mode (string) or to a {"failure_mode": str, "weight": float} mapping.	required
event_uuid	str	UUID stamped on emitted events.	'maint:asset_health'
value_column	str	Column holding the numeric readings.	'value_double'
time_column	str	Timestamp column.	'systime'
uuid_column	str	Column identifying the signal.	'uuid'

Raises:

Type	Description
ValueError	If signals is empty or a weight is not positive.

health_index

health_index(
    *, window: str = "1h", baseline_window: str = "24h"
) -> pd.DataFrame

Fuse the configured signals into one asset health score per window.

A signal with no data in a window is skipped rather than scored as zero; confidence_level reports the share of the configured weight that was actually available, so a score computed from one of four signals is visibly weaker evidence than a score from all four.

Parameters:

Name	Type	Description	Default
window	str	Evaluation window (e.g. '1h', '1D').	'1h'
baseline_window	str	Opening period of each signal used as its healthy reference for drift and variance.	'24h'

Returns:

Type	Description
DataFrame	Summary-shape DataFrame: start, end, duration_seconds,
DataFrame	uuid, source_uuid, asset_id, asset_health_score,
DataFrame	dominant_failure_mode, worst_signal_uuid,
DataFrame	signals_available, signals_expected, confidence_level,
DataFrame	sample_count.

health_events

health_events(
    *,
    window: str = "1h",
    baseline_window: str = "24h",
    warning_threshold: float = 70.0,
    critical_threshold: float = 50.0,
    only_crossings: bool = True
) -> pd.DataFrame

Emit an event when the fused index falls to warning or critical.

Parameters:

Name	Type	Description	Default
window	str	Evaluation window passed to :meth:health_index.	'1h'
baseline_window	str	Baseline period passed to :meth:health_index.	'24h'
warning_threshold	float	Score at or below which a warning fires.	70.0
critical_threshold	float	Score at or below which a critical fires.	50.0
only_crossings	bool	When True (default) only the window that enters a severity band emits a row, so a machine sitting at 40 for a week reports one critical, not 168. Set False to emit every window that sits below a threshold.	True

Returns:

Type	Description
DataFrame	Point-shape DataFrame: systime, uuid, source_uuid,
DataFrame	asset_id, asset_health_score, severity, threshold,
DataFrame	dominant_failure_mode, confidence_level, direction.

Raises:

Type	Description
ValueError	If critical_threshold exceeds warning_threshold.

signal_contributions

signal_contributions(
    *, window: str = "1h", baseline_window: str = "24h"
) -> pd.DataFrame

Rank the configured signals by how much health they cost the asset.

The contribution of a signal is its mean weighted health deficit (100 - health) * weight over the evaluated windows, expressed as a share of the total deficit. A perfectly healthy asset has no deficit to distribute and every contribution is 0.

Parameters:

Name	Type	Description	Default
window	str	Evaluation window passed to the per-signal scorer.	'1h'
baseline_window	str	Baseline period passed to the per-signal scorer.	'24h'

Returns:

Type	Description
DataFrame	Static-shape DataFrame: asset_id, signal_uuid,
DataFrame	failure_mode, weight, mean_health, min_health,
DataFrame	weighted_deficit, contribution_pct, windows, rank,
DataFrame	method.

maintenance_forecast

maintenance_forecast(
    *,
    window: str = "1h",
    baseline_window: str = "24h",
    critical_threshold: float = 50.0,
    min_confidence: float = 0.5
) -> pd.DataFrame

Project when the asset index reaches critical_threshold.

Fits a least-squares line through the fused index and extrapolates it to the threshold. confidence is the fit's R²: a flat but noisy index nearly always slopes slightly one way, so a fit below min_confidence reports its slope and confidence but no horizon, rather than handing out a maintenance date the data cannot support. An index that is flat or improving likewise yields NaN for the horizon columns.

Parameters:

Name	Type	Description	Default
window	str	Evaluation window passed to :meth:health_index.	'1h'
baseline_window	str	Baseline period passed to :meth:health_index.	'24h'
critical_threshold	float	Score treated as "intervention required".	50.0
min_confidence	float	Minimum R² of the trend fit before a horizon is projected. Pass 0.0 to always project.	0.5

Returns:

Type	Description
DataFrame	Summary-shape DataFrame with a single row: start, end,
DataFrame	duration_seconds, uuid, source_uuid, asset_id,
DataFrame	current_health, decline_per_day,
DataFrame	recommended_maintenance_days, forecast_time,
DataFrame	critical_threshold, confidence, sample_count,
DataFrame	method.