API reference

Warning

This is the API of the compiler lineage, released as v0.2.0b1 and still beta. The 0.1 oscillation and accumulation interfaces are preserved at v0.1.0a1 and v0.1.0b1 and are not part of it.

Development Transition

class featuregraph.behaviors.transition.Transition(df, signal, direction, op, group=None, diff_lag=1, eps=0.0)

Bases: object

summary()

Shape measures

Measures over compiled occurrences that need no knowledge of the signal.

Everything here reads the observations featuregraph.compile_states() returns and asks about shape alone: how long runs last, how a rise compares with the fall that follows it, and whether those quantities change across a record. None of it knows what the column was, and none of it needs to.

Positions are row positions within a group, so a measure can say where in a record something happened without knowing the time base.

featuregraph.shape.occurrence_drift(observations, *, group_by=None, measure='sample_count')

Whether a per-occurrence measure changes across a record.

For each group and state, fits a least-squares line of measure against where the occurrence starts, with position normalised to [0, 1] over the group. slope is therefore the fitted change in the measure from the start of the record to its end, in the measure’s own units. first_half_median and second_half_median split the occurrences by position for a reading that does not depend on the fit. Fewer than two occurrences give no slope.

Parameters:
Return type:

DataFrame

featuregraph.shape.occurrences(observations, *, group_by=None)

One row per occurrence: its state, where it starts and ends, how long it is.

start_position and end_position count rows within the group, so an occurrence in a record compiled under missing_policy: "exclude" still sits where it sat in the record. sample_count counts only the rows the occurrence actually holds. Rows outside the partition, where state_valid is False, belong to no occurrence.

Parameters:
Return type:

DataFrame

featuregraph.shape.rise_fall_asymmetry(observations, *, rising='rising', falling='falling', group_by=None)

How each rise compares with the fall that immediately follows it.

One row per rising occurrence. When the next occurrence in the group is falling, asymmetry is the rising share of the pair, rising_samples / (rising_samples + falling_samples): 0.5 is symmetric, above 0.5 is a slow rise and a fast fall, below is the reverse. When the next occurrence is anything else, or there is none, the row stays with paired set to False and no asymmetry, so an unpaired rise is reported rather than dropped.

Parameters:
Return type:

DataFrame

Example datasets

FeatureGraph example datasets.

featuregraph.datasets.bidmc(subject=1, *, refresh=False)

Load one BIDMC subject.

Returns:

Physiological waveform observations with standardized FeatureGraph column names.

Return type:

pandas.DataFrame

Parameters:
featuregraph.datasets.eastman(*, dataset='faulty_training', fault_number=1, simulation_run=1, refresh=False)

Load one Tennessee Eastman simulation run.

Returns:

Industrial process observations with standardized FeatureGraph column names.

Return type:

pandas.DataFrame

Parameters:
  • dataset (str)

  • fault_number (int)

  • simulation_run (int)

  • refresh (bool)

featuregraph.datasets.pulse(segments=None, *, initial_value=1.0, sample_interval=1.0, start_time=0.0, signal_name='signal')

Generate a deterministic piecewise-linear pulse signal.

Each segment is a mapping with three required fields:

state

One of "rising", "falling", or "stable".

target

The value reached at the final sample of the segment. Stable segments must target the current value.

duration

The number of samples generated for the segment.

Moving segments exclude their initial boundary value and include their target value. This prevents duplicate samples where adjacent segments meet while preserving exact, deterministic boundaries.

Parameters:
  • segments (Iterable[Mapping[str, float | int | str]] | None) – Ordered segment specifications. When omitted, a neutral step-and-hold example containing rising, falling, and stable episodes is generated.

  • initial_value (float) – Signal value immediately before the first generated sample.

  • sample_interval (float) – Time between consecutive samples. Must be positive.

  • start_time (float) – Time assigned to the first generated sample.

  • signal_name (str) – Name of the generated signal column.

Returns:

Columns are sample, time, the requested signal column, true_state, and true_segment_id.

Return type:

pandas.DataFrame

featuregraph.datasets.tank_fill(phases=None, *, initial_volume=10.0, sample_interval=1.0, start_time=0.0, capacity=None)

Generate a deterministic tank-filling time series.

Each phase is a mapping with three required fields:

state

Either "filling" or "stable".

flow_rate

Water added per unit time. Filling phases require a positive value; stable phases require zero.

duration

Number of generated samples in the phase.

Volume is updated once per sample according to volume[t] = volume[t - 1] + flow_rate * sample_interval.

Parameters:
  • phases (Iterable[Mapping[str, float | int | str]] | None) – Ordered phase specifications. When omitted, a sequence of filling periods at different rates separated by stable periods is generated.

  • initial_volume (float) – Volume immediately before the first generated sample.

  • sample_interval (float) – Time between consecutive samples. Must be positive.

  • start_time (float) – Time assigned to the first generated sample.

  • capacity (float | None) – Optional maximum tank volume. Generation fails if a phase would exceed this value.

Returns:

Columns are sample, time, volume, flow_rate, true_state, and true_segment_id.

Return type:

pandas.DataFrame

For the immutable alpha source and API behavior, use the v0.1.0a1 tag.