# Track Causal Chains
Source: https://docs.sumtyme.ai/analysis/map-causal-chains
`map_causal_chains` maps the trajectory of directional signals as they emerge at the microscale and propagate through a hierarchy of increasing timeframes. By identifying the origin of a change, it constructs causal chains to quantify how micro-scale shifts evolve into structural change across expanding time scales.
***
#### Function Parameters
| Parameter | Type | Required | Description |
| :---------- | :------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------- |
| data\_input | `list[tuple]` | True | A list of tuples containing the source (URL or local path) and the associated timeframe label e.g. ('path/to/file.csv', '1m'). |
#### Supported Time Resolutions
| Unit | Symbol | Seconds ($s$) |
| :-------------- | :----- | :--------------------- |
| **Planck Time** | `pt` | $5.39 \times 10^{-44}$ |
| **Yoctosecond** | `ys` | $10^{-24}$ |
| **Zeptosecond** | `zs` | $10^{-21}$ |
| **Attosecond** | `as` | $10^{-18}$ |
| **Femtosecond** | `fs` | $10^{-15}$ |
| **Picosecond** | `ps` | $10^{-12}$ |
| **Nanosecond** | `ns` | $10^{-9}$ |
| **Microsecond** | `us` | $10^{-6}$ |
| **Millisecond** | `ms` | $10^{-3}$ |
| **Second** | `s` | $1$ |
| **Minute** | `m` | $60$ |
| **Hour** | `h` | $3,600$ |
| **Day** | `d` | $86,400$ |
| **Week** | `w` | $604,800$ |
***
#### Python Code Example
```python theme={null}
import sumtyme
# Initialise the sumtyme client with the provided API key from your dashboard
client = sumtyme.client(apikey='your-api-key-here')
# Ensure API outputs start from the same timestamp
api_outputs = [
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_1s_reactive_outputs.csv", '1s'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_5s_reactive_outputs.csv", '5s'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_15s_reactive_outputs.csv", '15s'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_30s_reactive_outputs.csv", '30s'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_1m_reactive_outputs.csv", '1m'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_2m_reactive_outputs.csv", '2m'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_5m_reactive_outputs.csv", '5m'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_10m_reactive_outputs.csv", '10m'),
]
# Execute Causal Mapping
# initial_chain_starts (dataframe): Specific datetime where a chain first starts based on observed timeframes
# causal_chain_details (dataframe): A detailed breakdown of how the signal moved across different timeframes.
initial_chain_starts, causal_chain_details = client.map_causal_chains(api_outputs=api_outputs)
# Output results for review
print("--- Chain Inception Points ---")
print(initial_chain_starts)
print("\n--- Detailed Causal Path Analysis ---")
print(causal_chain_details)
```
# Forecast Path
Source: https://docs.sumtyme.ai/forecast/time-series
`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).
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'.
```python theme={null}
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}
```
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 | 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'.
```python theme={null}
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.
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'.
```python theme={null}
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}
```
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'.
```python theme={null}
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}
```
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'.
```python theme={null}
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**
```python theme={null}
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').
"""
```
# Get Started
Source: https://docs.sumtyme.ai/get-started
## Create an account and learn how to model with sumtyme.ai.
[Create your sumtyme account](https://www.sumtyme.ai/signup) to begin modelling complex multiscale systems, from shifting financial markets to evolving climate patterns in minutes.
Once you've got your API key, follow our [**walkthrough guide**](/quickstart/finance) to analyse your first multiscale system and learn our modelling approach.
### Why us?
* Deterministic Insights: map the specific causal trajectory of change from its point of inception rather than a probabilistic distribution.
* Zero Information Loss: track the signal's propagation through multiple time scales in real-time with no smoothing or data loss common in statistical modelling.
* Continual Learning: allow the CIL to use its understanding of how causal structures evolve to remain accurate in transition states where no historical data exists.
### Explore Our Lab
Learn the underlying theory of our Causal Intelligence Layer (CIL)
### Common CIL Use Cases
The CIL captures change at its point of inception, mapping its causal evolution across scales to provide a real-time lead on macro-shifts.
### Contact Us
Get in touch with our support team.
# CIL Quickstart
Source: https://docs.sumtyme.ai/quickstart/finance
This quickstart guide enables you to model complex multiscale systems, such as financial markets, with no reliance on training data.
The CIL models directional changes as a continuous causal chain, eliminating the need for historical training data while providing a deterministic view of system evolution.
In this guide you will learn:
* **Identification:** How to pinpoint system changes at their exact point of inception within the microscale.
* **Tracking:** How to follow an initial causal signal's evolution across multiple scales with zero information loss.
## Prerequisites
#### 1. Create a Virtual Environment
We recommend using a virtual environment to prevent dependency conflicts with other projects.
On Windows:
```bash theme={null}
python -m venv venv
venv\Scripts\activate
```
On Mac:
```bash theme={null}
python3 -m venv venv
source venv/bin/activate
```
#### 2. Install the Package
Once your environment is active, install the sumtyme python library.
```bash theme={null}
pip install sumtyme
```
The sumtyme package provides the underlying engine for detecting directional changes and analysing multiscale systems without requiring external training datasets.
#### 3. Verify Installation
You can quickly verify that the package is ready for use by checking the version in your terminal:
```bash theme={null}
python -c "import sumtyme; print(sumtyme.__version__)"
```
## Gold Price Volatility Analysis (Oct 2025)
| Metric | Description |
| ------------------ | -------------------------------------------------------- |
| Market Context | Gold reached record highs followed by an 11% correction. |
| Asset Under Review | SPDR Gold Trust (GLD) |
| Analysis Period | October 20 to October 28, 2025 |
| Peak Price | 403.30 (Recorded Oct 20, 19:59) |
| Trough Price | 357.62 (Recorded Oct 28, 09:08) |
| Maximum Drawdown | 11.32% |
### Phase 1: Pinpointing Microscale Inception
Detect the exact moment a change starts at the micro-level before it is visible in macro data.
```python theme={null}
import pandas as pd
# 1. Fetch data
gold_data = pd.read_csv('https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_1s_reactive_outputs.csv', parse_dates=['datetime'])
# 2. Date to start analysis
analysis_start_date = pd.to_datetime("2025-10-20 20:00:00")
# 3. Filter data
mask = gold_data['datetime'] >= analysis_start_date
filtered_df = gold_data.loc[mask].reset_index(drop=True)
print(f"Starting simulation for {len(filtered_df)} data points...")
# 4. Simulate the API calls
filtered_data = filtered_df.to_dict('records')
for current_tick in filtered_data:
# Extracting variables
timestamp = current_tick['datetime']
price = current_tick['open']
chain_detected = current_tick.get('chain_detected')
if chain_detected == -1:
print(f"--- Event Detected at {timestamp} ---")
print(f"Price: ${price}")
break
```
### Phase 2: Mapping Multiscale Signal Propagation
Follow the signal as it moves across scales, evolving from a minor fluctuation into a significant trend.
```python theme={null}
import sumtyme
client = sumtyme.client(apikey='xxxxxxx')
# 1. Define the data hierarchy (Granularity Scales)
# Each tuple contains the URL to a specific timeframe's CSV and its label.
# This setup allows the system to analyse how events cascade from 1-second ticks up to 10 minute timeframe.
scales = [
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_1s_reactive_outputs.csv", '1s'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_5s_reactive_outputs.csv", '5s'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_15s_reactive_outputs.csv", '15s'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_30s_reactive_outputs.csv", '30s'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_1m_reactive_outputs.csv", '1m'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_2m_reactive_outputs.csv", '2m'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_5m_reactive_outputs.csv", '5m'),
("https://raw.githubusercontent.com/sumteam/data_store/main/GLD/api_outputs/GLD_10m_reactive_outputs.csv", '10m'),
]
# 2. Execute Causal Mapping
# initial_chain_starts: Specific datetime where a chain first started.
# causal_chain_details: A detailed breakdown of how the signal moved across different timeframes.
initial_chain_starts, causal_chain_details = client.map_causal_chains(scales)
# 3. Output results for review
print("--- Chain Inception Points ---")
print(initial_chain_starts[initial_chain_starts['propagation_id'] == 'Chain_2'])
print("\n--- Detailed Causal Path Analysis ---")
print(causal_chain_details[causal_chain_details['propagation_id']=='Chain_2'])
```
### Result
The CIL framework successfully identified the structural breakdown of the Gold (GLD) market within seconds of its microscale inception, well before the trend became visible to traditional macro indicators.
| Metric | Details |
| :------------------------------ | :---------------------- |
| **Detection Status** | Negative Chain Detected |
| **Initial Detection Price** | 402.31 |
| **Detection Timestamp** | 2025-10-20 20:02:02 |
| **Price Drop Before Detection** | 0.99 (from 403.30) |
| **Time to Detection** | 2 minutes, 48 seconds |
| **Drawdown Saved** | 99.85% |
The robustness of the CIL approach is evidenced by Propagation ID: Chain\_2. The signal's ability to propagate through every timeframe confirms it was a systemic shift rather than random noise:
* **Micro-confirmation (1s – 30s)**: The signal survived the initial volatility phase, confirming a structural directional shift at the earliest possible stage.
* **Macro-realisation (1m – 10m)**: The chain remained intact across all scales, by the time it reached the 10m scale on Oct 28, the market had realised the full 11% correction.
* **Zero Information Loss**: Each scale transition maintained the original -1 (negative) directionality, validating the deterministic nature of the causal chain.
# Changelog
Source: https://docs.sumtyme.ai/updates
Product updates and announcements
### New Endpoints
* `forecast_path` analyses the causal structure of a time series to identify either the initiation of a new causal trajectory or the persistence of an existing one.
* `map_causal_chains` analyses submitted CIL outputs to map out causal chains.
### Deprecated
* `EIPClient` → Renamed to `client`.
* `ohlc_forecast`
* `univariate_forecast`