Organising data in spreadsheets

You can put your data into PLATO’s shape with an ordinary spreadsheet in Excel, LibreOffice or Google Sheets, using temPlato, PLATO’s spreadsheet template. It has eight sheets, one for each kind of information, and filling them in is also a way of working out what your data is: which places it is about, which sources it rests on, and what each source actually says. Most datasets use only three or four of the sheets.

Get temPlato

  • temPlato workbook (.xlsx): the easiest way to start. Hover over any column heading to see what to put in it; columns with a fixed list of values offer a drop-down.

  • temPlato as CSV files (.zip): the same eight sheets as separate CSV files, with the table definitions.

The eight sheets

Sheet

One row for each…

Needed?

places

place your data is about

always

sources

source you cite

always

names

time a source gives a name for a place

usually

locations

time a source gives a location

if you have coordinates

types

time a source says what kind of place it is

if you have types

relations

time a source relates two places, such as a parish in a hundred

if you have them

properties

other fact a source states, such as a population

rarely

identities

record elsewhere that is the same place as one of yours

if you know them

The places sheet becomes PLATO’s SpatialEntities; each row of names, locations, types, relations and properties becomes one attestation. The ideas in five minutes explains what that means.

Rules that apply everywhere

  1. Keep all eight sheets, even if you leave some empty apart from their headings. Do not rename, reorder or delete columns; leave a cell empty if you have nothing to put in it.

  2. Identifiers are yours to choose. place_id and source_id can be any short text, such as bristol or s12, as long as each is used only once in its sheet. The other sheets use them to refer to a place or a source.

  3. Every row of evidence needs a place, a source and a date. In names, locations, types, relations and properties, fill in place_id, source_id and date on every row.

  4. Write the date as your source gives it, or undated. Then, if you can, put the earliest and latest years in from and to, with at least four digits: 0921, not 921. Years BCE take a minus sign, and deep time as many digits as it needs (-12000). For a single year, put it in both. Leave to empty if the end is unknown.

  5. Some columns take a fixed word, such as Headword or ContainedIn. Use it exactly as written, with the same capital letters. The workbook offers these as a drop-down; the vocabularies page lists them all.

  6. One fact per row. If a source gives two spellings, that is two rows in names. If two sources give the same spelling, that is also two rows.

  7. A source that denies something is recorded too. If a source says a place had no market, add a row in types with market and denied set to yes. The row is then a denial, so give only the one thing denied. If the source only reports something (“it is said”), hedges it, or leaves it undecided, set stance to Reported, Tentative or Doubted: that is the source’s stance, not a denial, and not your own certainty.

Note

Spreadsheet programs sometimes “correct” what you type: 0921 becomes 921, and 1-2 becomes a date. The temPlato workbook formats its columns as text to prevent this. If you build your own sheets, format the columns as text before typing, and save CSV files as CSV UTF-8.

What the spreadsheets cannot say

The spreadsheets cover most datasets, but a few things need the JSON format instead:

  • one piece of evidence that rests on two sources at once, such as the place-name surveys’ “1252 Cl et passim to 1346 Harl”;

  • one piece of evidence giving several facts together, such as a name and a location in a single statement;

  • one scholar’s comment on another’s evidence (“this contradicts that”);

  • readings that are alternatives to each other, such as a “Neuton” that could be either of two Newtons, of which at most one is right;

  • a relation type that PLATO does not list yet. Ask for it to be added by opening an issue.

Checking your tables

The temPlato workbook catches most mistakes as you type. For a full check, open PLATO tools, drop your eight CSV files (or the workbook, or a zip of the files) onto the page, and press Check. It runs in your browser, so nothing is uploaded, and it lists every problem with its sheet, row and column, in plain words. It also says what PLATO JSON could not hold, should you convert the tables later.

If you prefer the command line, or have many sets of tables to check, PLATO tools runs there too, with the same checks and the same report. You need Node.js 24 or later; then, in a terminal:

# a folder holding your eight CSV files is one set of tables;
# a zip of them, or the workbook, works the same way
npx github:pelagios/plato-tools check my-tables/

Name as many folders or files as you like: each gets its own report, and a total comes at the end. The instructions list the other options, including conversion.

The tables are also described in the W3C standard CSV on the Web (CSVW), so any CSVW validator can check them against the table definitions. For example, with Python installed:

pip install csvw
# put csv-metadata.json in the same folder as your eight CSV files, then:
csvwvalidate csv-metadata.json

It reports, with the row and column, any identifier that does not exist, any missing required value and any value that is not allowed.

Using your tables

Once your tables are complete and pass the check above, your data is in PLATO’s shape. Any tool that implements PLATO can read it, and any CSVW processor can turn it into linked data (see Linked data). PLATO tools converts the tables to PLATO JSON, RDF or Linked Places Format in your browser. You can publish the tables as they are, for example in a repository such as Zenodo beside a publication, or load them into a platform that works with PLATO; platforms may prefer either the workbook or the eight CSV files.