> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sumtyme.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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)**

<Note>Use this configuration to map the system's state-space to specific clock-intervals (milliseconds, seconds, minutes, days). </Note>

<AccordionGroup>
  <Accordion title="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** |

    <Note>
      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'.
    </Note>

    ```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}
    ```
  </Accordion>

  <Accordion title="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: 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** |

    <Note>
      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'.
    </Note>

    ```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}
    ```
  </Accordion>
</AccordionGroup>

**B. Timeframe Independent (Event-Flow Mapping)**

<Note>Use this configuration to map the system's state-space based on sequential event-flow rather than linear time.</Note>

<AccordionGroup>
  <Accordion title="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** |

    <Note>
      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'.
    </Note>

    ```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}
    ```
  </Accordion>

  <Accordion title="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** |

    <Note>
      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'.
    </Note>

    ```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}
    ```
  </Accordion>

  <Accordion title="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** |

    <Note>
      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'.
    </Note>

    ```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}

    ```
  </Accordion>
</AccordionGroup>

**C. Automated Rolling Forecast**

<Accordion title="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').
  """
  ```
</Accordion>