@data

Declares a dataset under an #id: a table of values written inline, attached as a .csv or read from a URL, or boundaries attached as a .geojson.

On this page

#Attributes

srcImplicit
Where the dataset comes from: an attached file, or an https:// URL. A .csv file's header row names the columns, and a .geojson file holds boundaries; a file's extension decides which, and no other is accepted. A URL says what it returns with format:. Written as the implicit value, @data#survey:plants.csv or @data#stouts:https://api.sampleapis.com/beers/stouts(format: json). Omitted, the body holds the table inline.
Can be written as shorthand: @data:value
format
What a URL returns: csv and json are tables, geojson is boundaries. Required on a URL, since a URL rarely ends in an extension, and refused on a file, whose extension already says.
csvjsongeojson
path
Where the rows are in a json response, as a dotted path: path: results.items. Every array on the way is stepped into, and the objects the path ends on are the rows, each carrying the plain fields of every object above it. Omitted, the response itself is read: an array of objects is the rows, and a single object is one row.
next
The field of a json response that leads to the next page, as a dotted path: next: meta.cursor. A URL there is fetched as the next page, and any other value is sent back as a query parameter named after the path's last part, ?cursor=…. Pages are followed until the field is empty, and every page's rows are read in order.
key
The name of an API key the author has saved in Preferences, sent with each request: key: weather. Lowercase letters, digits and hyphens. A reader never sees the key.

#Allowed content

Body { }header and rows, pipe-delimited (inline form only)

#Examples

@data#islands{
    island     | area   | species
    Baltra     | 25.09  | 58
    Bartolomé  | 1.24   | 31
    Santa Cruz | 903.82 | 444
}
@data#survey:galapagos-plants-1973.csv
@data#stouts:https://api.sampleapis.com/beers/stouts(format: json; path: rating)

graph{
    scatter(x: #stouts.reviews; y: #stouts.average)
}
@data#islands{
    island     | area   | species
    Baltra     | 25.09  | 58
    Bartolomé  | 1.24   | 31
    Santa Cruz | 903.82 | 444
}

code{
    lines{
        area = np.array([{{#islands.area}}])
    }
}(
    language: python
)
@data#wards:sydney-wards.geojson
@data#turnout:turnout.csv

geo{
    choropleth(basemap: #wards; regions: #turnout.ward; value: #turnout.pct)
}(
    projection: conic
)

#Notes

  • The id is required: @data: requires an id — datasets are reached as #id.column.
  • Inline, the first row names the columns, cells are separated by |, and every row has as many cells as the header: @data: row 1 has 3 cells; the header declares 2. A cell cannot contain |. A cell is text, typed where it is used, and a blank cell is the empty text "", which a number position refuses, naming the row.
  • Column names are read in lower case, with spaces as hyphens: a header Species Count is the column species-count. A name written twice is refused: duplicate column name a.
  • A dataset is visible to the whole document wherever it is declared, including inside an @included partial. @for is the exception: it reads its dataset in document order, so the @data comes first.
  • Only .csv and .geojson files are attached: x.json has extension json, but only csv, geojson are permitted.
  • A URL must be https://, and must say what it returns: format: is required on a URL and refused on a file. A URL holding a space or any of { } ( ) [ ] ; " < > \ | ^ or a backtick is refused, naming the character and how to write it percent-encoded: [ as %5B. A URL built from a {{…}} value is written as src:, since the implicit value takes none.
  • A URL's response is fetched when the internote is published or its data refreshed, never as a reader opens it, so every reader sees the same rows. The columns are checked against that response, as a file's are.
  • In a json response a field that holds an object or an array is not a column: naming it is refused, as any unknown column is. path: reaches inside one instead.
  • An inline body and src together are refused: declare either an inline {grid} body or src:, not both.
  • A .geojson dataset has no columns and no rows. It is bound whole, in: #wards; #wards.name is refused with that fix, and boundaries are never written inline.
  • Packs bring datasets as well, through @use: #biology.lynx-hare.hare.

#Writing guidance

  • Checking a document's claims — Every other number worked out, every output quoted from a run, every dataset read and attached whole, every external fact checked and cited, or cut.

Last updated