highlight · part ii · 7

A cell can hold a number, a list, or a whole table.

A number. A code. A paragraph. A list. A whole linked table.

Atoms

number 42, 3.14, 125.7

true / false true or false; included or excluded

code one of a fixed set: "Include", "Exclude", "Human Review"

short text a phrase: "Cognitive Behavioural Therapy"

paragraph a free-form response — even several sentences

Structures

list every outcome, every person named, every citation

linked table rows × columns: arms by name, dose, duration, n

Data Mint inspection grid with paragraph answers in two columns and list cells reading [7 items], [8 items], and so on. — Paragraph cells and list cells in the same grid. Open a list cell and the table unfolds.

Name the shape. The codebook does the rest.

@karlrohe

An item is anything that can be responded to with plain text. That is the whole test. If a careful reader could write the answer in a sentence, it can be an item in a codebook.

definition

item — one codebook question as it lands on one document. The column is the item across your whole corpus; the cell is the item on a single document.

A paragraph answer is the one I reach for most. Ask the reader to describe the design of the study. Plain text, paragraph response, no codes. It is almost like blooming. Often that is enough, and with twenty documents it just helps to see it.

A list exists because you do not know how many columns you would need. Every author and their affiliation. Every citation. Every outcome. One paper has a hundred and the next has none, so there is no column count that fits. The list goes inside one cell instead.

A linked table is a list with more than one column. You still do not know how many rows. In Data Mint a table is a bundle of parallel lists, and the first list holds the row names.

Producing those row names is the indexing problem, and it is often the hardest step. You want every treatment effect estimated in the paper, and something has to go find all of them. This is a very hard thing. You should spend real time on it, and you should probably put a scaffolding question or two in front of it.

definition

indexing problem — enumerating the rows before you can fill them in. Finding every effect, every arm, every outcome the paper reports. Miss a row in the index and every column loses that row.

Here is a linked table written out in the codebook grammar. These are four fields from a general RCT codebook, trimmed to the tags that do the structural work:

## result_descriptions
**Settings:** phase=1, table=result, type=KEY
**Question:** What comparisons of arms on outcomes are reported in this paper,
and what does each report?
**Answer Type:** list

## result_arm_a
**Settings:** phase=1, table=result, type=COL
**Question:** For each effect, what is the first arm in the comparison?
**Answer Type:** list

## result_estimate
**Settings:** phase=1, table=result, type=COL
**Question:** For each effect, what is the estimated effect size?
**Answer Type:** list

## result_p_value
**Settings:** phase=1, table=result, type=COL
**Question:** For each effect, what is the p-value or significance indicator?
**Answer Type:** list

A Data Mint results grid: paragraph answers in some columns, list cells reading '[7 items]' in others, with consensus marks. — Five documents, one row each. Two columns hold paragraph answers. The rest hold lists, shown as a count until you open them. The mark on each cell is the consensus verdict.

A linked table opened from one cell: an index column of effect labels, a description column, and a values column, with tabs for each reader and the consensus. — One cell, opened. The index column names every treatment effect the reader found. The columns to its right were answered once per row. Each reader gets a tab.

One tag does the structural work: type=KEY. result_descriptions is the index. The reader returns a list, and each entry it finds becomes a row. Every field marked type=COL in the same table=result then returns a list aligned to that index, one value per row. You never state how many rows there are. The KEY field decides, and the rest follow it. If you also extract the trial's arms in an earlier phase, a column here can be marked type=FK with ref=armTABLE.arm_label. The engine then injects the arm names it already verified into that question, so the reader can only pick from arms that exist. The arms table in that codebook is the same phase, so it uses a Description instruction instead.

Every column after the index reads like an ordinary item. In the codebook you see a list of treatment-effect names, then treatment-effect size, and the second one looks like a plain numeric question. Behind the scenes it knows to answer once for every effect the index found. Add the estimation technique, a confidence interval, a p-value. Each is one more item in the codebook.