onsight-trend 0.1.0

Time-series trend analysis for any parameter (pressure, rate, temperature, etc.)

onsight_trend

Time-series trend analysis for the oil & gas industry—and beyond.

Analyze pressure, rate, temperature, or any parameter with rolling segmentation, dual-method voting (subtraction + linear regression), and configurable magnitude categories. Built for well performance, process monitoring, and industrial analytics.

Installation

pip install onsight-trend

Quick Start

from onsight_trend import analyze_trend

import pandas as pd
df = pd.read_csv("data.csv")
result = analyze_trend(df)

print(result.direction)    # 'increase', 'decrease', or 'steady'
print(result.magnitude)    # net change in parameter units
print(result.confidence)   # 0-100%

Input Formats

DataFrame with columns:

• Time: datetime, time, date, or timestamp
• Parameter: value, parameter, thp, pressure, rate, oil_rate, temperature, flow_rate, etc.—or any numeric column

Series with DatetimeIndex:

series = df.set_index("datetime")["pressure"]
result = analyze_trend(series)

Parameters

analyze_trend(
    data,
    duration_days=7.0,           # analysis window (most recent data)
    magnitude_categories=None,   # custom thresholds (see below)
)

Custom Magnitude Categories

Magnitude categories classify the size of change in your parameter’s units (e.g. psi, bar, stb/d, °C).

Default Categories

Category	Range (units)
negligible	0 - 10
small	10 - 50
moderate	50 - 150
large	150 - 300
very_large	300+

How to Change Magnitude Categories

1. Python API—pass a dict

my_categories = {
    "negligible": (0, 15),
    "small": (15, 60),
    "moderate": (60, 200),
    "large": (200, 400),
    "very_large": (400, float("inf")),
}
result = analyze_trend(df, magnitude_categories=my_categories)
print(result.magnitude_category)  # uses your categories

2. Modify defaults and reuse

from onsight_trend import analyze_trend
from onsight_trend.config import DEFAULT_MAGNITUDE_CATEGORIES

# Copy and adjust
my_cats = DEFAULT_MAGNITUDE_CATEGORIES.copy()
my_cats["small"] = (10, 75)
my_cats["moderate"] = (75, 200)

result = analyze_trend(df, magnitude_categories=my_cats)

3. Different units (e.g. oil rate in stb/d)

# For oil rate: 0-100 stb/d = low, 100-500 = medium, 500+ = high
rate_categories = {
    "low": (0, 100),
    "medium": (100, 500),
    "high": (500, float("inf")),
}
result = analyze_trend(rate_df, magnitude_categories=rate_categories)

4. CLI

python -m onsight_trend data.csv -d 7 -m "low:0,25 medium:25,100 high:100,inf"

Format: "name1:min1,max1 name2:min2,max2 ...". Use inf for no upper limit.

Category Rules

• Categories are checked in order; the first matching range is used.
• Ranges are [min, max) (inclusive min, exclusive max).
• Use float("inf") for unbounded upper limits.

Result Attributes

Attribute	Type	Description
direction	str	'increase', 'decrease', 'steady'
magnitude	float	Net change in parameter units
confidence	float	Vote confidence 0-100%
magnitude_pct	float	Percentage change
magnitude_category	str	Category from your thresholds
start_value	float	Parameter at start of window
end_value	float	Parameter at end of window
duration_days	float	Analysis window length
n_segments	int	Number of rolling segments (10)

How It Works

1. Rolling segments: Splits the duration into 10 overlapping segments (60% overlap).
2. Two methods per segment: Simple subtraction and linear regression.
3. Voting: Each segment contributes 2 votes; majority direction wins.
4. Confidence: Percentage of votes for the winning direction.
5. Magnitude: Net change from first to last point in the window.

License

MIT