Specimen search

Last modified by Anniina Kuusijärvi on 2024/02/12 14:08

Page in Finnish: Näytehaku

The specimen search in Kotka is very versatlie. However, using it may be difficult at first. There is also a simplified version of the search. Here are instructions on how to use them. The search page can be found in https://kotka.luomus.fi/specimens/search (from Kotka menu Specimens > Search).

These instructions concern the search form as it was 10/2021.

Simple search

You can access the simple search form through the Query builder-button (marked with green in the picture below). You can search based on a few query fields by writing the search criteria on the correct fields. When you start writing on the fields, Kotka automatically offers you options based on the data that has already been saved into Kotka.

This search is an AND-type search, meaning that all search criteria are fulfilled by the returned specimens.

Versatile/advanced search

With the diverse search you can for example

  • Perform exact searches and word searches for all specimen data fields
  • Define AND-, OR- and NOT-search criteria
  • Perform combination, similarity and partial searches as well as other advanced searches
  • Compile statistics based on any specimen data fields
  • Organize specimens based on different specimen data fields
  • Export the search results in different Excel-formats or generate different kinds of labels

search_help.jpg

On the search form there are two fields where you can write the search criteria. After entering the criteria click the Search-button (marked with violet in the picture) or press enter. Clear all-button clears all search criteria.

Identifier search

You can write specific specimen identifiers or identifier ranges in short form on the upper identifier search field (the field shows instructions for the correct format for the search). In the search settings (gearwheel icon) there is one setting for the identifier search: Identifier as range -checkbox. If you have this checkbox checked, Kotka tries to interpret the given identifier as an identifier range. If you need to search by one identifier that contains a dash ( - ) and you don't want it to be interpreted as a range, uncheck the checkbox.

If you need to search by identifier range, where the identifiers contain non-numeric characters (letters etc.), omit all non-numeric characters from the identifiers. For example, if you need to search between identifiers "JA.H12-13" and "JA.HA12-17", write the search in the following format: "JA1213-1217" and keep identifier as range checked.

Data field search

On the lower search terms field you can write search terms that target all specimen data fields.

By default Kotka includes all specimens into the search result that have any of the search terms in any data field. If you wish to search with a phrase, use quotation marks.

  • Cap Verde(link) - Cap or Verde: 4731 results
  • "Cap Verde"(link) – Exact search term: 110 results
  • sahlberg(link) – returns specimens where "sahlberg" occurs for example as collector, identifier or in the taxon name

If you wish to target the search to a certain data field, start by writing the ”database name” of the field. Kotka will automatically offer you the correct field names. Then write down your search term after the colon inside the quotation marks that Kotka automatically provides.

  • det: "sahlberg"(link) – returns specimens with Sahlberg as the person who identified/determined the specimen

Kotka can also offer search terms based on terms that have already been recorded into a certain data field. For example, if you target the search to Det field and write sahlberg on the search field (inside the quotation marks), Kotka will offer you Sahlberg, J., Sahlberg, U. and Sahlberg (among others) as options.

If you wish to search for specimens that match several search criteria, click the AND-button (marked with pink in the picture above) after writing down one search term. Then start writing down a new search term. This way Kotka will return the specimens that match all terms. You can also type AND between the search terms.

  • municipality: "Espoo" AND leg: "Heikkinen, Mikko"(link) - specimens from Espoo and collected by Heikkinen, Mikko

If you wish to search for specimens that match any of the search terms, type OR between the terms.

  • municipality: "Espoo" OR leg: "Heikkinen, Mikko" (link) - specimens from Espoo or collected by Heikkinen, Mikko

If you wish to search for specimens that do not match a given search term, type NOT in front of it.

  • NOT municipality: "Helsinki"(link) – specimens from everywhere except Helsinki

Performing more versatile searches on the search form is explained at the end of these instructions.

Subspecimens and associated observations

Since the specimens in Kotka can include several subspecimens or associated observations/units, these are also shown in the search results. For example, a specimen with two species as associated specimens and three associated observations is shown in five rows in the results (and thus effects the number of results accordingly). These can be filtered out as follows:

If you only wish to see the specimens (without associated observations), add recordBasis: "Preserved Specimen" as a search criterion.

If you don't want the subspecimens/associated specimens or the associated observations to affect the number of results, add firstInDocument: "true" as a search criterion.

Note that also identifications are shown on their own rows in the search results, if "Only accepted" is not checked.

Additional functions

You can access additional functions with the buttons in the upper right corner of the search form (marked red in the picture):

Link-icon copies the current search terms and result settings (see below) to your clipboard as a link. You can save the link for yourself/your team or pass it to a colleague, for example. Note that the link might include spaces; it will not work, if the link is cut at the spaces for example when pasted to an e-mail-platform.

Question mark guides you through a short introduction of the search form (in Finnish currently, to be translated)

Gearwheel-icon gives access to the search settings. There you can adjust the following settings:

  • Filter options: which fields are shown in the statistics on the left side of the page (in alphabetical order). When you start typing a field name, Kotka suggests available filters.
  • Filter size: how many options are shown in the statistics (eg. 10 most common ones).
  • Result options: which fields are shown in the search results table (columns of the result table are in alphabetical order except for the identifier, that is always first). When you start typing a field name, Kotka suggests available result columns.
  • Identifier as range, see above in Identifier search.

The browser preserves these settings, so you don't have to set them again each time you use the same browser. These settings are also included in the search link, so if for example your colleague sends you a search link, it opens to you with the same settings your colleague used.

By clicking the column headers of the result table you can re-arrange the results.

By clicking the Specimens I've edited or created today-link you gain quick access to specimens you have recently recorded. You can also use this link as a basis for another search and adjust the dates in the search field, for example.

Search results

Each ”subspecimen” or unit is shown in the result table on its own row. If a specimen consists of one actual specimen and five associated observations, they are all shown on their own rows if all of them match the search terms.

If there is a reasonable amount of results (10 000 at the moment), blue buttons appear on the search form through which the results can be exported in different forms:

Export to Excel converts the results into an Excel-file. For this you can choose from different formats:

  • In Kotka specific format: a format compatible with Kotka. The specimen data can be edited in this format and then directly imported back (unless someone else has edited the specimens meanwhile in Kotka).
  • Simply export the results: The data fields that you have chosen in result options will be exported to Excel. This is useful for example for making reports.
  • Hertta format: a format used by Hertta-system. Useful when data is copied to Hertta (until this is automated through FinBIF).

More information on how to use excel exports and mass editing of data is found in section Excel exports and mass edit

Print labels: prints the specimen data onto labels, the type of which you can define. The labels are only printed for specimens, not for associated observations. Label PDF maximum is 500 labels. More information on specimen labels and Label designer: Labels

Filters

There are filters for the search results on the top left side of the search form (marked with yellow in the picture above).

  • Only accepted: focuses searches only to identifications that have been accepted and only presents accepted identifications in the results. Affects specimens that have multiple identifications. If left unchecked, and specimens have multiple identifications, all matching identifications are shown in the result table.
  • Only with picture: only returns specimens that have images attached
  • Only type specimens: only returns specimens that have been marked as type specimens
  • By location: by clicking the globe button you can perform a search with a map (point + radius). The search is targeted to specimens whose coordinates are understood by Kotka.
Filter facets

Some statistics of the search result fields are shown lower on the left side of the search form. The fields shown can be chosen through the Gearwheel icon (see above under additional functions). 

The statistics show the most common entries of the data fields. By clicking each row you can filter the results accordingly. To remove the filter click the red cross following the filter. The logic of these filters is best learned by trying out different things!

The statistics also show how many unique values there are in each field in the search results (number after a field header). Exact number of unique values is shown up to 10 000 and above that it is an estimate.

Versatile search criteria

AND-, OR- and NOT-searches can be combined by using brackets to determine which of them are related. These types of searches must be manually typed in, because Kotka doesn't automatically add the brackets.

  • leg: "Heikkinen, Mikko" AND (municipality: "Espoo" OR municipality: "Asikkala") (link) - 165 results, returns specimens collected by Mikko Heikkinen from Espoo and Asikkala 
  • (leg: "Heikkinen, Mikko" AND municipality: "Espoo") OR municipality: "Asikkala" (link) - 4264 results, returns specimens collected by Mikko Heikkinen from Espoo, plus all samples collected by anyone from Asikkala 
  • country: "Finland" AND NOT (municipality: "Helsinki" OR municipality: "Espoo") (link) - returns specimens from Finland, except from Helsinki and Espoo

A word can also be marked compulsory with a plus sign add and banned with a minus sign delete.

  • +mountain +forest -meadow -dry (link) - specimen data must have the words mountain and forest but can't have the words meadow or dry
  • mountain AND forest NOT (meadow OR dry) (link) - this is equivalent to the previous search

Similar words can be searched by leaving out the quotation marks around the search term and adding a tilde-key (~) after it (fuzzy search).

  • municipality: Helsinki~ (link) - returns specimens where municipality includes e.g. Helsingin or Helsinge (note that the search term is not surrounded with quotation marks)
  • municipality: Helsinki~ AND NOT municipality: "Helsinki" (link) - returns specimens where the name of the municipality is almost, but not exactly, Helsinki. This can be used e.g. for finding misspellings. 

A search term can be cut with an asterisk * and an unknown letter can be replaced with a question mark, as long as you leave out the quotation marks.

  • leg: ?ahlberg (link) - returns specimens where the collector is e.g. Sahlberg, Dahlberg or Wahlberg
  • leg: Sahlb* (link) - returns specimens where the collectors name begins with Sahlb

Accent marks won't be taken into account in the search, except with letters å, ä and ö.

  • country: "Sao Tome" (link) - returns also specimens with the country name São Tomé
  • municipality: "Aanekoski" (link) - does not return specimens from Äänekoski

Date fields can be turned into date interval searches. When searched with these fields, Kotka will automatically open a calendar where you can choose start and end dates and time of day. You can also leave the day undefined with an asterisk * .

  • dateCreated: [2015-09-28T00:00:00 TO 2015-10-04T00:00:00] (link)
  • dateBegin: [2015-01-01 TO *] (link) - returns specimens that have been collected 1.1.2015 or after

You can also search for samples that have or are missing a certain piece of information.

  • _exists_: "municipality" (link) - returns specimens where the municipality has been recorded
  • NOT _exists_: "municipality" (link) - returns specimens where the municipality hasn't been recorded (note that the previous search term _missing_: "" no longer works!)

With the pictureCount-field you can search for and compile statistics of picture counts. 

  • pictureCount: [4 TO *] (link) - returns specimens that have four or more pictures
  • pictureCount: "3" (link) - returns specimens with exactly three pictures

With the identificationCount -field you can search for and compile statistics of identification counts.

  • identificationCount: "0" (link) - returns specimens that don't have an identification element at all
  • identificationCount: [3 TO 4] (link) - returns specimens that have 3 or 4 identifications

The unitCount search field works the same way as pictureCount and identificationCount, and you can use it to search for and compile statistics about units.

There are some helpful search fields related to e.g. taxonomy, like the fields Taxa, Family, Synonyms and EndangeredStatus. See Handling taxonomy for more information.

Special characters can be searched from so called raw-fields:

  • taxon.raw: *\.* (link) - returns specimens that have a dot in the taxon name
  • taxon.raw: *\(* OR taxon.raw: *\)* OR taxon.raw: *\.* OR taxon.raw: *\?* OR taxon.raw: *\/* (link) - returns specimens that have brackets, dot, question mark or division mark in the taxon name

More instructions for versatile searches can be found in Elastic-search engine directions, section Query String syntax.