Linnaeus User Guide

www.linnaeus.me


Introduction

Console

Linnaeus runs in two windows. One of these is the main window which runs in Firefox. The other is a console window that will look like the image below. Please keep this console window open when using Linnaeus. Closing this window will cause Linnaeus to stop working. If the command prompt window ever closes while you are working with Linnaeus, the program has crashed and should be restarted. Error messages may also occasionally display in the command prompt window.




Database

All data in Linnaeus is stored in a database file. The database file is named "database.db". It is stored in a folder named "database" located in Linnaeus' root directory. Linnaeus reads from the "database.db" file in order to process its data. To open the database folder, simply click the Open Database Folder button in Linnaeus. If you ever need to restore your database file, simply copy your backed up database file and paste it into the "database" directory. Linnaeus provides a feature accessed under the "Options" menu called "Database Backup". This will save a copy of your database to your desktop in a folder named "Linnaeus Backup". You can rename your backup database files anything you wish. However, to load them into Linnaeus, they must be renamed "database.db" once inside Linnaeus' database folder.

Data stored within Linnaeus' database is case insensitive. This means that the words "Dragonfly", "DrAgOnFlY", "dragonfly", and "DRAGONFLY" would all return as results for a search for "dragonfly".

Warning:
It is important to backup your database. You could even back it up to more than one drive, preferably among more than one computer, and most preferably to the cloud. You can also create multiple backups of your database and give each file a different name based upon the date backed up: e.g., "linnaeus_backup_june_2017.db", "linnaeus_backup_october_2017.db", or some variation. Your database could be damaged by user error, an update, a dragonfly flying into your computer, a solar flare, a cosmic ray, space alien attack, etc. Please keep your database safe.

Hotkeys


Key(s) Commands
F1 Adds record to print queue
F5 Restarts the program and reloads the database
← Move back 1 record
Alt + ← Move back 100 records
Control + ← Move back 1000 records
→ Move forward 1 record
Alt + → Move forward 100 records
Control + → Move forward 1000 records
Alt + Left Click Move in the clicked direction 100 records
Control + Left Click Move in the clicked direction 1000 records
Left click Deletes clicked specimen card from print queue
Right click Toggles edit mode on/off on clicked card




User Interface

Form

Provides fields to input and edit data. Most fields are self explanatory, but the following are worth noting.

Collection Dates
When entering collection dates, use the form yyyy-mm-dd as this will enable proper sorting. Using a different format will not sort dates correctly and make searching for dates not work correctly.

Coordinates Approximate
When checked, appends the text [coordinates approximate] to the applicable printed card and encloses the coordinates data in the Data Format Tool within {}.

DNA Sample Taken
If checked, prints "DNA sample taken: ID: X" on the specimen card, where X is the record's ID number.

Genital Ligula Extruded
If checked, prints "genital ligula extruded" on the specimen card.

ID
The ID of records cannot be entered or edited. It is generated automatically and is a unique number that distinguishes each record. There will never be two records with the same ID.

Manuscript Name
If checked, the year of the "Author Date" field is replaced by "ms." on the specimen cards.

Original Name
If unchecked, the "Author" and "Author Date" fields will be enclosed in parentheses on the specimen cards.

Manual Sex Symbol
If checked, a dropdown menu will appear that allows the sex symbol of the current card to be manually selected. If unchecked, the current card's sex symbol will be selected automatically.

Species
If you enter a species name in the species field, then press enter, the fields "Genus", "Family", "Author", and "Author Date" of that species will automatically be generated in the appropriate fields.

Timestamp
The timestamp of each record is generated automatically when submitted to the database.


Displays the specimen cards to be printed at the bottom of the page. Also displays how many cards and pages will be printed. There are 5 cards per page. Cards can be removed by left clicking them. Cards can be edited by right clicking them. Once finished editing, right click the card again to exit edit mode. Removing or editing a card from the print queue will not effect the data saved in the database.


Record Count

The record count is located at the top of the page, just under the title. It displays the number of records being viewed. The number of records being viewed will change after a successful search to the number of search results. When exporting records, the number here determines how many records will be exported.


Species Select

If there exist multiple records with the same species name but different data for any of the fields "Family", "Genus", "Author", "Author Date", and "Original Name", the species select window will appear. Clicking one of the rows will populate the appropriate fields with the desired data.





Functionality


Add to Print Queue

Adds the current record to the print queue.


Clear Print Queue

Removes all specimen cards from the print queue.


Color Theme

Changes the color of the user interface.


Convert Coordinates

Converts GPS coordinates from one notation to the other. Both latitude and longitude are converted at once, so make sure to input both before converting, otherwise it will not work. The input of the system you want to convert to must be empty for conversion to work. The following images illustrate what will and will not work.


Incorrect
The following attempt to convert will fail because only the latitude has been entered.


Incorrect
The following attempt to convert will fail because only the longitude has been entered.


Incorrect
The following attempt to convert will fail because none of the fields are empty.


Correct
The following attempt to convert will succeed because both latitude and longitude are entered and the desired conversion fields are empty.


Correct
The following attempt to convert will succeed because both latitude and longitude are entered and the desired conversion fields are empty.



Database Backup

Creates a folder on the Desktop called "Linnaeus Backup" and saves a copy of your "database.db" file. This file contains all your specimen records and options.


Data Format Tool (DFT)

The Data Format Tool (DFT) allows records to be automatically formatted for insertion into scientific papers based upon user preference. The DFT does not read directly from the database. Instead, it reads exported data. To use the DFT, first perform a search for a particular set of records you wish to format and use in a paper. Then, once the search is successful and you are viewing only the records you want, export them. This will create a file called "exported_data.csv" in the "files" folder of this program. This folder can be accessed by using the "Open Files Folder" button. After the "exported_data.csv" file has been created, the DFT can be used. Renaming the file, or moving it to a different directory, will cause the DFT to fail.

The DFT will generate a .html file of the formatted data called "formatted_data.html" located in the "files" folder. It will also show a brief preview of the data at the bottom of the page in the preview area. The preview data places each record on a new line: the generated .html file does not. To use the DFT, insert the fields whose data you wish to display, in the desired order, and click the generate button. The fields may be formatted with punctuation as desired. If no data exists for a certain field, it will be left blank.


DFT: Presets

Presets allow for easy reuse of common data formats. To save a new preset, enter a preset name and format in the respective fields. Set the checkboxes to the desired values and then click "Save Preset". To load a preset, simply select it from the Preset dropdown menu. Presets can also be edited and deleted.


DFT: Options

Decimal Coordinates
If checked, displays coordinates in decimal form (e.g., 35.3816). If unchecked, displays coordinates in degree/minute/second form (e.g. 55° 45' 36" N).

Truncate Duplicates
If checked, a record will only display its field data if the data is different from the previous record. If unchecked, field data is always displayed.


DFT: Fields

In the DFT, several fields are combined into one. They are listed below.

Specimen
The fields "males", "females", "larvae", and "exuviae" are all combined into "Specimen". When you insert "Specimen" into a DFT query, the program will automatically insert the correct data based upon weather there are males, females, larvae, or exuviae in a record.

Coordinates
All geographic coordinate data is merged into the "Coordinates" field. The coordinates will appear in either degree/minute/second form for decimal form, depending on whether the "Decimal Coordinates" checkbox is checked.


DFT: Examples

Example 1
In the following DFT query, the desired format is: "Specimen (Coordinates, Elevation) Species [Author];". This means each record will be displayed in accordance to that format. Because the "Truncate Duplicates" checkbox is not checked, the data will print exactly as it occurs in the database. Since the "Decimal Coordinates" checkbox is checked, the coordinates field displays in decimal format.

Example 2
In the following DFT query, the desired format is the same. However, the checkbox options are different. "Decimal Coordinates" is unchecked, so the coordinates display in degree/minute/second format. Because the "Truncate Duplicates" checkbox is checked, consecutive records with duplicate data are prefaced with "same data but" and have their duplicate data hidden. This means that if a record shares duplicate data with a record before it, only the data that is different is displayed. If a record shares exactly the same data as the record before it, then "same data" is displayed. The following is important to note: "same data" does not mean two records are exact duplicates. It only means that the requested fields are the same (i.e., in this case, specimen, coordinates, elevation, species, and author). Also take note that in the third record, there is an empty pair of "[]". This is because if no data exists for a certain field, it will be left blank. In this case, the Author field. The empty "[]", or any other field can easily be removed in a text editor with find and replace.


Delete

Deletes the current record from the database.


Delete Duplicates

Deletes all duplicate records in the database. Duplicate records are defined as records that share identical data in all their fields except for the following two fields: ID and timestamp.


Edit

Edits the current record and saves it to the database. This does not create a new record; it simply amends an existing record.


Exit

Exits the program by closing both the command prompt window and Firefox.


Feet to Meters

Converts the current elevation value from feet to meters.


Export

Exports the records currently being viewed to the files folder. The number of records currently being viewed can be seen in the record count area near the top of the page. To export only specific records, first conduct a search. For example, suppose an entomologist has a database of 392 records. The entomologist wants to send some records to a friend, but not the entire database. The friend is only interested in the records from Germany, of which there are 5. To achieve this goal, a search must be conducted to find records whose value for the country field is "Germany".

Before the search
392 records are being viewed, which means all 392 would be exported.


After the search
5 records are being viewed; the search found 5 records, so only these 5 will be exported.


Import

Imports records into the database. The records must be stored in the files folder, which can be opened with the open files button. The records must be in the .csv format and named "exported_data.csv". If there is no file named "exported_data.csv" in the "files" folder, the import will fail. Records exported from this software can be imported by anyone else using this software. Simply place the exported_data.csv file into the files folder and then click the import button.


Mass Edit

With great power comes great responsibility.
Make sure to read this entire section before attempting to use the mass edit tool.
Edits all records in the database that match the filter criteria. Edited records are immediately returned to the user. Any changes made with Mass Edit will effect the entire database, not simply the specimen cards currently being viewed. This means that even if the database is searched and only 100 records are currently being viewed, the entire database is still effected by the mass edit. Multiple filters can be chained together for very specific mass edits. To edit a checkbox value, use "true" for checked values and "false" for unchecked values.

Example 1

Suppose an entomologist accidentally misspelled the country "Greece" as "Grease" and submitted 500 records to the database with this spelling. The following mass edit would successfully fix the issue.



Example 2

Suppose an entomologist took a trip to the United States to collect bees. The first day of collecting bees was spent in the state of California. After the trip, many records were submitted to the database. However, the entomologist forgot to specify which state the bees were collected from on the first day of the trip. Only the country was specified that day. The following mass edit would successfully fix the issue and add "California" as the state to the records whose country is "United States" and whose collection_date_1 is "2016-01-23".




New

Creates a new blank record. This new record is not saved to the database until it is submitted.


Next

Views the next record. Holding the Alt key while clicking this button will skip forward 100 records. Holding the Control key while clicking this button will skip forward 1,000 records. The hotkey for this command is the right arrow key →. The hotkey can be combined with Alt or Control.


Open Database Folder

Opens the database folder where the main database is saved. The database file is named "database.db". Any other filename will fail. Another file exists here called "sqlite3.exe" and it should not be moved, renamed, or deleted.


Open Files Folder

Opens the files folder. This folder is where all exported and formatted data is saved. Data to be imported must also be saved here. Exported data is saved here in the file "exported_data.csv". Formatted data from the Data Format Tool is saved here in the file "formatted_data.html".


Options

Opens the options panel and gives access to several features: database backup, color theme change, delete duplicates and update check.


Previous

Views the previous record. Holding the Alt key while clicking this button will skip back 100 records. Holding the Control key while clicking this button will skip back 1,000 records. The hotkey for this command is the left arrow key ←. The hotkey can be combined with Alt or Control.


Print

To print specimen cards, click the menu icon composed of three horizontal lines in the top right corner of the web browser.

Then click the "print" button. Next, click "page steup". The following settings are a good starting point:

  • Format & Options
    • Orientation: Portrait
    • Shrink to fit Page Width: checked
    • Print Background (colors and images): checked
  • Margins & Header/Footer
    • Margins: 0 on all sides
    • Headers & Footers: --blank--


Searches the database and, if a search if successful, retrieves all matching records. All searches are case insensitive. The number of records currently being viewed is visible at top of the screen in the record count. If a search is successful, the only records viewable are the search results. To reload all records, refresh the page. To search for a checkbox value, use "true" for checked values and "false" for unchecked values.

Search
Searches the database based upon a minimum of two criteria: a field, and a value. The left column allows a field to be selected. The right column is the value to search for in the specified field. Multiple fields with different values can be chained together for more specific searches. If the "Exact" checkbox is checked, only matches will return results. For example with the "Exact" checkbox checked, a search in the Country field for "land" will not return results because there is no country with the exact name "land". However, if the "Exact" checkbox is unchecked, "England", "Greenland", and "Finland" would return as search results since they each contain "land". Note that in either case, with the "Exact" checkbox checked or unchecked, searches are case insensitive.

Range Search
Searches a field in the database between a range of values.


Special Characters

Provides a list of extended characters. To use a character, select it from the drop down menu, then copy it and paste it where desired. The character is automatically highlighted to facilitate quick copying.


Submit

Submits the current record to the database. If a record is submitted that already exists, a duplicate will be created. This makes it easy to add multiple records to the database with very minor differences.


Update Check

Checks if there is an updated version of Linnaeus available for download. Linnaeus automatically checks for updates when started. To disable this feature, uncheck the "Check for updates on start" checkbox.


User Guide

Launches the user guide documentation.