Merge pull request #467 from BioKIC/geothesaurus

[3.1] Add documentation for geographic thesaurus

content/portal_manager/geothes/_index.en.md

@@ -0,0 +1,24 @@
+---
+title: "Geographic Thesaurus"
+date: 2024-02-08
+lastmod: 2024-02-08
+authors: ["Katie Pearson"]
+editors: [""]
+draft: false
+weight: 30
+keywords: ["geography","geographic thesaurus","country","continent","state","province","county","municipality"]
+---
+
+For instructions on how to add geographic units to the geographic thesaurus, [click here](https://biokic.github.io/symbiota-docs/portal_manager/geothes/add/).
+
+For instructions on how to edit existing geographic units, [click here](https://biokic.github.io/symbiota-docs/portal_manager/geothes/edit/).
+
+The geographic thesaurus is a database structure that allows portal superadministrators to manage geographic units and their relationships (hierarchical and synonymous) in a Symbiota portal. All terms entered in the geographic thesaurus are given a numeric rank that corresponds to the level of the unit (e.g., country = 50) and a **parent unit** (unless the geographic unit is a "root" term). Each unit can have one to many children units and one to many synonyms.
+
+![Diagram of Geographic Thesaurus](/symbiota-docs/images/GeothesaurusModel.jpg)
+
+Managing geographic units in this way enables users to be able to perform more comprehensive searches. For example, rather than having to conduct separate searches for records in "United States" and "USA", the user can search one term, and all the records relating to the synonym term will also be returned.
+
+{{< notice note >}}
+  Only superadministrators have access to viewing, editing, and adding to the geographic thesaurus.
+{{</ notice >}}

content/portal_manager/geothes/add/_index.en.md

@@ -0,0 +1,37 @@
+---
+title: "Adding Geographic Units"
+date: 2024-02-08
+lastmod: 2024-02-08
+authors: ["Katie Pearson"]
+editors: [""]
+draft: false
+weight: 1
+keywords: ["geography","geographic thesaurus","country","continent","state","province","county","municipality"]
+---
+
+1. Use the Sitemap to navigate to the Geographic Thesaurus under "Administrative Functions (Super Admins only)".
+2. Click the plus icon to the right of the Root Terms title.
+3. Fill out the Add Geographic Unit box following the guidelines described below. Names in italics are required:
+
+      **_GeoUnit Name_**: the name of the geographic unit
+
+      **Abbreviation**: abbreviated version of the geographic unit name
+
+      **ISO2 Code**: the alpha-2 ISO code as described in the ISO international standard, if applicable
+
+      **ISO3 Code**: the alpha-3 ISO code as described in the ISO international standard, if applicable
+
+      **Numeric Code**: the three-digit country code defined in ISO 3166-1
+
+      **_Geography Rank_**: the type of geographic unit (select from dropdown menu)
+
+      **Notes**: any notes relating to the geographic unit
+
+      **Parent Term**: the term directly above the new geographic unit in a geographic hierarchy; for example, the parent term of the country "Canada" would be the continent "North America". If a parent term is not specified, the geographic unit will be designated as a root term (i.e., highest term in a hierarchy).
+
+      **Preferred Term**: if the term is a synonym of another term, select a geographic unit from this list that is the preferred name for this country, according to the portal. For example, "Deutschland" is a synonym of "Germany", but in a primarily English portal, "Germany" may be the preferred country name.
+
+      **Polygon**: a geographic polygon delineating the outline of this geographic unit, in WKT format. This field can be auto-populated using the [Geographic Harvester Tool](https://biokic.github.io/symbiota-docs/portal_manager/geothes/harvester/).
+
+4. Click the Add Unit button.
+5. To add children to the geographic unit, click the plus icon at the top of the "children" list and fill out the Add Geographic Unit box as above for that child taxon, selecting the desired parent term from the Parent Term dropdown list.

content/portal_manager/geothes/edit/_index.en.md

@@ -0,0 +1,25 @@
+---
+title: "Editing the Geographic Thesaurus"
+date: 2024-02-08
+lastmod: 2024-02-08
+authors: ["Katie Pearson"]
+editors: [""]
+draft: false
+weight: 5
+keywords: ["geography","geographic thesaurus","country","continent","state","province","county","municipality"]
+---
+
+1. Use the Sitemap to navigate to the Geographic Thesaurus under "Administrative Functions (Super Admins only)".
+2. If the geographic unit you are editing is a root term, select the term from the list on the resulting page. If the geographic unit is not a root term, use the Search Geographic Thesaurus box to search for your term.
+
+{{< notice note >}}
+  The search box will show a dropdown list of all terms matching your search term, along with the parent unit of your search term. Make sure you select the correct unit+parent unit combo!
+{{</ notice >}}
+
+3. To edit the values in the Geographic Unit box, click the pencil icon (highlighted below), make any edits, and click the Save Edits button. This is also where you can change the parent geographic unit for this unit (see Parent term field) and the preferred/accepted term for this unit (see Preferred term field).
+
+![Geographic Unit Editing Form](/symbiota-docs/images/Geothes_edit.PNG)
+
+4. To delete the term, click the Delete Geographic Unit button below the Geographic Unit box.
+5. To edit the children terms (i.e., terms beneath this unit in the hierarchy), view the list below the Geographic Unit box. To remove children from this geographic unit, click the name of the child term and edit its Parent term.
+6. To add a child term, click the plus icon at the top of the "children" list and follow [the instructions here](https://biokic.github.io/symbiota-docs/portal_manager/geothes/add/).

content/portal_manager/geothes/harvester/_index.en.md

@@ -0,0 +1,35 @@
+---
+title: "Geographic Harvester"
+date: 2024-02-08
+lastmod: 2024-02-29
+authors: ["Katie Pearson"]
+draft: false
+weight: 10
+keywords: ["geography","geographic thesaurus","country","continent","state","province","county","municipality"]
+---
+
+The Geographic Harvester tool can be used to automatically add geographic units and/or the polygons delineating the borders of geographic units, provided a corresponding geographic unit can be located in the [geoBoundaries API](https://www.geoboundaries.org/) (Runfola et al. 2020). This API includes polygons for many geographic unit ranks.
+
+To use this tool, use the Sitemap to navigate to the Geographic Thesaurus under "Administrative Functions (Super Admins only)" and click "Go to Geographic Harvester" at the top of the page.
+
+The resulting page will show you a list of all countries in the geoBoundaries API and their associated metadata.
+
+* The **In Database** field indicates whether that country exists in the geographic thesaurus.
+* The **Has Polygon** field indicates whether that country has a polygon loaded into your geographic thesaurus.
+* To view the polygon associated with the country, you can click the **IMG** link in the Preview Image column.
+
+![Geographic Harvester](/symbiota-docs/images/GeoHarvester.PNG)
+
+To import polygons associated with the countries and their lower geographic units, click on the name of the country. The resulting page will show you a list of geographic ranks associated with that country and their associated metadata. For example, the ADM0 rank corresponds to the country, and the ADM1 rank corresponds to the state/province in the U.S.
+* The **Database Count** field indicates how many geographic units at that rank are currently in your geographic thesaurus.
+* The **Geoboundaries County** field indicates how many geographic untis at that rank are found in the incoming geoBoundaries file.
+* To view the raw data associated with the geoBoundaries API call, click the link in the **Full Link** field.
+* To view the polygons associated with that geographic rank, click the **IMG** link in the Preview Image field.
+
+![Geographic Harvester Page 2](/symbiota-docs/images/GeoHarvesterRanks.PNG)
+
+Check the box next to the geographic ranks for which you would like to import polygons. Check the "Add geographical units if missing" box if you would like to import the geographic units themselves into your geographic thesaurus as well. Click the Add Boundaries button to import the selected polygon(s) and/or geographic units.
+
+The Symbiota Support Hub gratefully acknowledges the work of the geoBoundaries project, which is essential to the functioning of this tool:
+
+**Runfola, D. et al.** (2020) geoBoundaries: A global database of political administrative boundaries. PLoS ONE 15(4): e0231866. [https://doi.org/10.1371/journal.pone.0231866](https://doi.org/10.1371/journal.pone.0231866).