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

# Relativities

> Compare carrier premiums on the same risks, explain pricing differences, and test proposed rate changes with Python and pandas.

Relativities is Effective's Python library for comparative rating.
Run the same risks through your rating program and competing programs, then analyze the premiums in pandas.
Use the results to investigate competitive position, explain pricing gaps, and assess proposed changes by segment.

Start with a market basket or a book of business represented in pandas tables.
Each program maps those shared facts to its carrier's inputs and calculates premiums locally through the `rslc` engine.
Results retain submission IDs, rating statuses, and each rater's outcomes for analysis in your own notebook.

## Start with a pricing question

| Question | Workflow |
| - | - |
| Where does our program cost more or less than the competition? | [Compare carriers](/relativities/how-to/compare-carriers), then summarize by your own segments |
| Which rating rules explain a gap? | [Explain a premium](/relativities/how-to/explain-a-premium) and compare inputs, factors, and coverage premiums |
| How does a proposed change affect our competitive position? | [Measure a rate change](/relativities/how-to/measure-a-rate-change) against the current program and a competitor |
| How sensitive is the result to a deductible or mileage assumption? | [Price a deductible change](/relativities/how-to/price-a-deductible-change) or [find a mileage tipping point](/relativities/how-to/find-a-mileage-tipping-point) |
| Does the conclusion depend on missing facts? | [Fill unknown facts](/relativities/how-to/fill-unknown-facts) and report the assumptions and rating success counts |

The examples use personal auto. The data model lets you retain your own columns, tables, and analysis dimensions.

## Rate one risk

[Install Relativities and download the example data](/relativities/setup) before running this page.

```python theme={null}
from pathlib import Path

from relativities import Rater

with Rater.load(Path("relativities-examples/example-auto.zip")) as rater:
    result = rater.rate(
        {
            "drivers": [{"age": 42}],
            "vehicles": [{"annual_mileage": 5000}],
            "coverages": {"collision": False},
        }
    )
result.to_pandas()[["id", "status", "annual_premium"]]
#    id     status  annual_premium
# 0   0  succeeded           400.0
```

For a reusable comparison, [rate your first book](/relativities/tutorial/rate-your-first-book), then [compare carriers](/relativities/how-to/compare-carriers) on a common basis.

## How the pieces fit

| Noun | What it is |
| - | - |
| [`Rater`](/relativities/reference/relativities#rater) | A rating algorithm compiled from RSL, with its own inputs and outcomes |
| [`Program`](/relativities/reference/relativities#program) | A rater, the schema it accepts, and the `prepare` that builds its inputs |
| [`Book`](/relativities/reference/relativities#book) | Named pandas tables checked against a line's schema |
| [`Study`](/relativities/reference/relativities#study) | A recipe for versions of one book: scenarios and sampled draws |
| [`Market`](/relativities/reference/relativities#market) | Named programs to compare |

| Verb | What it does |
| - | - |
| `load` | Gets a rater or a program, by catalog ID or local path |
| `download` | Writes a catalog bundle to a local path |
| `rate` | Rates carrier inputs, a book, or a study |
| `explain` | Shows the inputs and each calculated value behind one result |
| `with_…` | Returns a changed copy, and keeps the original |

For carrier-specific inputs, `Rater.rate` returns a `RatingResult`; call `to_pandas()` for analysis.
`Program.rate` and `Market.rate` return DataFrames directly.

Each layer adds its key columns to the result:

| You rate | With | Rows are keyed by |
| - | - | - |
| Book | Program | `submission_id` |
| Study | Program | `submission_id`, `scenario_id`, `draw_id` |
| Book | Market | `submission_id`, `program` |
| Study | Market | `submission_id`, `scenario_id`, `draw_id`, `program` |

## Make the comparison defensible

Each carrier defines its premium term, coverages, and outcome columns. Choose a common basis before comparing premiums.
Retain unrated submissions and their reasons in your exhibit, and distinguish underwriting eligibility from rating status.
[Compare carriers](/relativities/how-to/compare-carriers) walks through these checks.

Use [Prepare a book](/relativities/how-to/prepare-a-book) to preserve reported facts and your own segment dimensions.
Use [Validate a program](/relativities/how-to/validate-a-program) to check the filing version, mapping assumptions, and independent rating examples.
Premium comparisons measure price position. Claims, expenses, and customer response require their own evidence for profitability or conversion analysis.

## Build and inspect raters

[RSL](/relativities/rsl/overview) expresses rating calculations, input constraints, tables, rounding, and source citations.
Its compiler checks the implemented algorithm; source review and independent examples establish fidelity to the filing.
[Package a program](/relativities/how-to/package-a-program) to distribute that rater with its `prepare`, schema and examples.

The [Python reference](/relativities/reference/relativities), [PPA book schema](/relativities/reference/book-schema), and [result reference](/relativities/reference/results) describe the API contracts.

The examples use synthetic households and rating algorithms. They illustrate analytical methods and package behavior rather than market premium levels.


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