This guide is intended as a reference to myself and any other user to explain the specifications of the Species software, how to use it and how to troubleshoot if things aren't working properly. Given that the software is currently in a state of partial completion, this guide is also. Items in red are things I need to update/fix in the software.
Sheet Input
If a required field is left blank and a substitute is not able to be generated, the entry will be excluded from the gallery and gallery totals, and an error message will be printed in the report; if a substitute is able to be generated, a warning message will document the change and the entry will still be included in the gallery. If a field is not required and has a value that is not accepted, a warning message will print, but the entry will still be included in the gallery.
File
This field gives the file name that will be appended to the image path as given in the configurations. It can include directories if necessary, but should not include the file extension (or period for extension).
Required: Yes
Accepted values: May not be null or unknown.
Ext. (Extension)
This field should include the extension of the image file to be used for the entry. It should not include a period. Extension is case sensitive and should match the case of the extension of the file to be used.
Required: No
Accepted values (case insensitive): "jpg", "jpeg", "gif", "png", "bmp"
Default assigned value if blank: Configurable; default configuration is "jpg" (Done, but need to make sure configurable value is one of the accepted values)
Unifying common name
This field is intended to serve as the common name that is used to refer to all entries for a species, regardless of what other common names or descriptors might be used for a subset of members of that species. For example, the domestic dog (Canis lupis familiaris) is a subspecies of the gray wolf (Canis lupus), the common name which more broadly and typically would refer to the parent species. As such, the Unifying common name for a domestic dog entry would be "Gray wolf", whereas the Differentiator would be "Domestic dog" and possibly additional information.
Required: Yes
Accepted values: May not be null or unknown.
Taxa
These columns comprise the bulk of the data and affect how each entry is sorted. Within the sheet, taxa are arranged from the highest and most generic (beginning with Domain) to the lowest and most specific (Other). Taxa from Domain to Genus are accounted for in on-page sorting. The Genus and Species values, if given, form the entry lines for each species. Values of the fields from Genus to Other affect how the entry's name is presented in the Colorbox display.
All values for these columns (with the exception of Other; see below) should be given without supplemental stylization (such as HTML italicizing, single quotes, or connecting terms such as "var.", "subg.", etc.) as this will be handled automatically. In-sheet stylization (italics, bold, text color) will not affect the presentation in the gallery.
Note: The Other column does not represent any official taxonomic rank. It is intended to serve as a catch-all for any additional information to be appended to the end of an entry's name in the Colorbox. Such information might include a locale, morph, or other unofficial designation. It is presented after all other values that form the species name without any stylization, so any desired decorations should be added. For example, the dairy cow morph of the swift woodlouse (Porcellio laevis) might be written as "Porcellio laevis 'Dairy Cow'." In this instance, the value for Other should be given as "'Dairy Cow'" (including single quotes).
Domain to Infratribe
If given a valid value, these taxa will print as headers before their respective entries.
Special functions:
- Parenthetical descriptors. The user may append a parenthetical descriptor of a taxon which is stripped/ignored under certain circumstances. The taxon and descriptor (for example, instead of entering simply "Canidae" in the Family field, "Canidae (dogs and allies)" may be used) should be formatted as "[Taxon value] ([Descriptor])". These descriptors should represent the only usage of parentheses in these fields. Parenthetical descriptors may be used in lower-level taxa for the user's own information, but any such instances will be stripped from the data before printing.
Genus to Other
These columns comprise the remaining taxa. They are treated the same as the taxa above, except that they do not affect the presence of headers in the main gallery. As such, the usage of parenthetical descriptors does not affect display (although they may still be used for the user's reference).
- Hybrid notation. There are three kinds of hybrid notations supported. All of them use the "/" character, and these instances should be the only ones in which that character is used in these fields. At the present time, notation for hybrids more complex than two parent species is not supported.
- Hybrids within the same genus. Where a hybrid's parent species share the same genus, the Genus field and all higher taxa should be filled out normally. The Species field should be formatted as "[species1]/[species2]". The binomial will then print as "Genus species1 × species2".
- Intergeneric hybrids. When the hybrid's parents do not share the same genus, both the Genus and Species fields should be formatted to incidate so. Where Parent 1 is Genus1 species1 and Parent 2 is Genus2 species2, the Genus field should be formatted as "[Genus1]/[Genus2]" and the species field as "[species1]/[species2]". The binomial will then print as "Genus1 species1 × Genus2 species2". Above the genus level, taxa should be given as null until the first common taxon between the two parent species.
- Nothotaxa. In cases where the user wishes to indicate a nothogenus or nothospecies, the value for the Genus or Species field (respectively) should begin a "/" character, followed by the taxon (with no space). For example, to indicate that Sorbopyrus auricularis belongs to a nothogenus, the Genus value for this entry should be given as "/Sorbopyrus", while the Species field should be filled out normally as "auricularis". Similarly, to indicate that the species Fragaria ananassa is a nothospecies, the Genus should be input normally as "Fragaria", while the Species value should be "/ananassa".
- Chimera notation. There are two kinds of chimera notations supported, and they operate almost identically to hybrid notation. Both use the "+" character, and these instances should be the only ones in which that character is used in these fields. At the present time, notation for chimeras across more than two genotypes is not supported.
- Chimeras with genotypes within the same genus. Where a chimera's genotypes share the same genus, the Genus field and all higher taxa should be filled out normally. The Species field should be formatted as "[species1]+[species2]". The binomial will then print as "Genus species1 + species2".
- Intergeneric genotypes. When the chimeras genotypes do not share the same genus, both Genus and Species should be formatted to incidate so. Where Genotype 1 is Genus1 species1 and Genotype 2 is Genus2 species2, Genus should be formatted as "[Genus1]+[Genus2]" and Species as "[species1]+[species2]". The binomial will then print as "Genus1 species1 × Genus2 species2". Above Genus, taxa should be given as null until the first common taxon between the two genotypes.
- Undetermined species notation. If the value for Species is given as "sp." or "sp" (case insensitive), it will be treated as unknown.
Special restrictions:
- If no valid Genus is given, no values below it are permitted (with the exception of Cultivar and Other). Any existing values in these fields will be changed to unknown.
- Similarly, if no valid Species is given, no values below it are permitted (with the exception of Cultivar and Other). Any existing values in these fields will be changed to unknown.
Required: Configurable; by default configuration, a valid value (including unknown or null) is required, and any blank fields will generate a warning. If configured to not be required, blank fields will be treated as null or unknown. This configuration setting allows the user to hide columns in the spreadsheet that they might find excessive (if, for example, the user prefers to only sort by a handful of core taxa) without being inundated with unhelpful warnings. This will result in less taxonomically accurate sorting, but simplifies input for the user.
Accepted values: Text values, null, unknown
Differentiator
The differentiator is intended to distinguish between entries where there are multiple represensatives of a species. Within a species, the differentiator value should be unique for each entry.
Required: No; when entry is not the sole representative of its species and no differentiator is provided, one will be assigned. If a differentiator value is not unique within its species, it will be modified to create a unique value.
Sex
This indicates the sex of the specimen(s) in the photo.
Required: No
Accepted values (case insensitive): "M", "F", "MF", "FM", "♂", "♀", "♂♀", "♀♂", "Hermaphrodite", "Gynandromorph", null, unknown
Comments
This field serves as a catch-all for additional information about the photograph or its subject(s). What that may entail is up to the user's discretion. Note that HTML can be used here to stylize text if needed (for example, to italicize a scientific name).
Required: No
Photo Information
Date
Date input is somewhat flexible. If numbers are separated by forward slashes, input will be interpreted as M/D/Y. If separated by hyphens, it will be interpreted as D-M-Y. If only two numbers are given (XX/XXXX, XX-XXXX, XXXX/XX, or XXXX-XX), input will be understood as M/Y; if a single four-digit number is given, it will print as-is. How dates are formatted in the Colorbox can be designated in the configurations. Additionally, configurations can allow a date to be pulled from the image metadata, if available, either in the absence of a valid date in the sheet data, or prioritized over it.
Required: No
Accepted values: Numerical date formats explained above
Country to Sublocation
These are fairly self-explanatory and straightforward. Note that for Sublocation, the value should begin with the appropriate preposition, for example "at the Houston Zoo" or "on the University of Houston main campus".
Special functions:
- "United States" omission. If configured to do so, when "United States" or another accepted variant is given in the Country field and there is also a value in the State field, the Country value will not print in the Colorbox display. Accepted variants include "United States of America", "United States", "USA", "U.S.A.", "US", and "U.S." (none case sensitive).
Required: No
Latitude and Longitude
These values, if both given, are used to generate configurable links in Google Maps. If only one value is given, the link will not print. The values should be given as the decimal coordinates (sexagesimal coordinates are not supported at this time).
Accepted values (Latitude): A decimal value from -90 to 90 (inclusive).
Accepted values (Longitude): A decimal value from -180 to 180 (inclusive).
Required: No
Scoring Data
This section is only intended to cover input standards for the data sheet. For details about the game rules and when to apply certain modifiers, etc., see the Rulebook.
Primary
This designation plays an important part in determining the starting point for scoring calculations. It should be used for an entry that will serve as the primary entry for its species, and only one entry within a species should be marked with the Primary value. Note that for entries that are not identified to the Species level, a Primary designation will not affect the entry score, as the unidentified status takes precedence in determining the base score.
Required: No; when entry is not the sole representative of its species and none is designated as the Primary, one will be assigned. If multiple entries within a species are designated as Primary, only one will be treated as such.
Accepted values: Any value other than unknown or null will result in this entry being treated as the Primary (with exceptions as noted above)
Score Modifiers (Columns A to M)
These fields indicate whether their respective score modifications should be applied. If blank, null or unknown, the modifier will not be applied to the entry. Any other value will result in the modifier's application, with the exception of some modifiers that cancel each other out.
A note on redundant score items: In circumstances where certain score items cancel each other out (for example, the "captivity" score modifier is not applied to entries also marked with the "dead" score modifier, and artifacts are not affected by multiplier values), it is still recommended that the user fill out all appropriate score items. Even if they are not calculated into the final score of an entry, future functionality may allow sorting or filtering entries by these criteria, and some designations may provide additional information about an entry subject.
Required: No
Multiplier
This field determines the value by which the entry score will be multiplied after factoring in base score and modifiers.
Required: Yes
Accepted values: "1", "1.4", "2", "4", "7", "10"
Omit
If this field is not blank and contains a value that is neither the null nor the unknown character, the entry will not print, and no further checks will be made in the data.
Required: No