Forecast Path

forecast_path analyses the causal structure of a time series to identify two structural states:

Initiation: Signals the emergence of a new causal trajectory, showing the start of a new causal chain.
Persistence: Validates the continuation of an established trajectory, indicating the current causal chain is still evolving.

Function Parameters

Parameter	Type	Default	Required	Description
`timeframe_dependent`	`bool`	`False`	`False`	Determines the indexing method. If `True`, a datetime column is expected. If `False`, a sequential step-based index is required.
`time_series_type`	`string`	`None`	`True`	Time series data type, e.g. ‘ohlc’, ‘univariate’, or ‘rmsf’.
`data_input`	`object`	`None`	`True`	The financial time series data to be analysed. Can be a file path (CSV, Parquet, etc.) or a pandas DataFrame.
`reasoning_mode`	`string`	`None`	`True`	The strategy used for decisions: ‘proactive’ acts early; ‘reactive’ waits for sufficient evidence.
`interval`	`int`	`None`	`False`	The frequency of the time series data. Use in conjunction with `interval_unit`.
`interval_unit`	`string`	`None`	`False`	The unit of time for the interval (e.g. ‘seconds’, ‘minutes’, ‘days’).
`rmsf_stability`	`int`	`None`	`False`	The maximum cumulative or averaged stability index permitted for the system.
`rolling_path`	`bool`	`False`	`False`	Generates a rolling path forecast across input based on `rolling_path_window_size`.
`rolling_path_window_size`	`int`	`5001`	`False`	Window size of rolling window, e.g. 5001 data periods.
`rolling_path_file_output`	`string`	`None`	`False`	The base name for the output file (e.g. ‘saved_output’ creates ‘saved_output.csv’).

Configuration Options

A. Time Series Type

Option	Description
`ohlc`	A series of multivariate data points recorded over time containing open, high, low, close values e.g. financial time series.
`univariate`	A series of data points recorded over time for a single variable e.g. temperature time series.
`rmsf`	A series of Root Mean Square Fluctuation values points recorded over time commonly used in molecular modelling e.g. protein trajectories.

Timeframe Dependency

Option	Description
`True`	Anchors the state-space reconstruction to specific temporal units. The manifold is mapped against linear time.
`False`	Treats data as an ordered sequence of morphisms. The CIL maps the system’s state-space based on event-flow rather than clock-intervals.

Interpreting Function Response

The function returns a dictionary containing the target timestamp/index and the detected causal state: {"target_anchor": signal}.

Response	Type	Description
`1`	`int`	Positive causal chain detected.
`0`	`int`	No chain detected, indicates a multi-frequency overlap where opposing directional changes are occurring simultaneously on different timescales.
`-1`	`int`	Negative causal chain detected.

Python Examples

A. Timeframe Dependent (Temporal Mapping)

Use this configuration to map the system’s state-space to specific clock-intervals (milliseconds, seconds, minutes, days).

OHLC Time Series

The forecast_path function requires a specific data length to establish causal context. To forecast the next state, you must append a final “placeholder” row (in this example: 2025-08-19 17:00:00).

datetime	open	high	low	close
2025-01-23 09:00:00	100.20	110.50	90.10	95.30
2025-01-23 10:00:00	95.30	98.10	86.40	88.20
[… 4,998 rows]	…	…	…	…
2025-08-19 17:00:00	0	0	0	0

N=5001 Requirement: The algorithm utilises 5,000 preceding periods to reconstruct the system’s state-space. You must include a 5001st row that acts as a ‘placeholder’.

import sumtyme

# Initialise the client
client = sumtyme.client(apikey='your-api-key-here')

# Execute the forecast
# The CIL distinguishes between the initiation of a new chain and the persistence of an existing one.
forecast = client.forecast_path(
    time_series_type = 'ohlc',
    data_input='data/ohlc_price_5001.csv', 
    interval = 1,
    interval_unit = 'minutes',
    reasoning_mode='reactive',
    timeframe_dependent=True
)

print(forecast)
# Output: {"2025-08-19 17:00:00": -1}

Univariate Time Series

datetime	value
2025-01-23 09:00:00	100
2025-01-23 10:00:00	95
[… 4,998 rows]	…
2025-08-19 17:00:00	0

N=5001 Requirement: The algorithm utilises 5,000 preceding periods to reconstruct the system’s state-space. You must include a 5001st row that acts as a ‘placeholder’.

import sumtyme

# Initialise the client
client = sumtyme.client(apikey='your-api-key-here')

# Execute the forecast
# The CIL distinguishes between the initiation of a new chain and the persistence of an existing one.
forecast = client.forecast_path(
    time_series_type = 'univariate',
    data_input='data/univariate_5001.csv', 
    interval = 1,
    interval_unit = 'seconds',
    reasoning_mode='reactive',
    timeframe_dependent=True
)

print(forecast)
# Output: {"2025-08-19 17:00:00": -1}

B. Timeframe Independent (Event-Flow Mapping)

Use this configuration to map the system’s state-space based on sequential event-flow rather than linear time.

OHLC Time Series

The forecast_path function requires a specific data length to establish causal context. To forecast the next state, you must append a final “placeholder” row (in this example: 5001).

step	open	high	low	close
1	100	110	90	95
2	95	98	86	88
[… 4,998 rows]	…	…	…	…
5001	0	0	0	0

N=5001 Requirement: The algorithm utilises 5,000 preceding periods to reconstruct the system’s state-space. You must include a 5001st row that acts as a ‘placeholder’.

import sumtyme

# Initialise the client
client = sumtyme.client(apikey='your-api-key-here')

# Execute the forecast
# The CIL distinguishes between the initiation of a new chain and the persistence of an existing one.
forecast = client.forecast_path(
    time_series_type = 'ohlc',
    data_input='data/ohlc_price_5001.csv', 
    reasoning_mode='reactive',
    timeframe_dependent=False
)

print(forecast)
# Output: {"5001": -1}

Univariate Time Series

The forecast_path function requires a specific data length to establish causal context. To forecast the next state, you must append a final “placeholder” row (in this example: 5001).

step	value
1	100
2	95
[… 4,998 rows]	…
5001	0

N=5001 Requirement: The algorithm utilises 5,000 preceding periods to reconstruct the system’s state-space. You must include a 5001st row that acts as a ‘placeholder’.

import sumtyme

# Initialise the client
client = sumtyme.client(apikey='your-api-key-here')

# Execute the forecast
# The CIL distinguishes between the initiation of a new chain and the persistence of an existing one.
forecast = client.forecast_path(
    time_series_type = 'univariate',
    data_input='data/univariate_5001.csv', 
    interval = 1,
    interval_unit = 'seconds',
    reasoning_mode='reactive',
    timeframe_dependent=False
)

print(forecast)
# Output: {"5001": -1}

RMSF Time Series

The forecast_path function requires a specific data length to establish causal context. To forecast the next state, you must append a final “placeholder” row (in this example: 5001).

step	rmsf
1	100
2	95
[… 4,998 rows]	…
5001	0

N=5001 Requirement: The algorithm utilises 5,000 preceding periods to reconstruct the system’s state-space. You must include a 5001st row that acts as a ‘placeholder’.

import sumtyme

# Initialise the client
client = sumtyme.client(apikey='your-api-key-here')

# Execute the forecast
# The CIL distinguishes between the initiation of a new chain and the persistence of an existing one.
forecast = client.forecast_path(
    time_series_type = 'univariate',
    data_input='data/univariate_5001.csv', 
    interval = 1,
    interval_unit = 'seconds',
    reasoning_mode='reactive',
    timeframe_dependent=False
)

print(forecast)
# Output: {"5001": -1}

C. Automated Rolling Forecast

Rolling Forecast

import sumtyme

# Initialise the sumtyme client with the provided API key from your dashboard
client = sumtyme.client(apikey='your-api-key-here')

# Execute a rolling forecast across an entire dataset
# The function automatically manages the FIFO window to map the system's evolution
client.forecast_path(
    time_series_type='ohlc',
    data_input='folder/full_data.csv',        # Supports file paths or pandas DataFrames
    reasoning_mode='reactive',
    rolling_path=True,                        # Enables iterative processing across the dataset
    rolling_path_window_size=5001,            # Defines the causal context window (N=5001)
    rolling_path_file_output='rolling_path'   # Saves results to 'rolling_path.csv'
)

"""
Automatically saves each time step's rolling path forecast, appending the results to a single .csv file (e.g. './rolling_api_outputs.csv').
"""

Getting Started

Quickstart Guides

Forecast

Analysis

Updates

Function Parameters

Configuration Options

Interpreting Function Response

Python Examples

​Function Parameters

​Configuration Options

​Interpreting Function Response

​Python Examples

Function Parameters

Configuration Options

Interpreting Function Response

Python Examples