1. Instructions tab
How to fill in the workbook, kept with it so the instructions travel with the file. The viewer ignores this tab.
2. Data tab
One row per coded quote. The theme, code, sub-code and strand columns build the map; repeating the same names on each row is what groups the quotes.
| Column | What goes in it | Required | Example |
|---|---|---|---|
quote_id | A unique identifier, for example BEL-001 Used to find and star quotes. Falls back to the row number if blank. Give each row its own ID, including a quote coded to more than one code. | Required | BEL-001 |
participant | The participant's pseudonym Keep one consistent format. | Required | Bella |
quote | The verbatim extract Never edited. The viewer keeps it as the record. | Required | Um, so, like, I get home and I just, you know, put it on straight away? Before I've even, like, taken my coat off. It's like, oh good, they're here. |
refined_quote | A tidied version for display Shown by default where a row has it, with the verbatim always available beside it. The verbatim stays in the quote column and is never changed. | Optional | I get home and put it on before I've even taken my coat off. It's like, good, they're here. |
theme | The theme the quote belongs to Spelt identically on every row. While themes are still forming in Themescape for students, candidate_theme can stand in for it. | Required | A friend on the sofa |
code | The code within the theme Leave blank for a quote that belongs to the theme itself. It shows when the theme is selected and draws no code node. | Conditional | Daily company |
subcode | A finer code within the code Needs a code. Only some codes will have them. | Optional | Habits and quirks |
subsubcode | A strand: a level under a sub-code, for when one part of a sub-code deserves its own attention Needs a sub-code. The column can be headed subsubcode or strand. Added in format 2.6. | Optional | |
candidate_theme | A working theme while the final theme is undecided Shown until you decide. If theme and candidate_theme are both blank, the quote is filed under Uncategorised. In Guided analysis each candidate theme is a pile; Set aside and Miscellaneous are reserved values. | Optional | |
illustrativeness | A number from 1 to 5 Orders the quotes within a code, highest first. | Optional | 5 |
preferred | Marks the illustrative quote for a code Y, Yes, TRUE, 1, x or a star all count. Favourite quotes come first in the reader, and Present mode features up to three for each code. Starring a quote in Work mode sets this column when you save your progress. | Optional | Y |
notes | The researcher's own memo Ignored by the viewer. | Optional | Revisit after the second round of coding. |
3. Framework tab
One row per theme, code, sub-code or strand with its working definition. Without it the themes and codes still appear; only the definitions are missing.
| Column | What goes in it | Required | Example |
|---|---|---|---|
name | The theme, code, sub-code or strand name Must match the Data tab exactly. | Required | A friend on the sofa |
definition | The working definition Shown in the reader when that theme or code is selected. Editable in Work mode. | Optional | Viewers describe characters as familiar, warm presences in their daily lives, close to friends, though they know the warmth runs one way. |
order | A whole number Theme rows only. Sets the display sequence. Themes without a number follow the order they first appear in Data. | Optional | 1 |
colour | A hex code such as #0070A6 Theme rows only. Overrides the viewer's colour for that theme. A blank cell keeps the viewer's colour. | Optional | #0070A6 |
central_concept | The theme's central organising concept Theme rows only. The viewer keeps it and writes it back into your exported files. | Optional | The characters are company, and the company feels real. |
includes | What the theme covers Theme rows only. Kept and written back on export. | Optional | Watching as daily company, knowing characters closely, talking to them and imagining their understanding. |
excludes | What the theme leaves out Theme rows only. Kept and written back on export. | Optional | Seeing oneself in characters (see Mirror on the screen). |
model_element | The part of the model a theme or code belongs to, for Model mode An element_id or name from the Model elements tab, or the word outside to keep it out of the model. A code left blank follows its theme, and sub-codes follow their code. | Optional |
4. Connections tab
One row per link between any two themes, codes, sub-codes or strands, drawn as a branch in the viewer. Connections can also be marked in Work mode and exported back to this format.
| Column | What goes in it | Required | Example |
|---|---|---|---|
from | A theme, code, sub-code or strand name Must match the Data tab exactly. A sub-code is written as Code > Sub-code, and a strand as Code > Sub-code > Strand. | Required | Who I wish I was |
to | A theme, code, sub-code or strand name As for from. | Required | Borrowed courage |
note | Why the two ends are linked Shown when the connection is selected. | Optional | Admiring a braver character turns into courage used in real life. |
type | empirical or theoretical Empirical is a solid branch, a link seen in the data. Theoretical is a dashed branch, an association you propose. Any value containing theor is read as theoretical. | Optional | empirical |
arrow | to, from or blank A connection with an arrow is shown as causal, and the arrow points at the effect. Blank means no arrow. | Optional | to |
5. Settings tab
Three columns: setting, value and where it appears. The setting names stay as they are and you fill in the value.
| Column | What goes in it | Required | Example |
|---|---|---|---|
project | The project title The large title at the top of the viewer, the browser tab and export file names. Without it, the Data file name becomes the title. | Optional | The Friends We Stream |
researcher | Your name The line above the title, shown as Researcher: Firstname Lastname. | Optional | Demo researcher |
subtitle | A short line under the title Shown under the title. | Optional | Bonds with characters from the series we watch |
version | A version label for the dataset Kept with the exports. | Optional | Example workbook 1.0 |
6. Model elements tab
For Model mode only. One row per element of the published model or framework you are mapping your data into. Download it as a CSV file with model and elements in its name.
| Column | What goes in it | Required | Example |
|---|---|---|---|
element_id | A short id, used once only Framework rows link to the model through this id or the name. | Required | JD |
name | The element's name | Required | |
parent | The element that holds this one as a group Its element_id or name. | Optional | |
type | Sorts elements in the key Each type takes its own colour. | Optional | Demands |
description | What the element is Shown when the element is selected. | Optional | |
source | The published work Shown when the element is selected. | Optional | |
row | A whole number With column, places top level elements in a grid. | Optional | |
column | A whole number With row, places top level elements in a grid. | Optional |
7. Model relationships tab
For Model mode only. One row per arrow in the model. Download it as a CSV file with model and relationships in its name.
| Column | What goes in it | Required | Example |
|---|---|---|---|
relationship_id | An id for this relationship Needed only when another row points to it. | Optional | |
from | An element_id or name | Required | |
to | An element_id or name, or the relationship_id of another row Pointing at a relationship_id draws this one onto the middle of that arrow, as a moderator. | Required | |
sign | positive, negative or blank | Optional | |
arrow | to, from, both or none Blank means to. | Optional | |
note | A note on the relationship Shown when the relationship is selected. | Optional | |
source | The published work Shown when the relationship is selected. | Optional |
Rules that matter most
Names are matched as plain text
A theme spelt two ways becomes two themes. Column names are matched without regard to case, extra columns are ignored and blank rows are skipped.
Every row needs a theme
A row without a code is a quote on the theme itself, which shows when the theme is selected and draws no code node. A row with neither a theme nor a candidate theme is filed under Uncategorised.
The verbatim quote is never altered
Verbatim quotes are never altered, with a separate refined column for presentation wording.
Confidential data goes in as files
CSV files are read in your browser and never leave your machine. The Google Sheets mode is opt in, for non-sensitive data only.
Loading the files
Download each tab you have used as a CSV file and add the files on the viewer's Start a project screen. The viewer matches each file to its slot by name: a name containing framework, connection or setting goes to that slot, a name containing model and elements or model and relationships goes to the Model mode slots, a file ending in .json goes to the Layout slot, and anything else is read as the Data file. Your browser reads the files on your own computer.
