Browse the canonical dataset
The PeriodO client is an application that runs in your browser. It can be used to browse and edit any dataset that conforms to the PeriodO data model. But most people are probably interested in looking at the canonical dataset curated by the PeriodO project.
When you first load the client, you are prompted to select a backend. A backend is simply a location from which the client will load data. The client supports three kinds of backends:
A web backend loads data from a specified URL. Data loaded from a web backend can only be browsed, not edited.
A file backend loads data from a local file. Data loaded from a file backend is also browse-only.
An IndexedDB backend loads data from a local database running in your browser. Data in an IndexedDB backend can be edited as well as browsed. (Note that Safari does not yet have full support for IndexedDB.)
Initially you should see only one backend, a web backend pointing to the canonical PeriodO dataset (at
Clicking on the “disc with a down arrow” icon will download the data from the canonical web backend to a local file. Clicking on the name of the backend (“Canonical”) will load the data from the canonical backend into the client, and you should see a browsing interface like this:
Finding and comparing period definitions
In the browsing interface it is possible to find and compare period definitions by applying one of several filters (time range, source, language, spatial coverage) or searching by text string.
To filter by time range, on the right side of the browser window hover over the x-axis of the time range chart to find the desired ISO year. Drag your cursor to select a desired time range, and your selection will appear highlighted in gray in the time range. Period definitions which fall within this time range appear on the left side of the browser window under Periods, where you can view between 10 and 250 results at a time. Note that these results remain until you click back in the time range chart to reset the dataset.
To filter by source, locate the desired contributor in the Source box (which provides author, collection name, and year of creation/publication): these are listed in descending order by the number of periods contributed to the PeriodO dataset. You can also use
Ctrl+F to find a contributor by name. Clicking on the desired collection retrieves and displays all periods in that collection, and moves this collection to the top of the Source list. Clicking Reset on the right of the box causes the interface to display all records in the dataset again.
To filter by language, locate the desired language in the Language box: these are listed in descending order by the number of periods contributed to the dataset. You can also use
Ctrl+F to find a language by name. Clicking on the desired language retrieves and displays all periods entered in that language script, and moves this language to the top of the Language list. Clicking Reset on the right of the box causes the interface to display all records in the dataset again.
To filter by spatial coverage (geographic location), locate the desired location in the Spatial coverage box: these are listed in descending order by the number of periods contributed to the dataset. You can also use
Ctrl+F to find a spatial coverage by name. These terms reflect the labels used by the source to describe the period’s spatial coverage, NOT the coordinate-based geographic entity with which we have associated them. The large quantity of
undefined values reflect records that could clearly be associated with a modern national boundary, but for which the source did not provide a verbal label for spatial coverage (most of these are from Fasti Online and the British Museum). Clicking on the desired spatial coverage label retrieves and displays all periods associated with that label, and moves this term to the top of the Spatial coverage list. Clicking Reset on the right of the box auses the interface to display all records in the dataset again.
To search by text string, enter your text in the search box. Periods containing this text string will display on the left under the Periods list.
Results sets derived from filtering or searching can also be recursively filtered using all of the same methods as above, until only one result is left.
A results set can be ordered by label, earliest start, and latest stop, just like the full dataset. This is the simplest way to compare date ranges between period definitions. Clicking within any individual result expands the full period definition, including more detailed information including spatial coverage, permalink for the definition and its collection, and notes.
Finding and comparing periods
You can search for periods by name, and you can find sets of periods from specific source authorities, named in specific languages, or having specific spatial coverage.
TODO resolve “labels” vs. “names” terminology
To search for periods by name, enter some text in the search box. If the Labels option is selected, the search will be restricted to the preferred (original) name of each period. If the Labels + alternate labels option is selected, the search will also include the alternate (translated) names of each period.
To filter by source authority, locate the desired authority in the Authority list: these are listed in descending order by the number of periods they contain (indicated to the left of the authority’s name). You can use
Ctrl+F to search for an authority by name.
Clicking on an authority filters the list of periods to include only periods belonging to that authority, and moves the selected authority to the top of the Authority list. Selecting multiple authorities will show all the periods defined by those authorities. Clicking Clear at the top of the authority list will show all the periods again.
Filtering by language works just like filtering by source: click on one or more languages in the Language list to show only periods originally named in those languages.
The spatial coverage of a period in PeriodO can be specified in two ways: 1) as a string of text (usually a place name, but sometimes a description of multiple places) quoted from the source authority, and 2) as a set of links to places identified in Wikidata. As a result there are two ways to filter periods by spatial coverage.
The first way to filter periods by spatial coverage uses the descriptions quoted from the source authorities, and works just like filtering by language or authority. Locate the desired spatial coverage description in the Spatial coverage list, and select it by clicking. Again, you can use
Ctrl+F to search for a specific place name in a spatial coverage description.
The second way to filter periods by spatial coverage uses the links to Wikidata places. Under Filter by place, click Select places. A map and a search box will appear. Enter some text to see a list of matching place names. Select a place name to add it to the filter. Adding multiple places to the filter will show periods linked to any of those places. The spatial coverage of the places in the filter will be shown on the map, until you click Done. To remove a place from the filter, click the X following the place name, or use
Tab to highlight the place name and then press
Searches and filters can be combined; for example you might search for periods that 1) have
bronz in their names, 2) are linked with the Wikidata records for Spain or France, and 3) are defined by the ARIADNE authority. The resulting list will include only periods that satisfy all three of these criteria.
The periods satisfying the current search and filter criteria are shown as spans on a timeline, as regions on a map, and as sortable rows in a table.
Use the timeline to compare the temporal extents of the selected periods. There are two styles of timeline. The histogram style shows, for each unit of time, how many of the selected periods include that unit. The stacked bars style shows the temporal extent of each period as a horizontal bar.
Use the map to get a sense of the combined spatial coverage of the selected periods, as specified by the Wikidata places they are linked to. The regions highlighted in purple indicate the spatial extents of all the Wikidata places linked to by the selected set of periods. If you focus on a period by clicking on or hovering over it in the tabular list of periods, the the spatial extents of the Wikidata places linked with that one period will be highlighted in red.
The map display should be interpreted cautiously, as not all periods are linked to Wikidata places, and not all Wikidata places are currently mappable, i.e. we do not know the geometry of their spatial extents. (Learn more about the PeriodO place name gazetteers.)
The periods in the table can be sorted by clicking on the column headers.
Getting structured data for a period collection
The entire PeriodO dataset can be downloaded as a JSON-LD file from the Switch backends page (click on the disk icon). You can also download any datasets you have created in a local database from this page as a JSON-LD file (see Creating a local database below). This can be very useful if you wish to share your period definitions with someone else, or if you need structured data for your own visualization or data management.
You can also view structured data for an individual collection from the page for that collection. At the top of the browser window, which shows Browse by Period by default, click the Browse by Collection tab. This will list all of the period collections.
Locate the desired collection (20 are currently viewable at once) by scrolling down or using
Ctrl+F, and clicking on the source title. This brings you to the page for this collection, which displays collection-level information at the top followed by individual period definitions below. These periods can be sorted by label, earliest start, or latest stop.
Finding and using a URI for a period or collection
Every period and collection that is part of the canonical dataset has been assigned a stable, permanent URI. When viewing the canonical dataset, if you are browsing by period, click on any period to expand the data display; this will show the permalink for the period.
Right-click or highlight to copy this link. Clicking on In collection will bring you to the collection page, at the top of which is the permalink for the collection. Right-click or highlight to copy this link.
Use PeriodO permalinks for citation and sharing: ensure that your period or collection URI from PeriodO always starts with
Creating a local database
! To edit periods and period collections, you must create a local database. To do this, first Switch backends, and then under Add backend select IndexedDB (editable, stored locally), write in a name for your local database, and click Add.
You should see your newly added IndexedDB backend appear in the list of backends. Click the name of your backend to switch to it.
Initially your new local database (the backend you just created) will be empty, to fill it with some period definitions, go to the upper-right Menu drop-down and select Get data from server or file.
Next you should see the Sync window. With
https://test.perio.do/ supplied as the server URL option, click Fetch which will retrieve all the period collections from the PeriodO server. From this list of New period collections, find your desired collection(s) and check the box to the left of their listing. Checking one or more boxes enables the Continue button at the top of the window. Click this button to confirm your selection.
The next screen displays your selected collections; ensure all that you need are listed and then under Accept changes? click Yes.
You have now made a local, editable database containing the periods in the selected collections. Next, at the top beside Current backend click switch to return to the backend selection page. Click on the name of your local database, and you will see a list of all the periods in the database. From here, you can click the Browse by Collection tab to make edits or additions. Click the collection you wish to edit. You will see the collection page, now with two new options to Edit collection details (this will edit the collection-level description) or Add period (to add a new period definition to this particular collection).
You can also edit existing periods: locate the desired period in the collection, click on its row to expand the data entry, and find the blue Edit button beside the period. Clicking on this button will open a form using which you can edit the period definition.
Once you have completed your edits, click the blue Save button at the bottom left and you will return to the collection. At any time, you can export your local database as a file by clicking switch at the top of the browser window to return to the backend selection screen, and clicking the “disc with a down arrow” icon to download the structured data as a JSON-LD file.
Sharing a local database
Once you have created a local database and downloaded it following the steps above, you can share your JSON-LD file with others. You can also make further edits to your JSON file(s), or edit a file that someone else has shared with you. Under the Menu button in the upper-right of the browser window, select Get data from server or file. Next, under PeriodO data file click Choose file and upload the JSON file you wish to load and edit. Once you see the data in your file, you can follow the steps above to edit your period collection and definitions.
Submitting a patch
We welcome contributions and enhancements (“patches”) to the canonical PeriodO dataset. To submit a patch, you must first register for a free ORCID so that we can credit you properly. Once you have an ORCID, click Sign in at the top of the browser window. You will see a link to Create or Connect your ORCID iD.
Clicking this link will open a popup window. From this window you can sign into the ORCID website and grant permission to PeriodO to read your public information (such as your name).
Once you are successfully signed in, you should see your name at the top of the PeriodO window. Now you can open a local database that has the changes or additions that you would like to contribute. Under the Menu button in the upper right of the browser window, select Submit patch to server and submit your patch. Check that your patch was successfully submitted by selecting Review patches (again, under Menu) to see a list of the patches submitted to server.