> ## 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.

# Rate a book with a program

> Rate every submission in a book with one program, count the unrated submissions by reason, and explain one premium step by step.

Rate the example book with the example program:

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

program = Program.load("effective://example-ca-ppa")
book = program.example_book
results = program.rate(book)
results[["submission_id", "status", "reason_code", "premium"]].head(3)
#   submission_id     status reason_code premium
# 0       S000001  succeeded        None    2636
# 1       S000002  succeeded        None    5339
# 2       S000003  succeeded        None    2341
```

`rate` returns one row per submission, in book order. `premium` is the policy's annual premium,
as an exact `Decimal`. Rating runs on your machine, and your book stays there.

## Count the unrated submissions

Each submission keeps its row. An unrated submission has a `status` other than `succeeded`, a
reason, and `NaN` as its premium:

```python theme={null}
results.groupby(["status", "reason_code"], dropna=False).size()
# status          reason_code
# invalid_inputs  INPUT-TYPE       394
# refused         CSL             1056
#                 FR-FILING       1258
#                 RIDESHARE        621
# succeeded       NaN            96671
```

| Status | Meaning |
| - | - |
| `succeeded` | The rater calculated each outcome |
| `refused` | The carrier declines the risk; `reason_code` is the carrier's code |
| `invalid_inputs` | An input breaks `program.rater.inputs`; `reason` names the field |
| `rating_failed` | The rater failed on this submission |

Keep the unrated submissions and their reasons in each exhibit. [Results](/relativities/reference/results) describes each column.

## Summarize by your own segments

Join the results to the book by `submission_id`, and summarize in pandas:

```python theme={null}
rated = results.merge(book.submissions[["submission_id", "policy_id"]]).merge(book.policies)
rated.groupby("region")["premium"].agg(["count", "mean"]).astype(float).round(0)
#                   count    mean
# region
# bay_area        18722.0  3036.0
# central_coast    3908.0  2397.0
# central_valley  11700.0  2612.0
# inland_empire   11645.0  3532.0
# los_angeles     33043.0  4012.0
# north_coast      2442.0  1801.0
# sacramento       6767.0  2801.0
# san_diego        8444.0  2785.0
```

`mean` skips the `NaN` premiums, so each mean describes the rated policies of its region.

## Rate by vehicle

Pass `by="vehicles"` for one row per vehicle, with the premiums the rater returns for that vehicle:

```python theme={null}
vehicles = program.rate(book, by="vehicles")
vehicles[["submission_id", "vehicle_id", "coverage_premium.collision"]].head(3)
#   submission_id vehicle_id coverage_premium.collision
# 0       S000001         V1                        562
# 1       S000001         V2                        611
# 2       S000002         V1                       1382
```

## Explain a premium

`explain` lists each input the rater received, then each value it calculated, in order:

```python theme={null}
explained = program.explain(book, "S000001")
explained.query("kind == 'input'")[["name", "value"]].head(5)
#                         name     value
# 0               multi_policy      True
# 1              years_with_us         2
# 2          drivers[0].number         1
# 3  drivers[0].years_licensed        52
# 4  drivers[0].marital_status  divorced
explained.query("kind == 'calculation'")[["name", "value"]].tail(3)
#                     name value
# 208  vehicles[0].premium  1265
# 209  vehicles[1].premium  1371
# 210              premium  2636
```

Each row carries `submission_id`, so the table merges with the book and with the rows of `rate`.
The calculation rows show each factor and premium to the total of \$2,636.


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