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

# Create a study with scenarios

> Write scenarios that change a book, such as a higher collision deductible, and hold each version of the book in one study.

A study holds versions of one book: the book as reported, and one version per scenario. Write a
scenario as a function from a book to a changed book, marked with `@scenario`:

```python theme={null}
from relativities import Program, Study, scenario

program = Program.load("effective://example-ca-ppa")
book = program.example_book


@scenario("Collision deductible {deductible}")
def collision_deductible(book, deductible=1_000):
    """Raise each collision deductible below `deductible` to `deductible`."""

    def raised(coverages):
        lower = coverages["coverage_id"].eq("collision") & coverages["deductible"].lt(deductible)
        return coverages.assign(deductible=coverages["deductible"].mask(lower, deductible))

    return book.with_tables(coverages=raised)


study = Study(book, scenarios=[collision_deductible, collision_deductible(deductible=2_000)])
study.scenarios  # ('baseline', 'Collision deductible 1000', 'Collision deductible 2000')
```

The label names each scenario in the results, with its parameters filled in. `baseline` is the book
as reported.

```mermaid theme={null}
flowchart LR
  book["Book"] --> baseline["baseline"]
  book --> s1["Collision deductible 1000"]
  book --> s2["Collision deductible 2000"]
  baseline --> rate["rate: one row per submission and scenario"]
  s1 --> rate
  s2 --> rate
```

## Set a scenario's parameters

Call a scenario with parameters to make a new scenario, such as `collision_deductible(deductible=2_000)`.
A scenario's function takes the book first, then keyword parameters with defaults.

* A scenario changes rows inside each submission, such as a deductible or an added driver.
* A scenario keeps every submission, in order. The study checks each version as it builds it.

## Read one version of the book

A study builds each version when you ask for it:

```python theme={null}
changed = study.book("Collision deductible 1000")
changed.coverages.query("coverage_id == 'collision'")["deductible"].value_counts().sort_index()
# deductible
# 1000    137122
# 2000      4815
```

## Fill unknown facts in draws

The example book leaves 4,668 annual mileages blank. To test how much a result depends on blank facts, add draws. A draw fills each blank of the columns
you name, and keeps each reported value:

```python theme={null}
from relativities import fill

sampled = Study(book, scenarios=[collision_deductible], fill={"vehicles.annual_mileage": fill.like("garaging_postal_code")}, draws=10, seed=7)
sampled.scenarios, sampled.draws  # (('baseline', 'Collision deductible 1000'), 10)
```

Draw 0 is each scenario as reported, and draws 1 to 10 fill the blanks. `fill.like` borrows each
blank value from a random vehicle with the same postal code. Each filled column gets a `_source`
column, `reported` or `modeled`.

[Books and studies](/relativities/explanation/books-and-studies) describes scenarios, draws and their seeds.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.