# Find negations and modals

Which sentences of a legal text are negated, and which carry a modal verb, read off each sentence's dependency tree.

## Input

[The Constitution of the United States: the Preamble, and Article I, Sections 1 and 2 (opening)](https://www.archives.gov/founding-docs/constitution-transcript), The Constitutional Convention, 1787. Public domain (a founding document of the United States, 1787).

The calls read it as `constitution-article-one.txt` in the directory they run from:

```bash
curl -fLO https://mox-labs.github.io/matra/example-files/negations-and-modals/constitution-article-one.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("constitution-article-one.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="constitution-article-one.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 constitution-article-one.txt
```

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

Trimmed: only `result.sections[0].paragraphs[2].sentences`, `tokens` shown as a count, lists cut to the first 2, long strings shortened.

```jsonc
[
  {
    "span": {
      "byte_start": 482,
      "byte_end": 739
    },
    "text": "The House of Representatives shall be composed of Members chosen every …",
    "tokens": [ /* 44 items */ ],
    "word_count": 42,
    "tree_depth": 6,
    "passive": true,
    "negations": [],
    "modals": [
      {
        "aux_id": 5,
        "aux_lemma": "shall",
        "head_id": 7
      },
      {
        "aux_id": 28,
        "aux_lemma": "shall",
        "head_id": 29
      }
    ],
    "clausal_complements": [],
    "root_adverbials": [],
    "hearst_pairs": [],
    "root_mood": null
  },
  {
    "span": {
      "byte_start": 740,
      "byte_end": 982
    },
    "text": "No Person shall be a Representative who shall not have attained to the …",
    "tokens": [ /* 51 items */ ],
    "word_count": 46,
    "tree_depth": 7,
    "passive": true,
    "negations": [
      {
        "cue_id": 1,
        "cue_lemma": "no",
        "head_id": 2
      },
      {
        "cue_id": 9,
        "cue_lemma": "not",
        "head_id": 11
      }
      // … 1 more
    ],
    "modals": [
      {
        "aux_id": 3,
        "aux_lemma": "shall",
        "head_id": 6
      },
      {
        "aux_id": 8,
        "aux_lemma": "shall",
        "head_id": 11
      }
      // … 2 more
    ],
    "clausal_complements": [],
    "root_adverbials": [],
    "hearst_pairs": [],
    "root_mood": null
  }
]
```

The whole output: https://mox-labs.github.io/matra/example-files/negations-and-modals/output.json, and what the CLI prints: https://mox-labs.github.io/matra/example-files/negations-and-modals/cli.json.
Every primitive of every sentence, marked on the word it is read from and the word it attaches to:

<figure-primitives input="constitution-article-one" />

## What to notice

- Every sentence has a `negations` list and a `modals` list, empty when there is none. A negation names its cue (`cue_lemma`, at token `cue_id`) and the word it attaches to (`head_id`). A modal names its auxiliary (`aux_lemma`, at `aux_id`) and the word it governs (`head_id`). The ids are token ids within the sentence.
- The second sentence of Section 2 has three negations, `no` on `Person` and `not` twice, and four modals, each `shall`. To the parser the Constitution's `shall` is a modal like any other.
- One `not` attaches to `shall` rather than to a verb: in "who shall not, when elected, be an Inhabitant", the parser hung the negation on the auxiliary. `head_id` is what the tree says, and that is all it says.
- To collect the negated sentences, keep those whose `negations` is not empty. What a negation means for your purpose is your code's decision; matra reports where it is.
