Maps by MicheleTobias

Documentation

Recommedations & Disclaimer

Literature Mapper is an experimental plugin. Although the developers of Literature Mapper have made every effort to make a quality plugin that behaves as expected, they make no guarantees that the program will function as intended. We highly recommended that you back up your Zotero database before you alter it with Literature Mapper.

Download & Install

Literature Mapper is available as an experimental plugin in the QGIS Manage & Install Plugins interface. Once installed, you can find it on the Plugins Menu.

Alternatively, you may download development versions of Literature Mapper at the GitHub repository for the project and place it in your QGIS plugins folder. When you start QGIS, it should be available on the Installed Plugins menu of the Manage and Install Plugins tool (find this in the Plugins Menu).

Use

Start the Literature Mapper Plugin

To start the Literatue Mapper Plugin, click on the LiteratureMapper option in the Plugins menu. Next, click the icon in your toolbar or find the Literature Mapper icon on the Plugins Menu.

Interface 1: Access Keys

Literature Mapper works with an online Zotero Database. You can connect your local Zotero database to an online account. You will need to find your user ID, the collection ID for the collection of citations you would like to use with Literature Mapper, and your API key.

Your user ID and your API key can be found or created at https://www.zotero.org/settings/keys. The collection key can be found by navigating to the library in your online account (My Library tab --> click on the library name in the left navigation bar) and finding the alphanumeric character string at the end of the URL.

Enter each key into their respective text boxes - just the alphanumeric keys, no punctuation such as quotes - and click "ok". The program will check the keys you entered with Zotero. If the keys are recognized, the next window will open. If there is any error, a message bar will show at the top of the map canvas window. If you receive an error, check that you entered your keys correctly and check to see that Zotero's online system is functioning. You do not need to be logged into your Zotero Online account for Literature Mapper to work, but checking to see that it is available can rule out an error caused by Zotero not being online.

Interface 2: Enter Locations

In the mapping interface, the table should be populated with information from the Zotero collection you entered earlier. (You should not edit any column except the Geometry column. In future updates, only the Geometry column will be editable.)

Add Point Locations

To add a location to a record, click on the record you want to update. Click the Point button in the table, then click its location on the map canvas. You should see that the text in the Geometry column has been updated to look something like this: {"type": "Point", "coordinates": [-140.504592652, 37.1942567162]}. Add locations to as many records as you would like.

Add Multipoint Locations

Adding a multipoint is ideal for literature that has more than one point location associated with it, as is often the case with studies that compared multiple sampling locations. To add a multipoint location to a record, click the record you want to update. Next, click the Multipoint button in the table, then click the locations for this record on the map canvas.

Saving

When you are done, click the "Save to Zotero" button. Because the only method of saving your work is by saving changes to Zotero, you may want to save frequently as you work. Changes not saved to Zotero will not be saved in the case of a crash. Saving may take several minutes if you have many records. The program will alert you that it has finished saving with a banner at the top of the map canvas in the main QGIS window.

Virtual Shapefiles

On start up, the plugin will scan your Zotero database to look for locations you've previously entered. When it finds them, it sorts the locations into either a point or multipoint virtual shapefile. If you would like to keep these shapefiles, right click on the file in the Layers List, then select Save As. Currently, the shapefiles don't update in real time as you edit, although this is on the list of future upgrades. To referesh the shapefiles, you need to restart the plugin.

Updates in Version 0.3.3

Literature Mapper no longer overwrites the Extra field for each item, but creates a html-like tag structure and only edits inside the tag.

Planned Upgrades:

Automatic updating of the virtual shapefiles while editing.
Allow panning and zooming between the addition of points in a multipoint record.
Improve saving time.
Working with private collections.

Known Trouble Spots:

Issues are tracked on the GitHub repository's Issues tab. Here are some known issues with Literature Mapper that may cause you some trouble. We're working on these and encourage you to file other issues on the issue tracker.

We have had reports that Literature Mapper does not work well with collections created with Better BibTex. We would like more information about the behavior of Literature Mapper with this tool so we can fix the bugs.

Works Citing LiteratureMapper

Tobias, M.M. and A.I. Mandel. 2021. Literature Mapper: A QGIS Plugin for Georeferencing Citations in Zotero. Air, Soil and Water Research 14:1-8. Open Access.

Goldstein et al. 2018, Literature-based latitudinal distribution and possible range shifts of two US east coast dune grass species (Uniola paniculata and Ammophila breviligulata). PeerJ 6:e4932; DOI 10.7717/peerj.4932 Available from PeerJ.

Suggested Citation for Literature Maper

Tobias, M.M., and A.I. Mandel. 2021. Literature Mapper. Version 0.3.3. QGIS Plugin. https://github.com/MicheleTobias/LiteratureMapper/blob/master/literature_mapper.py

-or-