> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.emtelligent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emtelligent.com/_mcp/server.

# flatten

This module provides a method for flattening JSON files from emtelliPro, in a
similar method to `emtellipro-flatten-json`.

**Examples:**

Simple usage involves reading a JSON file, and saving the documents
contained within to a TSV file.

```python
from emtellipro.data import ResultFile
from emtellipro.flatten import Flattener

result_file = ResultFile.load_path('path/to/result.json')
flattener = Flattener(include=('document_id', 'spans'))

flattener.add(*result_file.docs)
tables = flattener.flatten()

# write TSV files to the given directory
tables.write('path/to/output/directory/', 'tsv')
```

However, if you prefer to work with Pandas DataFrames, you can iterate over
the tables and convert them to dataframes.

```python
for name, table in tables:
    print(name)
    print(table.to_df())
```

## Module Contents

### Classes

| Name                                       | Description                                                                                              |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| [`Flattener`](#emtelliproflattenflattener) | Flattens annotated documents from emtelliPro into a set of tables.                                       |
| [`Tables`](#emtelliproflattentables)       | The flattened tables, produced by [`Flattener.flatten`](/nlp/python/reference/flatten#flattenerflatten). |
| [`Table`](#emtelliproflattentable)         | A single table in a [`Tables`](/nlp/python/reference/flatten#emtelliproflattentables) collection.        |

### API

#### `emtellipro.flatten.Flattener`

```python
class emtellipro.flatten.Flattener(include=())
```

**Bases:** object

Flattens annotated documents from emtelliPro into a set of tables.

##### Initialization

**Parameters:**

* **include**:
  A list of extra columns to include when generating the
  flattened tables.
  document_id
  The ID of the document containg each item.
  spans
  The character spans for each item.
  spans_in_sentences
  The character spans for each item, adjusted to be relative
  to the containing sentence.

##### `Flattener.add`

```python
add(*docs: emtellipro.data.AnnotatedDocument)
```

Add documents to the flattener.

**Parameters:**

**`*docs`**

Annotated documents.

---

##### `Flattener.flatten`

```python
flatten() -> emtellipro.flatten.Tables
```

Flatten the documents into tables.

**Returns:**

The flattened tables.

**Return type:** [`Tables`](/nlp/python/reference/flatten#emtelliproflattentables)

#### `emtellipro.flatten.Tables`

```python
class emtellipro.flatten.Tables(tables)
```

**Bases:** object

The flattened tables, produced by `Flattener.flatten`.

> **Warning**
>
> This class should not be instantiated by user code.

**Examples:**

This table can be iterated over, which is helpful for storing to custom
file paths, or for converting the table to a pandas DataFrame.

```python
tables: Tables = flattener.flatten()

for name, table in tables:
    print(table.to_df())
```

##### Initialization

**Parameters:**

* **tables**: The tables (internal data structure).

##### `Tables.names`

```python
property names
```

A list of all the table names.

##### `Tables.__iter__`

```python
__iter__()
```

Iterate over tuples containing the table name, and `Table`
instance.

##### `Tables.write`

```python
write(
    outdir,
    format,
    values_separator = '::',
    dewhitespace = False
)
```

Write the tables to the given output directory.

**Parameters:**

**`outdir`**

Path to directory where to store the flattened files.

---

**`format`**

The format for the flattened files. May be `tsv`, `json`,
and `jsonl`.

---

**`values_separator`** — default: '::'

Separator for values in multi-valued attribute or argument
fields in output formats that flatten field values to text.

---

**`dewhitespace`** — default: False

Replace whitespace in text fields with visual marker
characters.

---

#### `emtellipro.flatten.Table`

```python
class emtellipro.flatten.Table(items)
```

**Bases:** object

A single table in a `Tables` collection.

##### Initialization

**Parameters:**

* **items**: The items in the table (private data structure).

##### `Table.write`

```python
write(
    path,
    format,
    values_separator = '::',
    dewhitespace = False
)
```

Write the table to the given output file.

**Parameters:**

**`path`**

The path of the file in which to save the data.

---

**`format`**

The format for the flattened files. May be `tsv`, `json`,
and `jsonl`.

---

**`values_separator`** — default: '::'

Separator for values in multi-valued attribute or argument
fields in output formats that flatten field values to text.

---

**`dewhitespace`** — default: False

Replace whitespace in text fields with visual marker
characters.

---

##### `Table.to_df`

```python
to_df(
    values_separator = '::', dewhitespace = False
)
```

Return a pandas DataFrame containing the data.

**Parameters:**

**`values_separator`** — default: '::'

Separator for values in multi-valued attribute or argument
fields in output formats that flatten field values to text.

---

**`dewhitespace`** — default: False

Replace whitespace in text fields with visual marker
characters.

---