CINXE.COM

<!DOCTYPE html> <html lang="en" data-content_root="../"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Tutorials & Guides — World Historical Gazetteer 0.0.1 documentation</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=5ecbeea2" /> <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=12dfc556" /> <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="../_static/sphinx-dropdown.css?v=995e94df" /> <link rel="stylesheet" type="text/css" href="../_static/panels-bootstrap.min.css?v=21c0b90a" /> <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=88135fc7" /> <script src="../_static/documentation_options.js?v=d45e8c67"></script> <script src="../_static/doctools.js?v=9a2dae69"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../_static/copybutton.js?v=f281be69"></script> <link rel="icon" href="../_static/favicon.ico"/> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="next" title="Technical" href="400-Technical.html" /> <link rel="prev" title="Introduction" href="001-Introduction.html" /> <link rel="stylesheet" href="../_static/custom.css" type="text/css" /> </head><body> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="tutorials-guides"> <h1>Tutorials & Guides<a class="headerlink" href="#tutorials-guides" title="Link to this heading">¶</a></h1> <section id="choosing-an-upload-data-format-lpf-or-lp-tsv"> <h2>Choosing an upload data format: LPF or LP-TSV?<a class="headerlink" href="#choosing-an-upload-data-format-lpf-or-lp-tsv" title="Link to this heading">¶</a></h2> <p>World Historical Gazetteer supports uploads of both Linked Places format ( LPF; <a class="reference external" href="https://github.com/LinkedPasts/linked-places">v1.2.2 specification</a>) and its delimited file derivative, LP‑TSV, which is more useful for relatively simple data (<a class="reference external" href="https://github.com/LinkedPasts/linked-places/blob/master/tsv_0.5.md">v0.5 specification</a>). In both cases, some level of transformation has to happen between your source data and the chosen format. Both formats require that there be one record per place. The main distinctions can be summarized this way:</p> <ul class="simple"> <li><p>LPF is JSON-based and supports both temporal scoping and citations for individual place names, geometries, types, and relations within a single place record;</p></li> <li><p>LP-TSV is a delimited file format — either a spreadsheet or a text file in CSV or TSV format. Although it can handle multiple name variants and place types in a single column, it can have only one geometry per place, and citation is possible only for the principal name (‘title’).</p></li> </ul> <p>Choose LPF if:</p> <ul class="simple"> <li><p>You have multiple names, types, geometries, or relations for a single place that are temporally scoped; i.e. any of these attributes are associated in your data with a given year, timespan, or period—and you want that represented in your WHG representation;</p></li> <li><p>You wish to include citations per name, type, geometry, or timespan.</p></li> </ul> <p>Choose LP-TSV if:</p> <ul class="simple"> <li><p>You have a single year or timespan that applies to the entire record (start/end or attestation year).</p></li> <li><p>Your name variants and place types can be listed in a single column, e.g. this way: “name1;name2”</p></li> </ul> </section> <section id="preparing-data-for-upload"> <h2>Preparing data for upload<a class="headerlink" href="#preparing-data-for-upload" title="Link to this heading">¶</a></h2> <ul class="simple"> <li><p>The simple case</p></li> </ul> <p>If you have a list of distinct places with a name or names and basic attributes of the place, like coordinates, and place type in a spreadsheet, database table, etc., the task of preparing an upload file for WHG is straightforward. In almost all cases your format choice will be LP-TSV, and you can copy/paste columns from your file into WHG’s <a class="reference external" href="https://github.com/LinkedPasts/linked-places-format/raw/main/LP-TSV_template.xlsx">LP-TSV spreadsheet template</a>, as explained in the file itself. See also, “Quick Start” on the “<a class="reference external" href="https://whgazetteer.org/datasets/validate/">Upload dataset</a>” page.</p> <ul class="simple"> <li><p>The not so simple case: extracting places</p></li> </ul> <p>However, the data for most spatial historical projects is not only about places or locations, but principally about events or artifacts for which location is an important dimension.</p> <p>Both LPF and LP-TSV require that there be one record per place. But for many projects, a single place can have multiple rows in a spreadsheet, or multiple features in a shapefile—each recording for example a change in some attribute at a given time. For this reason, data often takes the form of one row per event, or artifact, or observation of some kind, with a column for place name, and/or for latitude and longitude. In this case location information is often repeated on each row that is about that event, or artifact, etc. <strong>The task is to extract the distinct places, into a separate places-only table or worksheet.</strong></p> <p>Conflating multiple place references to a single place record often requires disambiguation or normalization, with several kinds of decisions only the data creator can make, e.g.:</p> <ul class="simple"> <li><p>Do two different names actually refer to the same place?</p></li> <li><p>Are an archaeological site and a modern city with the same name the same place?</p></li> <li><p>If there are multiple name variants, which should be the primary “title” of the record?</p></li> <li><p>If some references are at the scale of settlement and others at the scale of county, should they be normalized to county</p></li> <li><p>for purposes of analysis?</p></li> <li><p>Linked Places format (LPF), a GeoJSON extension</p></li> </ul> <p>Apart from conflating multiple place references to a single place record, converting data from a delimited format like a spreadsheet or shapefile attribute table to the JSON-base LPF will almost certainly require a script—using e.g. Python or SQL if a database is involved. A how-to for this is beyond the scope of this document, but this <a class="reference external" href="https://csvjson.com/csv2json">CSV > JSON</a> tool demonstrates how this will look, and a web search will locate other tools that may help.</p> </section> <section id="explaining-the-whg-indexes"> <h2>Explaining the WHG Indexes<a class="headerlink" href="#explaining-the-whg-indexes" title="Link to this heading">¶</a></h2> <p>WHG maintains three high-speed indexes for use in the platform, “<strong>Wikidata+GeoNames</strong>”, the “<strong>WHG Union Index</strong>”, and the “<strong>Pub</strong>” index.</p> <section id="wikidata-geonames"> <h3>Wikidata+GeoNames<a class="headerlink" href="#wikidata-geonames" title="Link to this heading">¶</a></h3> <p>This index of over 13 million place records from Wikidata (3.6m) and GeoNames (10m) is used for initial intitial reconciliation of uploaded datasets, enabling their augmentation with</p> <ul class="simple"> <li><p>Coordinate geometry their records may be missing (a “geocoding” function”)</p></li> <li><p>Additional name variants</p></li> <li><p>Identifiers from additional gazetteer resources, including several national libraries, VIAF, and Getty’s Thesaurus of Geographic Names (TGN). This has the benefit of making user records significantly more linkable —within in WHG’s union index, and in other linked data contexts.</p></li> </ul> </section> <section id="whg-union-index"> <h3>WHG Union Index<a class="headerlink" href="#whg-union-index" title="Link to this heading">¶</a></h3> <p>The WHG Union Index is where individual records for the same or “closely matched” places coming from different datasets are linked. Search results privilege these linked sets or “clusters” of records, and present them in Place Portal pages like <a class="reference external" href="https://whgazetteer.org/places/12346428/portal/">this one</a> for Glasgow.</p> <p>Records from published datasets make their way into the union index by means of a second reconciliation step, following that for the Wikidata+Geonames index. This step is initiated by WHG editorial staff, and when complete the dataset is considered fully accessioned. See “Accessioning to the WHG Index” in <a class="reference internal" href="001-Introduction.html#individual-datasets"><span class="std std-ref">Individual datasets</span></a> for details.</p> </section> <section id="whg-pub-index"> <h3>WHG “Pub” index<a class="headerlink" href="#whg-pub-index" title="Link to this heading">¶</a></h3> <p>When a dataset has been reconciled to the Wikidata+Geonames index and published, it is automatically added to the “Pub” index so that its records can be discovered not only via browsing its publication page, but in search and via our Application Programming Interface (API). If and when the dataset is reconciled to the union index, its records are removed from “Pub,” as they are now linked where possible and will appear in Place Portal pages.</p> </section> </section> <section id="reviewing-reconciliation-results"> <h2>Reviewing reconciliation results<a class="headerlink" href="#reviewing-reconciliation-results" title="Link to this heading">¶</a></h2> <p>After a reconciliation task is run, the prospective matches to your records are presented for review. For each of your records that had one or more “hits,” those hit records from Wikidata and/or GeoNames are presented in a list on the right of the screen, with your record on the left. The dataset owner and any designated collaborators decide, for each of its records, whether one or more of the hits is a “close match.” Clicking the save button records those closeMatch/no match decisions and advances to the next record from the dataset. It is also possible to defer a decision, and placed in a separate queue that can be revisited, possibly by someone with more relevant expertise. It is also possible to add a note to the record for future reference.</p> <p><img alt="img.png" src="../_images/img.png" /></p> <p>The information displayed and options offered are explained below.</p> <ol class="arabic simple"> <li><p>The user-designated label of the current dataset</p></li> <li><p>Save / defer: After making match decisions (closeMatch or no match), click the Save button, If you want to defer a decision on this record, click ‘defer’ and it will go in a ‘deferred’ queue where it can be revisited. Optionally, add a note to help with the decision.</p></li> <li><p>The current “PASS.” If any automatic matches were made based on shared links, a PASS 0 is included, and these can be accepted en masse from the Linking screen. Otherwise, you will be stepped through potential matches from PASS 1 and then PASS 2, and in the case of Getty TGN, possibly PASS 3.</p></li> <li><p>It is possible to undo the last Save action; sometimes we click, then think better of it.</p></li> <li><p>The record from your dataset, as sent for matching. If it had associated geometry those will appear as green markers.</p></li> <li><p>Close match vs. no match. This is explained in depth in its own section below</p></li> <li><p>The globe icon indicates the potential match includes geometry. Hovering the mouse over the link will highlight it on the map.</p></li> </ol> <section id="what-does-closematch-mean"> <h3>What does closeMatch mean?<a class="headerlink" href="#what-does-closematch-mean" title="Link to this heading">¶</a></h3> <p>The meaning of <em>closeMatch</em> derives from the Simple Knowledge Organization System (<a class="reference external" href="https://www.w3.org/TR/2009/REC-skos-reference-20090818/">SKOS</a>) vocabulary, a widely used data model. Practically speaking, for WHG asserting a <code class="docutils literal notranslate"><span class="pre">closeMatch</span></code> serves as a linking “glue.” Specifically, records that share one or more common linked asserted as <code class="docutils literal notranslate"><span class="pre">closeMatch</span></code> are joined/linked in our “union index” and returned together in response to queries. For example, records for Abyssinia and Ethiopia share two <code class="docutils literal notranslate"><span class="pre">closeMatch</span></code> links, to a DBPedia record and a TGN record. Therefore, they appear together when searching for either Abyssinia or Ethiopia. We have determined there is not a clear enough distinction with SKOS:exactMatch to offer that choice.</p> <p>From the SKOS specification:</p> <ul class="simple"> <li><p><em>closeMatch</em>: “…(the) two concepts are sufficiently similar that they can be used interchangeably in some information retrieval applications”</p></li> <li><p><em>exactMatch</em>: “…a high degree of confidence that two concepts can be used interchangeably across a wide range of information retrieval applications.”</p></li> </ul> <p>Furthermore, <code class="docutils literal notranslate"><span class="pre">closeMatch</span></code> is a super-property of <code class="docutils literal notranslate"><span class="pre">exactMatch</span></code>; that is, every <code class="docutils literal notranslate"><span class="pre">exactMatch</span></code> is also a <code class="docutils literal notranslate"><span class="pre">closeMatch</span></code>. Remember, the purpose of the assertion is to ensure records that should intuitively appear together, do.</p> </section> </section> <section id="reviewing-accessioning-results"> <h2>Reviewing accessioning results<a class="headerlink" href="#reviewing-accessioning-results" title="Link to this heading">¶</a></h2> <p>Review of results for accessioning to the WHG index is similar to <a class="reference internal" href="#reviewing-reconciliation-results">review for reconciliation</a> but differs in the following ways:</p> <ol class="arabic simple"> <li><p>Instead of matching to individual records from Wikidata or GeoNames, you are deciding on matches to sets of records in the WHG union index — records that have been previously linked to each other. If you decide to match to a set, your record will be added to that set; in this case adding a third attestation for Lund.</p></li> </ol> <p><img alt="img_1.png" src="../_images/img_1.png" /></p> <ol class="arabic simple" start="2"> <li><p>If you decide there is no match and proceed, your record is indexed as a new first, or “seed”, for the place.</p></li> <li><p>When the accessioning task was run, all of your records that had no prospective matches were automatically indexed as new first (“seed”) records for those places.</p></li> </ol> </section> <section id="create-and-publish-a-place-collection"> <h2>Create and publish a Place Collection<a class="headerlink" href="#create-and-publish-a-place-collection" title="Link to this heading">¶</a></h2> <p>Place Collections in the WHG are annotated sets of place records from published datasets. Places can be added to a collection in three ways:</p> <ol class="arabic simple"> <li><p>From a Place Portal page, using the “Add to Collection” button.</p></li> <li><p>One or more from a published dataset’s Browse page, using the “Add to Collection” button.</p></li> </ol> <p><img alt="img_2.png" src="../_images/img_2.png" /></p> <ol class="arabic simple" start="3"> <li><p>By adding all of the places in one of your datasets — usually a small one created for the purpose.</p></li> </ol> <p><img alt="img_3.png" src="../_images/img_3.png" /></p> <p>Once places have been added, they can be annotated in the following way:</p> <ul class="simple"> <li><p>Create a set of “annotation keywords” for the collection — a custom vocabulary used to classify each place’s relation to the collection theme and to style map markers</p></li> </ul> <p><img alt="img_4.png" src="../_images/img_4.png" /></p> <ul class="simple"> <li><p>For each place, choose a relation keyword, and a note and optional date(s) and image — then save.</p></li> <li><p>If desired, drag and drop place “cards” to order them in a sequence</p></li> </ul> <p>At any time, add the following elements to the collection as a whole:</p> <ul class="simple"> <li><p>A title and description</p></li> <li><p>Collection keywords (these are distinct from annotation keywords)</p></li> <li><p>An image</p></li> <li><p>Upload an explanatory essay as a PDF file</p></li> <li><p>Up to three links to external web pages or resources</p></li> </ul> <p>Choose visualization options to control how temporal information will appear in the collection’s map and table displays (you can preview how your collection will display at any time). Options include:</p> <ul class="simple"> <li><p>Sort by sequence, start date, or end date?</p></li> <li><p>Include animated “ant trail” lines between places?</p></li> <li><p>Display a time “slider” filter or a sequence “player” control?</p></li> </ul> <p>If you have joined a collection group class or workshop, you have the option to submit it to the instructor or workshop leader for review. If the group has a gallery, once reviewed, the collection will appear there. Instructors have the option to nominate exceptional collections for the WHG Student Gallery.</p> <p><img alt="img_5.png" src="../_images/img_5.png" /></p> <p>If your collection is not associated with a class or workshop, you can request it be published in the site-wide <a class="reference external" href="https://whgazetteer.org/datasets/gallery/">WHG gallery</a> using the site contact form.</p> </section> <section id="create-and-publish-a-dataset-collection"> <h2>Create and publish a Dataset Collection<a class="headerlink" href="#create-and-publish-a-dataset-collection" title="Link to this heading">¶</a></h2> <p>A WHG Dataset Collection is a set of published, indexed datasets in WHG, whose place records have been linked with others for the same place where they occur. Its potential purposes and possibilities are outlined in the <a class="reference internal" href="001-Introduction.html#multiple-datasets"><span class="std std-ref">Multiple datasets</span></a> pathway section of this documentation.</p> <p>All datasets in a Dataset Collection must be published and fully accessioned — that is, indexed in the WHG union index. This is because the linking of records for the same place from multiple datasets occurs during the final indexing step. See “Accessioning to the WHG union index” in the <a class="reference internal" href="001-Introduction.html#individual-datasets"><span class="std std-ref">Individual datasets</span></a> section.</p> <p>The steps in creating a Dataset Collection are as follows:</p> <ol class="arabic simple"> <li><p>Click the + in that section of your My Data dashboard, then fill in the three required fields on the Create Dataset Collection form.</p></li> </ol> <p><img alt="img_6.png" src="../_images/img_6.png" /></p> <ol class="arabic simple" start="2"> <li><p>On the “Add and manage datasets” tab of Dataset Collection Builder screen that follows, you can begin adding datasets. The dropdown menu lists accessioned datasets that you own are are a designated collaborator on.</p></li> <li><p>You can add collaborators on the Collaborators tab. Co-owners are able to add datasets, and datasets they own will appear in the dropdown list of eligible datasets.</p></li> <li><p>You can preview the still private presentation of the collection at any time by clicking the “view” icon in the upper right.</p></li> </ol> <p><img alt="img_21.png" src="../_images/img_21.png" /></p> <ol class="arabic simple" start="5"> <li><p>Each Dataset Collection should have an accompanying essay and image prior to publication. You can also add up to three links to related external web resources.</p></li> <li><p>If a significant proportion of the collection’s records have meaningful date information, turn on the “Display temporal information” switch. This will ensure the collection table has start and end columns, and that there is a time “slider” filter overlay on the map.</p></li> <li><p>When you are ready to publish, click the “Request publication” button. This will notify WHG editorial staff that the collection is ready for review and publication. The timing of publication is up to its creators. Typically, datasets will be added over time, and it is sensible to publish the collection early, especially if it is a goal to attract addition datasets and collaborators.</p></li> </ol> </section> <section id="create-and-manage-a-collection-group-for-a-class-or-workshop"> <h2>Create and manage a Collection Group for a class or workshop<a class="headerlink" href="#create-and-manage-a-collection-group-for-a-class-or-workshop" title="Link to this heading">¶</a></h2> <p>The <strong>Collection Group</strong> feature in WHG is designed primarily for instructional scenarios, but can also be used for workshops. Any registered user can request “group leader” permissions, which allow them to create and manage a WHG Collection Group. This is a private space where students or workshop participants can create and share collections of places (WHG Place Collections), annotated with custom keywords, notes, dates, and images. The group leader can review submitted collections, and can nominate exceptional collections for inclusion in the WHG Student Gallery. Students or workshop participants join the group by entering an access key created and distributed by the instructor or workshop leader.</p> <p>The workflow in both cases is very similar:</p> <ul class="simple"> <li><p>Request group leader privileges using the site-wide contact form.</p></li> <li><p>On your “My Data” dashboard, a plus sign (+) appears in the “Collection Groups” box.</p></li> </ul> <p><img alt="img_7.png" src="../_images/img_7.png" /></p> <ul class="simple"> <li><p>Add a new Collection Group by filling the required fields in the form. Upon save, you are brought to the “Update Collection Group” screen where you will configure the group and manage submissions.</p></li> </ul> <p><img alt="img_8.png" src="../_images/img_8.png" /></p> <ol class="arabic simple"> <li><p>Edit title and description.</p></li> <li><p>Choose type (class or workshop), add keywords, start date and if applicable, due date.</p></li> <li><p>Upload a file (PDF format) with the course or workshop description, requirements, etc.</p></li> <li><p>Add up to 3 links to external web resources.</p></li> <li><p>Will this class/workshop have a gallery of completed works, visible to its members after completion? If so, are all submissions required to appear in it?</p></li> <li><p>Are collaborators permitted?</p></li> <li><p>Generate a group signup code and distribute it to students/participants, who join by entering the code on their own dashboard.</p></li> <li><p>As members join, they appear on this list</p></li> <li><p>For each submission, flag as ‘reviewed’ and if appropriate, nominated for the WHG Student Gallery.</p></li> </ol> <ul class="simple"> <li><p>When a student/participant enters the group code in their <em>My Data</em> dashboard, they get access to the PDF guide you have created, with guidelines for this particular exercise—the theme, or goals. <strong>NOTE: Technical instructions for creating a <a class="reference internal" href="001-Introduction.html#thematic-place-collections"><span class="std std-ref">Place Collection</span></a> are covered in site documentation and need not be included in this group guide.</strong></p></li> <li><p>As collections are submitted to the group, they are listed (9) and you can review them and nominate them for inclusion in the WHG Student Gallery (in development).</p></li> <li><p>Communication between instructor/leader and students/participants is left to normal email and/or course management software if applicable.</p></li> </ul> </section> </section> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="Main"> <div class="sphinxsidebarwrapper"> <p class="logo"><a href="../index.html"> <img class="logo" src="../_static/whg_logo.png" alt="Logo of World Historical Gazetteer"/> </a></p> <h1 class="logo"><a href="../index.html">World Historical Gazetteer</a></h1> <h3>Navigation</h3> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="001-Introduction.html">Introduction</a></li> <li class="toctree-l1"><a class="reference internal" href="001-Introduction.html#workbench-pathways">Workbench Pathways</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Tutorials & Guides</a><ul> <li class="toctree-l2"><a class="reference internal" href="#choosing-an-upload-data-format-lpf-or-lp-tsv">Choosing an upload data format: LPF or LP-TSV?</a></li> <li class="toctree-l2"><a class="reference internal" href="#preparing-data-for-upload">Preparing data for upload</a></li> <li class="toctree-l2"><a class="reference internal" href="#explaining-the-whg-indexes">Explaining the WHG Indexes</a><ul> <li class="toctree-l3"><a class="reference internal" href="#wikidata-geonames">Wikidata+GeoNames</a></li> <li class="toctree-l3"><a class="reference internal" href="#whg-union-index">WHG Union Index</a></li> <li class="toctree-l3"><a class="reference internal" href="#whg-pub-index">WHG “Pub” index</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#reviewing-reconciliation-results">Reviewing reconciliation results</a><ul> <li class="toctree-l3"><a class="reference internal" href="#what-does-closematch-mean">What does closeMatch mean?</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#reviewing-accessioning-results">Reviewing accessioning results</a></li> <li class="toctree-l2"><a class="reference internal" href="#create-and-publish-a-place-collection">Create and publish a Place Collection</a></li> <li class="toctree-l2"><a class="reference internal" href="#create-and-publish-a-dataset-collection">Create and publish a Dataset Collection</a></li> <li class="toctree-l2"><a class="reference internal" href="#create-and-manage-a-collection-group-for-a-class-or-workshop">Create and manage a Collection Group for a class or workshop</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="400-Technical.html">Technical</a></li> <li class="toctree-l1"><a class="reference internal" href="500-System.html">System Architecture</a></li> <li class="toctree-l1"><a class="reference internal" href="950-License.html">Licence</a></li> </ul> <div class="relations"> <h3>Related Topics</h3> <ul> <li><a href="../index.html">Documentation overview</a><ul> <li>Previous: <a href="001-Introduction.html" title="previous chapter">Introduction</a></li> <li>Next: <a href="400-Technical.html" title="next chapter">Technical</a></li> </ul></li> </ul> </div> <search id="searchbox" style="display: none" role="search"> <h3 id="searchlabel">Quick search</h3> <div class="searchformwrapper"> <form class="search" action="../search.html" method="get"> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> <input type="submit" value="Go" /> </form> </div> </search> <script>document.getElementById('searchbox').style.display = "block"</script> </div> </div> <div class="clearer"></div> </div> <div class="footer"> ©2024, World Historical Gazetteer. | Powered by <a href="https://www.sphinx-doc.org/">Sphinx 7.4.7</a> & <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a> | <a href="../_sources/content/100-Tutorials.md.txt" rel="nofollow">Page source</a> </div> </body> </html>