# Compare readability across paragraphs

The three paragraph measures of The Federalist No. 10, to see where the essay is harder going and where it eases.

## Input

[The Federalist No. 10, the essay body](https://www.gutenberg.org/ebooks/1404), James Madison (as Publius). Public domain (first published 1787).

The calls read it as `federalist-10.txt` in the directory they run from:

```bash
curl -fLO https://mox-labs.github.io/matra/example-files/readability-by-paragraph/federalist-10.txt
```
## The call

Rust:

```rust
// cargo add matra@0.3 serde_json
use matra::{Engine, Input};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Loads the English model, downloading it on first use.
    let engine = Engine::new()?;
    let doc = engine.analyze(Input::file("federalist-10.txt"))?;
    println!("{}", serde_json::to_string_pretty(&doc)?);
    Ok(())
}
```

Python:

```python
# pip install 'matra>=0.3'
import json

import matra

engine = matra.Engine()  # downloads the English model on first use
doc = engine.analyze(file="federalist-10.txt")  # a str alone would be text, not a path
print(json.dumps(doc.to_dict(), indent=2, ensure_ascii=False))
```

The command line, which prints the output below inside an envelope:

```bash
matra analyze --json federalist-10.txt
```

```jsonc
{
  "format_version": 2,
  "command": "analyze",
  "input": "federalist-10.txt",
  "result": /* the output below */,
  "error": null
}
```
## Output

Trimmed: `sentences` shown as a count, lists cut to the first 3, long strings shortened.

```jsonc
{
  "provenance": {
    "matra": "0.3.0",
    "schema": "2.0",
    "parser": {
      "name": "udpipe",
      "model": "english-ewt-ud-2.5-191206",
      "sha256": "784bd0fa85e3d831fd02a55290d0acfd05c953159dc38cc33d52e1b28add9957",
      "license": "CC BY-NC-SA 4.0 (non-commercial)"
    },
    "format": "plain_text",
    "source": {
      "path": "federalist-10.txt",
      "bytes": 17880,
      "sha256": "e074108c9cdf3d26db71dd52b22ab9f1e1af47b94618e3707daee74673b79a00"
    }
  },
  "sections": [
    {
      "heading": null,
      "level": 0,
      "span": null,
      "paragraphs": [
        {
          "span": {
            "byte_start": 0,
            "byte_end": 2351
          },
          "text": "AMONG the numerous advantages promised by a well constructed Union, non…",
          "kind": "paragraph",
          "sentences": [ /* 9 items */ ],
          "metrics": {
            "readability_grade": 20.724682332463008,
            "lexical_density": 0.4699738903394256,
            "compression_ratio": 0.4564015312632922
          }
        },
        {
          "span": {
            "byte_start": 2353,
            "byte_end": 2644
          },
          "text": "By a faction, I understand a number of citizens, whether amounting to a…",
          "kind": "paragraph",
          "sentences": [ /* 1 item */ ],
          "metrics": {
            "readability_grade": 24.8921568627451,
            "lexical_density": 0.43137254901960786,
            "compression_ratio": 0.563573883161512
          }
        },
        {
          "span": {
            "byte_start": 2646,
            "byte_end": 2775
          },
          "text": "There are two methods of curing the mischiefs of faction: the one, by r…",
          "kind": "paragraph",
          "sentences": [ /* 1 item */ ],
          "metrics": {
            "readability_grade": 10.690000000000001,
            "lexical_density": 0.45454545454545453,
            "compression_ratio": null
          }
        }
        // … 20 more
      ]
    }
  ],
  "metrics": {
    "total_words": 3000,
    "total_sentences": 88,
    "paragraph_count": 23,
    "mean_sentence_length": 34.09090909090909,
    "sentence_length_std": 17.36930597256701,
    "vocabulary_ttr": 0.25233333333333335,
    "nominalization_ratio": 0.042333333333333334,
    "passive_ratio": 0.42045454545454547
  },
  "skipped": []
}
```

The whole output: https://mox-labs.github.io/matra/example-files/readability-by-paragraph/output.json, and what the CLI prints: https://mox-labs.github.io/matra/example-files/readability-by-paragraph/cli.json.
Each measure over the essay's 23 paragraphs, one panel each:

<figure-metrics input="federalist-10" />

## What to notice

- Each paragraph carries `readability_grade`, `lexical_density` and `compression_ratio` in its `metrics`. The document's own `metrics`, beside its `sections`, carry the counts, the sentence-length statistics, `vocabulary_ttr`, `nominalization_ratio` and `passive_ratio`.
- The grade runs from 10.69 (paragraph 3) to 32.06 (paragraph 18). It is the Flesch-Kincaid formula over sentence length and syllables per word ([Methodology](../reference/methodology.md#flesch-kincaid-grade-level)), so an eighteenth-century paragraph of a few long sentences scores far above any school grade. Compare paragraphs with each other, not with a grade band.
- `compression_ratio` is `null` for four paragraphs, the ones of 50 words or fewer. `null` means the measure declined to run, not that it measured zero; which measure needs what is in the [Rust guide](../guides/rust.md#why-a-metric-slot-is-none).
