location-linking is a preliminary implementation of workflows for linking historical documents in Rotunda, the digital imprint of the University of Virginia Press, to locations. It aims to automate much of this process while allowing humans to track the computer's reasoning through provenance metadata. This software contributes to their larger project of using artificial intelligence technologies to derive linked data from their annotated historical documents, which will substantially improve a researcher's ability to search through their documents and enable them to link with other historical datasets using linked data.
The Rotunda collection contains hundreds of thousands of annotated historical documents, and they want to augment them with linked data to enable better search algorithms and eventually cross-database search. There is currently not quite enough structured information to be able to author this linked data automatically and easily, so machine learning techniques are necessary.
However, using machine learning poses an issue for data reliability since conclusions these algorithms draw aren't always correct (in this domain, they're almost always less accurate than a human expert). Rotunda needs to be transparent about its use of machine learning and be able to improve the accuracy of the new linked dataset over time to maintain its reputation as a reliable source for researchers. Addressing these concerns has required careful design of the new database system.
The design currently being pursued stores a graph of assertions about the original historical documents and their contents. Assertions have associated provenance metadata which indicates how the assertion was made (human review, generation by an ML algorithm, etc.), who made it (human, computer acting on behalf of a human), and when it was made. For a researcher, this allows them to assess the veracity of any given assertion. For Rotunda team, this allows them to monitor their data verification process. The graph-based design also allows corrections to propagate easily (this will be shown with a concrete example in the next section).
So far, these efforts have mostly been focused on linking with other (internal) Rotunda databases. This software
extends the system being developed internally to connect with Geonames and
Wikidata for location information. It uses a proof-of-concept data store developed using
the RDF data model as a temporary substitute for the more complex final system. I designed this software such that the
final system can be swapped in relatively easily (as long as it provides an implementation of the
rotundalocations.db.base.Database abstract class).
git clone the repository, and then you can install the rotundalocations package into your Python environment with
pip install <path-to-repo-directory>You can include the -e flag to make an editable install; this means any changes you make to the rotundalocations
package will automatically update for all uses of the package installation.
The primary entrypoint for command-line use is the location-linking script installed along with the package.
To run it, you need to first specify arguments shared across all its subcommands, and then a subcommand and its specific
arguments. For example:
location-linking -o db -u joe <path-to-rotunda-data> <subcommand...>This is running location-linking on the documents described in <path-to-rotunda-data> using the database at db for
result storage and the username joe as an identifier for any additions to the database. These arguments are
only the required ones; see the help message printed with location-linking -h for more information.
For testing, you can use the public Revolutionary Networks dataset, which is in the correct format and contains metadata about a subset of the larger Rotunda collection. Please use that repository as a reference for the correct input document format.
Each existing subcommand is listed below, along with a brief description and usage guide.
Assign the documents in the provided dataset into clusters formed based on their datelines. The clustering algorithm used is Hierarchical Density-Based Clustering. To convert the datelines into vectors for the clustering algorithm, the script analyzes frequencies of adjacent letter pairs.
This subcommand does not take any arguments. Here is an example usage:
location-linking -o db -u joe <path-to-rotunda-data> clusterWithout the -f universal flag, the software will not attempt to cluster documents which have already been clustered.
Assign Geonames entities to clusters which are identified in the database. This contacts the Geonames search API.
This subcommand requires one argument, which is your Geonames username. Geonames uses your username to authenticate each request and rate limit users. Here is an example usage:
location-linking -o db -u joe <path-to-rotunda-data> geonames-clusters demo(Do not actually use the Geonames demo user!)
Without the -f universal flag, the software will not attempt to assign Geonames entities to clusters which have
already been assigned one.
Assign Geonames entities to Rotunda collections documents. This contacts the Geonames search API.
This subcommand requires one argument, which is your Geonames username. Geonames uses your username to authenticate each request and rate limit users. Here is an example usage:
location-linking -o db -u joe <path-to-rotunda-data> geonames-clusters demo(Do not actually use the Geonames demo user!)
Without the -f universal flag, the software will not attempt to assign Geonames entities to documents which have
already been assigned one.
Assign Wikidata items to clusters which are identified in the database. This contacts the Wikidata full text search API and the Wikidata Query Service.
This subcommand requires one argument, which is contact information that will be included in the software's user agent.
This is required by the Wikimedia Foundation by policy for all bots. You can provide an email (e.g., joe@example.org),
and/or a website (e.g., https://example.org/~joe). Alternatively, you can provide your Wikimedia Foundation
credentials in the form (<wikimedia project, e.g., wikipedia:en>; User:<username>). For example:
location-linking -o db -u joe <path-to-rotunda-data> wikidata-clusters "wikipedia:en; User:OrdinaryJoe"Assign Wikidata items to Rotunda collections documents. This contacts the Wikidata full text search API and the Wikidata Query Service.
This subcommand requires one argument, which is contact information that will be included in the software's user agent.
This is required by the Wikimedia Foundation by policy for all bots. You can provide an email (e.g., joe@example.org),
and/or a website (e.g., https://example.org/~joe). Alternatively, you can provide your Wikimedia Foundation
credentials in the form (<wikimedia project, e.g., wikipedia:en>; User:<username>). For example:
location-linking -o db -u joe <path-to-rotunda-data> wikidata-clusters "wikipedia:en; User:OrdinaryJoe"This project is licensed under the Apache 2.0 License.
Copyright © 2026, The Rector and Visitors of the University of Virginia
This software has been made possible in part by the National Endowment for the Humanities: Democracy demands wisdom. Any views, findings, conclusions, or recommendations expressed in this software and its associated documentation do not necessarily represent those of the National Endowment for the Humanities.
This software was developed in the course of a student internship at the University of Virginia. I am grateful for my supervisor, Patricia Searl, M.A., who provided me with this opportunity.