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/.

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.

{
	"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.