> For the complete documentation index, see [llms.txt](https://quandora.gitbook.io/quandora-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quandora.gitbook.io/quandora-docs/understanding-quandora/factor-card.md).

# Factor Card

Every completed run returns a factor card: a structured report designed to be read by both humans and AI agents. The card is the trust artifact — it turns a raw backtest into something you can review, question, and build on.

### How To Read A Card

Read in this order:

```
verdict first
-> evidence second
-> risk / caveats third
-> next improvement fourth
```

### Card Fields

| Field           | Meaning                                                           |
| --------------- | ----------------------------------------------------------------- |
| verdict         | accepted, rejected, duplicate, needs repair, or failed evaluation |
| factor idea     | One-sentence explanation of what the factor tries to capture      |
| formula         | The human-readable version of the factor logic                    |
| data used       | Data headers, bar size, forward horizon, and evaluation windows   |
| key metrics     | Sharpe, rank IC, autocorrelation, drawdown, turnover, and more    |
| pass checks     | Each check with the threshold applied and whether it passed       |
| assumptions     | What the backtest assumes                                         |
| caveats         | Why the signal may decay or fail                                  |
| next experiment | What the agent or user should test next                           |

### A Real Example

From a real run on the microstructure task — factor: "Taker Trade Size Imbalance", daily bars, 7-day forward horizon:

| Field                   | Value                              | Plain English                                            |
| ----------------------- | ---------------------------------- | -------------------------------------------------------- |
| Verdict                 | pass                               | Cleared the cross-sectional checks                       |
| Sharpe (CS)             | 0.81 (threshold 0.8)               | Just cleared the bar — real but not spectacular          |
| Rank IC                 | 0.012 (threshold 0.01)             | Weak but genuinely positive predictive ranking           |
| Autocorrelation (lag 1) | 0.89                               | Very stable signal, not bar-to-bar noise                 |
| Max drawdown            | −32%                               | The worst peak-to-trough loss in the backtest            |
| Turnover                | 0.63                               | How much the portfolio churns — this drives trading cost |
| Cost viable             | ❌                                  | The edge does not survive realistic trading costs        |
| Validation regime       | Bear 51% / Sideways 16% / Bull 32% | Tested across mixed market conditions                    |

Reading it the card's way: **verdict** — pass, but barely. **Evidence** — weak-but-real predictive power with a very stable signal. **Caveat** — it fails cost viability, so it is not tradeable as-is. **Next experiment** — reduce turnover or slow the signal down so more of the edge survives costs.

This is exactly what a factor card is for: a "pass" that still tells you the honest, load-bearing caveat before you risk anything on it.

### Charts

Each run also saves PNG charts alongside the card:

* **Group return plot** — forward returns split by factor buckets: do high scores actually outperform low scores?
* **NAV curves** — cumulative performance curves per factor bucket over time
* **Profile panel** — factor diagnostics at a glance (IC behavior, signal distribution, decay)

### Where Files Land

When your host supports local files, each run is archived under a stable folder named after the factor:

```
Quandora result/factor-mining/<factor_slug>/
  plugin.py
  run_summary.json
  factor_card_is.json
  artifact_manifest.json
  artifacts/is/*.png
```

Ask your agent to explain any field — the card is designed to be pasted into an AI conversation for critique and next steps.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quandora.gitbook.io/quandora-docs/understanding-quandora/factor-card.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.