> 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/more-details/digital-twin/simulation-types/root-cause-analysis.md). # Root Cause Analysis Root Cause Analysis answers a specific question: *this value came out wrong — why?* You point it at a variable that behaved unexpectedly, give it the record you want to diagnose, and it traces **upstream** through the [Digital Twin](/more-details/digital-twin.md)'s causal graph to find what drove the anomaly. For the workflow that produces a Digital Twin in the first place, see [Step 5: Build Digital Twin](/user-guide/creating-digital-twin.md). *** ## How it works: expected vs. observed A trained Digital Twin doesn't only predict an outcome from inputs — it learns the expected relationships among *all* the variables. So for any record, it can say, for each value: *given everything else I know about this record, here is the value I'd expect, and the range it should fall in.* A **deviation** is the gap between the value you observed and the value the model expected. RootCause measures it as a **z-score** — the number of standard deviations the observation sits from expectation: * A z-score near **0** means the value is in line with what the model expected. * A **large** z-score (positive or negative) means the value is genuinely surprising — it doesn't fit what the model learned. Root Cause Analysis starts from the variable you flag as anomalous and walks the causal graph upstream, scoring the deviation of each variable along the way. The upstream variables with the largest deviations are the candidate root causes: they are the surprises that explain the surprise you started with. > **Root Cause Analysis vs. Anomaly Scan.** They answer opposite questions. **Anomaly Scan & Diagnosis** watches your data and surfaces anomalies *for* you — you don't have to know what's wrong. **Root Cause Analysis** is deliberate: you already know something is off, name it, and ask the platform to diagnose the cause. *** ## Starting a simulation Open your trained Digital Twin from the Digital Twins list.

A trained Digital Twin's Home showing the causal graph, a Model trained and ready banner, and side cards reporting 19 variables, 32 relationships, and a 72% model fit — Root Cause Analysis runs against a trained Digital Twin — the same causal model that powers every other simulation type.

Open the twin's **Simulations** row, click **New Simulation**, and choose **Root Cause Analysis** from the type picker.

The empty Root Cause Analysis setup form: Step 1 Anomalous variable with the Select variable to diagnose dropdown unset, and Step 2 Observed data with one blank record on the Field Input tab — The Root Cause Analysis setup as it opens: the anomalous variable to diagnose on top, the observed data to diagnose it against below.

*** ## Step 1: Choose the anomalous variable Select the variable showing unexpected behavior. This is the starting point — the analysis traces upstream from here through the causal graph to find likely root causes. In the example below, the anomalous variable is **MonthlyCharges**: we want to understand why customers' observed charges sit where they do relative to what the model expects. *** ## Step 2: Provide the observed data Supply the record you want to diagnose. Each row is one independent sample; you can diagnose several at once. As with Prediction, you can enter records by hand (**Field Input**), upload a CSV on **File Upload**, or pull rows from a **Dataset**. Each record carries the full customer profile — services, contract, tenure, and the observed MonthlyCharges value. The platform validates required fields before it will run.

The Root Cause Analysis setup form with MonthlyCharges as the anomalous variable and an Input Records table of customer records, one column per record, filled in on the Field Input tab — The setup filled in: MonthlyCharges as the anomalous variable, with the observed customer records to diagnose — one column per record.

*** ## Step 3: Detection settings *(optional)* These tune how sensitive the analysis is — how large a deviation has to be before a variable is flagged. * **Target false-positive rate** — the slider runs from 0.1% (strict) to 5% (loose). A lower rate flags fewer variables and reduces false positives; a higher rate flags more. The default is 0.50%. Leave the default unless you have a reason to change it. Pick the twin version to run on, review the **Configuration Summary**, and click **Run Simulation**. *** ## Running the analysis The twin runs the diagnosis — scoring the observed records against its learned expectations and tracing the causal path upstream from the anomalous variable. Even a large batch is fast: the run below scored 4,998 records in seconds.

The Root Cause Analysis run page just after completion: the per-sample deviation table is populated, with the run configuration — diagnosing root causes of anomaly in MonthlyCharges across 4,998 input samples at a 1.00% target FPR — beside it — The run page as the analysis lands. This run was configured with a 1.00% target FPR rather than the 0.50% default.

*** ## Reading the result The result opens on the **Root Cause Analysis** section. For a multi-sample run that is the per-sample table: one row per sample, each carrying the target's observed value, the expected value and its range, a severity z-score, whether the sample counts as anomalous, and (when one is found) the top root cause with its confidence. Expand a row — or run a single sample — and a **Target Diagnosis** narrative appears for it, a plain-English account of the deviation with its observable-versus-latent attribution split and a deviation chart.

A completed Root Cause Analysis: the per-sample table where every row shows a mild z-score against an expected 65.02 ± 27.75 and Anomalous: No, with an expanded row showing the Target Diagnosis narrative for MonthlyCharges and its observable-versus-latent attribution split — A completed analysis. The table shows the working for every sample: observed vs expected, severity, and the anomalous flag; expanding a row gives that sample's Target Diagnosis.

In this run, the verdict was that there was **no clear cause to find**. Every sample's diagnosis reported no identified upstream root cause for MonthlyCharges, with z-scores ranging from −1.27 to 0.20 — mild rather than strongly abnormal — fully explained by observable factors, with observable attribution at 1.0 and latent attribution at 0.0, and no causal paths found. This is the system working as intended, not failing. The deviations stayed mild: no sample's |z| reached the table's anomaly cut-off of 2.5, so every row reads **Anomalous: No**. The target false-positive rate you set in Step 3 does not decide that verdict; it calibrates the per-variable thresholds, shown on the causal flowchart, that decide which upstream variables are flagged as root causes or as propagation. Rather than manufacture a tidy explanation, the platform reported that the observed charges are consistent with what the model expects, and the Observable/Latent attribution split confirms the small deviations that do exist are carried by measured variables, not hidden ones. That restraint is the point. A Digital Twin's Root Cause Analysis is grounded in the causal model and the evidence in front of it. When the evidence supports a cause, it names it and shows the deviation that justifies it; when the evidence doesn't, it says so. The answer is always defensible, because it never fakes one. *** ## Outside the UI This simulation runs from the Python SDK and from the REST API, with the same configuration the wizard collects. ```python >>> twin.root_cause("Churn", observed) ``` Over REST it is a scenario on `POST /api/v1/workspaces/{workspaceId}/simulations` with `"type": "root_cause_analysis"`, with a different spelling per twin kind. The observations to diagnose are required: this analysis reads rows you supply, not the training data. See [Working with Digital Twins](/api-and-integrations/sdk-getting-started/sdk-working-with-twins.md) for the SDK, and [Running Simulations over REST](/api-and-integrations/rest-running-simulations.md) for the request body. *** ## Other Simulation Types * [Prediction](/more-details/digital-twin/simulation-types/prediction.md) — the most likely outcome for a specific input. * [Intervention](/more-details/digital-twin/simulation-types/intervention.md) — change a single variable and observe propagation. * [Optimization](/more-details/digital-twin/simulation-types/optimization.md) — find the input combination that best meets a goal. * [Best Action](/more-details/digital-twin/simulation-types/best-action.md) — the minimum change needed to reach a target outcome. * [Explanation](/more-details/digital-twin/simulation-types/explanation.md) — the drivers and impacts behind an outcome. * [Anomaly Scan & Diagnosis](/more-details/digital-twin/simulation-types/anomaly-scan.md) — scan every variable for anomalies and diagnose each one. See [Simulation Types](/more-details/digital-twin/simulation-types.md) for the full picture and [Step 6: Run Simulations](/user-guide/simulations.md) for the general overview.