inventory_monitoring

inventory_monitoring

Inventory monitoring events for supply chain timeseries.

Detects low stock intervals, calculates consumption rates, identifies reorder point breaches, and predicts stockouts.

InventoryMonitoringEvents

InventoryMonitoringEvents(
    dataframe: DataFrame,
    level_uuid: str,
    *,
    event_uuid: str = "sc:inventory",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Monitor inventory levels from a timeseries signal and detect supply chain events.

Each inventory level is tracked via a UUID signal whose numeric value represents the current stock quantity.

Example usage

tracker = InventoryMonitoringEvents(df, level_uuid='warehouse_a_level') low = tracker.detect_low_stock(min_level=100, hold='5min') rate = tracker.consumption_rate(window='1h') breach = tracker.reorder_point_breach(reorder_level=200, safety_stock=50) prediction = tracker.stockout_prediction(consumption_rate_window='4h')

Initialize inventory monitoring.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	Input DataFrame with timeseries data.	required
level_uuid	str	UUID of the inventory level signal.	required
event_uuid	str	UUID assigned to generated events.	'sc:inventory'
value_column	str	Column containing numeric inventory levels.	'value_double'
time_column	str	Name of timestamp column.	'systime'

detect_low_stock

detect_low_stock(
    min_level: float,
    hold: str = "0s",
    *,
    interval_end: str = "next_change"
) -> pd.DataFrame

Flag intervals where inventory stays below min_level for at least hold.

Parameters:

Name	Type	Description	Default
min_level	float	Threshold below which stock is considered low.	required
hold	str	Minimum duration the level must stay below threshold (e.g. '0s', '5min', '1h').	'0s'
interval_end	str	"next_change" (default) ends an interval at the next sample (the transition), so the interval spans the time the condition held and change-encoded signals -- one row per change -- keep their duration. "last_sample" ends it at its last flagged sample. See :func:ts_shape.utils.intervals.interval_end_times.	'next_change'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, source_uuid, is_delta,
DataFrame	min_value, avg_value, duration_seconds.

consumption_rate

consumption_rate(
    window: str = "1h", *, handle_refills: bool = True
) -> pd.DataFrame

Calculate rolling consumption rate from inventory level decreases.

The rate is expressed as units consumed per hour within each window.

Parameters:

Name	Type	Description	Default
window	str	Time-based window for grouping (e.g. '1h', '30min').	'1h'
handle_refills	bool	When True (default) only level decreases are summed (a refill is treated like a counter reset), booked in the window of the reading that reports them. When False consumption is first - last level of the window, so a refill inside the window cancels out the consumption (100 -> 40 -> 100 -> 40 reads as 0).	True

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, duration_seconds, uuid,
DataFrame	source_uuid, is_delta, consumption_rate, level_start, level_end.
DataFrame	end is start plus window.

reorder_point_breach

reorder_point_breach(
    reorder_level: float, safety_stock: float = 0.0
) -> pd.DataFrame

Detect when inventory falls below reorder point or safety stock level.

Parameters:

Name	Type	Description	Default
reorder_level	float	The reorder point threshold.	required
safety_stock	float	Safety stock threshold (must be <= reorder_level).	0.0

Returns:

Type	Description
DataFrame	DataFrame with columns: systime, uuid, source_uuid, is_delta,
DataFrame	current_level,
DataFrame	breach_type ('reorder' or 'safety_stock'), deficit.

stockout_prediction

stockout_prediction(
    consumption_rate_window: str = "4h",
    *,
    handle_refills: bool = True
) -> pd.DataFrame

Estimate time until stockout based on recent consumption rate.

For each data point, uses the consumption rate calculated over the preceding consumption_rate_window to project when inventory will reach zero.

Parameters:

Name	Type	Description	Default
consumption_rate_window	str	Lookback window for calculating consumption rate (e.g. '4h').	'4h'
handle_refills	bool	When True (default) the consumption in the lookback is the sum of the level decreases between consecutive samples (the same refill-aware rule as :meth:consumption_rate), so a refill inside the window does not cancel the consumption around it. When False it is the level at the window's first sample minus the level at its last (a refill then hides consumption, often giving 0).	True

Returns:

Name	Type	Description
	DataFrame	DataFrame with columns: systime, uuid, source_uuid, is_delta,
	DataFrame	current_level,
	DataFrame	consumption_rate (units per hour), estimated_stockout_time_hours.
	DataFrame	estimated_stockout_time_hours is NaN where the level is not
falling	no consumption in the window	no stockout is
	DataFrame	projected.