> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/sdk-getting-started/sdk-api-reference/results.md). # Results The result objects twin operations hand back. ## SampleDraws Raw joint posterior draws from twin.sample(), columnar on the wire. | Attribute | Type | Description | | --------- | ------ | ------------------------------------ | | `n` | `int` | Draws per sampling unit. | | `raw` | `dict` | The payload as it came off the wire. | ### Properties * **environments** (`list[str]`) ### SampleDraws.to\_frame ```python SampleDraws.to_frame() -> pd.DataFrame ``` *Undocumented; the signature above is the contract.* ## SimulationResult A completed simulation run: raw outputs plus best-effort tabular and narrative views. | Attribute | Type | Description | | ---------- | -------------- | ------------------------------------------------ | | `run_id` | `str` | The run this result came from. | | `run` | `dict` | The run document: status, timings, and the rest. | | `scenario` | `dict \| None` | The scenario that ran. | ### Properties * **results** (`Any`) * **environment\_groups** (`list[dict[str, Any]]`): The saved environment groups this run was scoped to, as the platform froze them. * **summary** (`str`) * **tables** (`list[str]`) ### SimulationResult.to\_frame ```python SimulationResult.to_frame(path: str | None = None) -> pd.DataFrame ``` Tabularize the result payload. Simulation families answer with different shapes, so this finds record lists in the payload. | Parameter | Type | Default | Description | | --------- | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `path` | `str \| None` | `None` | Which candidate table to use, as a dotted path. With several candidates and no path, the largest wins; the error message from a bad path lists what exists. | **Returns** (`pd.DataFrame`): The chosen records as a DataFrame. **Raises** * `InvalidArgumentError`: No tabular records in the payload, or no records at `path`. ### SimulationResult.link ```python SimulationResult.link() -> Any ``` This run's detail view on the platform, as a clickable URL. Opens the parent twin's Simulate tab on exactly this run. ### SimulationResult.export ```python SimulationResult.export(fmt: str = 'csv') -> bytes ``` The platform's own export of the run. `json` works for any completed run; `csv` is only available for a completed `forecast`, `panel_forecast` or `prediction` run against a multi-environment (panel) model, so check the run's `exportFormats` before asking for it. | Parameter | Type | Default | Description | | --------- | ----- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fmt` | `str` | `'csv'` | Export format: `json` or `csv`. `json` works for any completed run; `csv` only for a completed forecast, panel forecast or prediction run on a panel model, so `export()` raises on anything else unless you pass `'json'`. | **Returns** (`bytes`): The export's raw bytes. ### SimulationResult.sweep ```python SimulationResult.sweep(metric: str | None = None) -> SweepResult ``` Full dose-response curve of a range intervention, one metric at a time. | Parameter | Type | Default | Description | | --------- | ------------- | ------- | -------------------------------------------------------------------------------------------- | | `metric` | `str \| None` | `None` | Which metric's curve to return. Required when the run carries several; the error names them. | **Returns** (`SweepResult`): The curve as a [`SweepResult`](#sweepresult): displayed in a notebook it renders the interactive curve, `to_frame()` is the points, and DataFrame attributes pass through. ## SweepResult One metric's dose-response curve off a sweep run. Displayed in a notebook it mounts the interactive curve; everywhere else it behaves like its DataFrame — `to_frame()` returns the points, and unknown attributes (`head`, `plot`, …) delegate to it. | Attribute | Type | Description | | --------- | ----- | ------------------------------- | | `metric` | `str` | The metric this curve measures. | ### Properties * **swept\_variable** (`str | None`) ### SweepResult.to\_frame ```python SweepResult.to_frame() -> pd.DataFrame ``` *Undocumented; the signature above is the contract.* ## ForecastResult Forecast run with a tidy long-format frame: environment, series, timestamp, values. Everything on [`SimulationResult`](#simulationresult) applies; `to_frame()` additionally carries an `environment` column on panel runs and a `variable` column when several targets were forecast, so no series is ever dropped. ### ForecastResult.to\_frame ```python ForecastResult.to_frame(path: str | None = None) -> pd.DataFrame ``` *Undocumented; the signature above is the contract.* ## PredictionResult Prediction run: one row per input record, per target. Everything on [`SimulationResult`](#simulationresult) applies. `to_frame()` adds a `row` column carrying the 0-based position of the input record each prediction answers for, so predictions join back onto the frame they were asked about; a `variable` column names the target when several were predicted, and an `environment` column the environment on a panel twin. ### PredictionResult.to\_frame ```python PredictionResult.to_frame(path: str | None = None) -> pd.DataFrame ``` *Undocumented; the signature above is the contract.* ## UpdateResult Outcome of an incremental model update (assimilation). | Attribute | Type | Description | | ------------------ | ------------- | --------------------------------------------------- | | `status` | `str` | `committed`, `up_to_date`, or `retrain_required`. | | `rows_assimilated` | `int \| None` | Rows folded into the model, when any. | | `reasons` | `list[str]` | Why assimilation was not possible, when it was not. | | `job` | `dict` | The underlying job document. | ### Properties * **retrain\_required** (`bool`) ## ScoreResult Verdicts and per-row counterfactual changes from a batch scoring run. | Attribute | Type | Description | | --------- | ----- | ------------------------------ | | `run_id` | `str` | The simulation run underneath. | ### Properties * **digest** (`dict[str, Any]`): Verdict counts, top drivers, and the first row summaries. ### ScoreResult.to\_frame ```python ScoreResult.to_frame(max_rows: int | None = None) -> pd.DataFrame ``` Every scored row with its full change list, paged transparently. | Parameter | Type | Default | Description | | ---------- | ------------- | ------- | ----------------------------------------------------------- | | `max_rows` | `int \| None` | `None` | Stop after this many rows. Fetches everything when omitted. | **Returns** (`pd.DataFrame`): One row per scored input, with its change list. ### ScoreResult.link ```python ScoreResult.link() -> Any ``` This scoring run's detail view on the platform, as a clickable URL.