vis-chronicle

vis-chronicle is a tool to generate web-based timelines from Wikidata SPARQL queries. You feed the tool a specification JSON file that describes what items to put on the timeline. The tool gathers the needed data from Wikidata and produces a JSON file suitable for feeding directly to vis-timeline.

vis-chronicle-demo is a demo application using this tool. View the output at https://brianmacintosh.github.io/vis-chronicle-demo/.

!Screenshot of a timeline showing United States presidents and their terms.

Installation

npm install vis-chronicle --save-dev

Execution

The tool can be run as a package script like vis-chronicle ./src/timeline.json -v.

The tool takes these parameters on the command line:
* (Mandatory) The name of the input file or directory. If a directory, all JSON files in the directory will be combined together.
* (Optional) The name of the output file. Defaults to intermediate/timeline.json.
* -v[erbose]: Print verbose output, including the actual queries being run.
* -skip-wd-cache: Do not read anything from the local cache, query all data fresh.
* -q[uery-url]: The URL of the SPARQL endpoint. Defaults to https://query.wikidata.org/sparql.
* -l[ang]: Language priorities to use when fetching labels. Defaults to en,mul. See SPARQL/SERVICE - Label.

Example

This specification file generates a timeline containing the lifespans of every United States president.

``json
{
"groups":
[
{
"id": "presidents",
"content": ""
}
],
"options":
{
"width": "100%",
"preferZoom": false,
"showCurrentTime": true,
"stack": false,
"stackSubgroups": false,
"verticalScroll": true
},
"queryTemplates":
{
"dateOfBirth": "{entity} p:P569 ?_prop. ?_prop psv:P569 ?_value.",
"dateOfDeath": "{entity} p:P570 ?_prop. ?_prop psv:P570 ?_value."
},
"items":
[
{
"comment": "All United States presidents",
"itemQuery": "?_node wdt:P39 wd:Q11696. ?_node wdt:P31 wd:Q5.",
"group": "presidents",

"startQuery": "#dateOfBirth",
"endQuery": "#dateOfDeath"
},
{
"label": "Ed Kealty (fictional)",
"entity": "Q5335019",
"group": "presidents",
"startQuery": "#dateOfBirth",
"endQuery": "#dateOfDeath"
}
]
}

`

groups and options are transparently passed through for vis-timeline - see the vis-timeline documentation. "stack": false and "stackSubgroups": false false are necessary in order for chronicle's open-ended ranges to display correctly.

queryTemplates contains template queries to be re-used by multiple items. vis-chronicle comes with a few template queries by default. Queries need to match a property (p:) using the variable ?_prop and a value (such as psv: or pqv:) using the variable ?_value. Also, any format variable like {format} will be replaced by the same-named value on the item entry, allowing templates to be parameterized.

items contains any number of items to generate. An item can be a single, literal item, or a multi-item generator (using itemQuery or items).

Item properties:
* label: Literal items only. Display label for the item. Can contain HTML. For generators, wildcards can be used:
* {_LABEL} will be replaced by the Wikidata label.
* {_QID} will be replaced by the Wikidata Q-id.
* itemQuery: Generators only. A SPARQL query segment to select all the items that should be generated. ?_node stands in for the ouput variable. The entity property is added to each item with the item's entity id. Item labels are automatically fetched from Wikidata.
* items: Generators only. An array of Wikidata ids. Works like itemQuery but with an explicit list.
* itemRange: Generators only. Only generates items whose time spans fall at least partially within the provided range.
* min
* max
* group: The vis-timeline group to put the item(s) in.
* className: CSS class to apply to the timeline div.
* type: vis-timeline type of the item.
* startQuery: A SPARQL query segment that selects the desired start time of the object. These should select Wikidata properties (not statements or values). Can be a query term like {entity} p:P569 ?_prop. ?_prop psv:P569 ?_value. or a template query like #dateOfBirth.
* endQuery: Same as startQuery, but for the end time.
* startEndQuery: Use instead of startQuery and endQuery separately if the start and end times are from qualifiers. This guarantees they will be drawn from the same statement.
* general: General query segment, usually for selecting the item and property.
* start: Query segment for selecting the start value.
* end: Query segment for selecting the end value.
* expectedDuration: Describes the expected duration, for hinting if the start or end is missing.
* min: The absolute minimum duration.
* max: The absolute maximum duration.
* avg: The average duration.

chronicle contains configuration for chronicle itself (not passed through to the output):
* defaultLabel: Default format string to use for item labels without label. See label.
* maxUncertainTimePrecision: Default 10 (month). Maximum Wikidata time precision to treat as uncertain. Cleans up tiny, artifacty uncertainty ranges.
* shareSuccessiveUncertainty: Default true`. If true, uncertain ends of successive items (related by P1365 'replaces' or P1366 'replaced by') can be truncated such that the items fit togther.