Annotate a table

In this first tutorial, you open a small pandas table in a Metanno tab, mark some notes as reviewed, and read your annotations back in Python. It takes about five minutes and needs no configuration.

Before you start

Install Metanno as described in Installation, then open a notebook in JupyterLab.

Open the table

Run this cell, which puts three notes in a Store, the object Python and Metanno share:

import pandas as pd
from pret import DataFrame, create_store

from metanno import view_opener

notes = pd.DataFrame(
    [
        {"note_id": 1, "text": "Follow-up on Monday", "reviewed": False},
        {"note_id": 2, "text": "No further treatment", "reviewed": False},
        {"note_id": 3, "text": "Follow-up in 3 months", "reviewed": False},
    ]
)
store = create_store({"notes": DataFrame(notes)}, sync=True)
view_opener(store)

The cell shows an opener:

The view opener below a notebook cell

Click Open with Metanno: a tab opens beside your notebook, with the table on the left and the Selected rows panel on the right. The menu next to the button chooses how to display the data: table for now, and your own views once you write some, like note_tnm above.

Try the table before going further:

type follow in the box under the text header to keep the matching notes
click the ⋮ button of a column header to sort by that column
select a row to see its fields in Selected rows

What can I type in a filter box?

Filter text	Keeps rows where the column
`follow`	contains `follow`, or equals it for numbers and booleans
`= 1`, `!= 1`, `< 1`, `>= 1`	compares with the value
`in (1, 2)`	equals one of the values
`starts with follow`, `ends with up`	starts or ends with the text
`is null`, `is not null`	is missing or present

Make it editable

This first tab is a preview: you can look, but not edit. To annotate, save the Store to a file and open the saved copy:

from pret import save_store

saved = save_store(store, "review.pret")
view_opener(saved)

Click the new Open with Metanno. In this tab, double-click the text of note 1, change it to Follow-up on Tuesday and press Enter, then tick the reviewed box of notes 1 and 3.

There is no save button: each edit is written to review.pret as soon as you make it.

What is review.pret?

A SQLite database holding your table and the history of its edits, which also lets you undo with Ctrl+Z. Pret's Inside a Store file explains what it contains. save_store never overwrites a file: if you run the cell again, use load_store("review.pret") instead.

Read your annotations in Python

Back in the notebook, the saved Store already holds your edits:

saved["notes"].materialize().to_pandas()

	note_id	text	reviewed
0	1	Follow-up on Tuesday	True
1	2	No further treatment	False
2	3	Follow-up in 3 months	True

It also works the other way around. Run this cell while watching the tab:

saved["notes"].update(identity={"note_id": 2}, values={"reviewed": True})

The box of note 2 gets ticked: Python and the tab edit the same data. The notes pandas table you started from is left unchanged.

Come back later

Close the tab, or even restart the kernel. To continue, run in any notebook of the same folder:

from pret import load_store

from metanno import view_opener

view_opener(load_store("review.pret"))

Your edits are all there, and new ones keep being saved to the same file.

Find it in the sidebar

Files saved in the metanno-home/annotations folder, at the root of the JupyterLab file browser, are listed in the Metanno sidebar, so you can reopen them without a notebook. The next tutorial shows that sidebar.