To search the User Guide, press Ctrl+f and enter a keyword.

1. Glossary

1.1. Agent String

In-place, in-context verbatim, character-by-character representations of one or more person and/or one or more organization. Example: "M. et Mme Jacques Brossard" as Verbatim Collector in a Collecting Event.

1.2. Geographic names

Names of any geographical or topographical feature of public or historical interest. A geographical name is a proper noun applied to a natural, man-made or cultural feature on Earth. A feature can have different names in one or several languages and the names may be provided, together with appropriate information on the feature, in different products like maps and gazetteers as well as respective services. Based on defintion from EU INSPIRE.

1.3. Georeferencing

Georeferencing means to associate an object with a position in physical space. Postion is most commonly represented using a coordinate reference system, which in turn can be related to a geodetic reference system such as WGS-84.

1.4. Person

A definitive, canonical representation of a human in the Agent module that has been ideally disambiguated through inclusion of an externally referenced identifier.

1.5. Reverse geocoding

Reverse geocoding is the process of converting a location as described by geographic coordinates (latitude, longitude) to a human-readable place name.

2. General Concepts

2.1. Group

Groups are used to define set of users for administration purpose (mostly permissions). They usually align with collections. A user can belong to more than 1 group.

Groups are also used to defined who owns an object. For example, an object in the object-store always belongs to a group. Objects can only have 1 owner.

2.2. Role

With the exception of Administrator, roles are always assigned per group.

Roles:
Administrator

DINA Administrator

Super User

Group administrator

User

Regular user

Guest

Similar to a regular user but with less permissions on destructive operations

Read-Only

No data alteration possible

2.3. Permissions

Permissions in DINA are strictly related to roles per the table below:

Table 1. Minimum role required for operation
Resource Create Update Delete

Material Sample

Guest

Guest

User

Controlled Vocabulary

Super User

Super User

Super User

Form Template

Object Owner

Object Owner

Object Owner

Object Store objects

Guest

Guest

Super User

Agent (person)

Guest

Super User

Super User

Technicals: Permissions are mostly Role-based access control combined with Discretionary access control with owner.

2.4. User

Users (when explicitly allowed) can access the system. What a user can and cannot do is based on the group(s)/permission(s). When using an external Identity Provider (e.g. ESAS) the user account must be linked to the Identity Provider account. Once done, the user will be able to use a third-party authentication (e.g. ESAS) to access the system.

2.5. Verbatim

DINA has some fields that are prefixed with the word "verbatim". Verbatim is defined as "in exactly the same words as were used originally". These fields are used to capture the data as originally represented for example on a label or in in expedition notes.

2.6. DINA Identifiers

All object in DINA are identified with UUID (universally unique identifier). While this type of identifier is not considered human-readable (123e4567-e89b-12d3-a456-426614174000) it has the property to be virtually universally unique (chances of duplicates are close enough to zero to be considered negligible). Objects can be uniquely identifed even outside the DINA system.

2.7. Barcode

Machine readable code output that would be obtained from a scanning gun. Can be used as another means of searching the database.

2.8. Date/Time

In the context of DINA, date/time can organized in 4 categories:

LocalDate

Local date represents a date, without time, that is local (no timezone information). Example: Date of employement

LocalDateTime

Local date/time represents a date, with time, that is local (no timezone information). Example: Physical store inauguration date/time

DateTime

Date/time that includes timezone information. Example: Exact date/time a record was created.

DateTimeOptionalTz

Date/time that may or may not include timezone information.

2.9. Form Template

Form templates are used to customize the user interface by allowing you to choose field visibility and default values. The user can then use them for data entry on a single page or through a split operation.

2.9.1. Visibility

The owner (the user who created the template) can always see/use its templates. Optionally, the template can be made available to an entire Group that the user has access to.

Allowing other users to see a group does not give them access to edit the form template, they are only able to use the form template.

2.9.2. Split Configuration

Split Configurations enable you to configure how Material Sample Splits are automatically named and under what conditions they can be used.

Condition Setup

The Condition controls when a split configuration can be used. Currently, the only supported Condition Type is Material Sample Type condition but multiple Material Sample Types can be configured.

A condition can be applied that this split configuration can only be used if the Material Sample being split from is a specific Material Sample Type.

Material Sample Name Generation

The Direct Parent Naming Strategy and Material Sample Type Naming Strategy are available to use as strategies.

When using the Material Sample Type strategy, you will need to define the Material Sample Type in the Material Sample Info data component.

Generation Options

Once you have configured the Strategy, you can choose how the sequence should be generated. Using a (Lowercase letters) and A (Uppercase letters) options will start the sequence at the beginning of the alphabet, before moving on to two-letter sequences starting with "AA", "AB", and so on.

2.10. Field extensions

Field extensions are fields with specific definitions that are defined by known standards. In order to add a specific field extension, a system administrator needs to provide a configuration file to the application.

2.11. Managed Attributes

Managed attributes are attributes that can be created and used by the users on-demand. They are usually used to track data that is not common enough to be captured in a regular field. A managed attribute can be of type integer, string, date or boolean.

2.12. Material Sample Attachements

Attachments refer to Object Store Component.

3. Collection Component

3.1. Assemblage

Mechanism used to group material samples according to a generic, administrative theme. Should not be confused with Project. Examples might include specimen books or exsiccatae in herbaria where there is a title and a description and possibly enhanced with Managed Attributes for additional metadata that depicts the group’s identity.

3.2. Association

3.2.1. Host Organism

Organism that is the host of the material-sample. Usualy mean that we have the host (collected/cultivated). Not to be confused with Host of the collecting-event where the host was observed but not collected.

3.3. Collection

A Collection represents the top entity that can contain material-sample. Top collections (or parent collections) generally represent a natural history collection or a laboratory. A collection can contain multiple sub-collection(s).

3.4. Collecting Event

Darwin Core defines "event" as : An action that occurs at some location during some time. (from DarwinCore). In a Collection Event, the action is the extraction from nature.

3.4.1. Collection Number

An identifier given to the event in the field at the time of collecting one or more samples. Often serves as a link between field notes and the Event.

Same as DarwinCore fieldNumber

3.4.2. Collector’s Number

An identifier given to the Occurrence, by the collector, at the time it was recorded. Often serves as a link between field notes and an Occurrence record, such as a specimen collector’s number.

Same as DarwinCore recordNumber

3.4.3. Collection Method

Method used during an Collecting Event. Examples: UV light trap, bottom traw

Similar to DarwinCore samplingProtocol.

3.4.4. Coordinate Uncertainty In Meters

The horizontal distance in meters from the given decimalLatitude and decimalLongitude describing the smallest circle containing the whole of the Location. (from Darwin Core)

3.4.5. Habitat

An environmental system which can sustain and allow the growth of an ecological population. (from Ontobee)

3.4.6. Host

Observed host of the material-sample at the time of the collecting-event.

3.4.7. Substrate

Observed surface on which an organism was collected and understood to have lived.

3.5. Determination

Determinations are attached to an Organism. There is always a primary determination defined. Determination history is preserved.

3.5.1. Effective Determination(s)

The effective determination refers to the first primary determination that can be found in the material-sample lineage. If a target Organism is defined, the effective determination will be restricted to it otherwise all the organism will be grouped to return the effective determinations.

3.5.2. Target Organism Primary Scientific Name

The scientific name (verbatim scientific name if absent) of the primary Determination of the target Organism. If there is no target organism, all scientifc names will be concatenated (pipe | separated).

3.6. Material Sample

Material Sample represents the main unit of work in DINA. It can be described as: A physical result of a sampling(or subsampling) event.

The material sample can be collected, cultivated, extracted and either preserved or destructively processed.

The concept encompasses the terms materialSample and materialSampleEntity from DarwinCore.

3.6.1. Material Sample Type

A Material Sample Type is a system-defined term that prescribes the downstream expectations and logic in how derivative (or child) Material Samples are to be interpreted and digitally managed. Fixed values include: Whole Organism, Culture Strain, Molecular Sample, Organism Part or Mixed Organisms.

3.6.2. Primary ID

Primary, preferably unique and human readable, identifier for the material-sample.

Best Practice: For reasons of reproducibility, data aggregation, interoperability, and to facilitate communications, newly assigned Primary ID should be universally unique. Including a collection code as a prefix to alphanumeric values will generally give a human-readable Primary ID this desired uniqueness such as on physical labels while also indicating formal ownership in accordance with institutional policies.

Non-unique identifiers are allowed but will require user to explicitly allow it. This should only be done for historical bookkeeping purposes.

3.6.3. Next Available Identifier

Unique Primary ID creation by system for a material by concatenating the associated Collection string with the lowest unused integer. Ticking off the box will block manual Primary ID entry.

3.6.4. Material Sample State

Represents the state of a material sample when its condition is negatively impacted. Fixed values include: destroyed, damaged, lost or decommissioned

3.7. Preparation

Preparation can either be for preservation or propagation purpose.

3.7.1. Preparation Type

A noun representing what is getting prepared.

(inspired by ABCD 3.0)

Examples: leg, tissues, DNA

3.7.2. Preparation Method

A noun representing the process used (the how) in preparing the material sample.

(inspired by ABCD 3.0)

Examples: culture, mechanical inoculation, dissection

3.7.3. Preservation Type

Description of the preservation type of the material sample.

Examples: Freeze-Dry (from ABCD 3.0)

3.7.4. Preparation Fixative

Solution that was applied to or in which the material sample is preserved. Examples: EtOH 95%, EtOH 75%, EtOH 70%, saline, glue

3.7.5. Preparation Materials

Additional, typically inert physical environments or objects in which or on which the organism in a material sample is stored. It does not express the state of the organism nor the fixatives used but rather the materials that allow the organism to be presented.

Examples: pinned, glass vial, plastic jar, glass jar, microscope slide, acid-free paper, sticky trap/card, Eppendorf tube

3.7.6. Preparation Substrate

Material on which the organism in the material sample is presented or grows. Examples: rock, log, agar

3.8. Organism

A particular organism or defined group of organisms considered to be taxonomically homogeneous. (from DarwinCore). Optionally, it is possible to define a target organism within a material sample.

3.9. Project

Project has a start and an end date. It usually links to the organizational definition of project where an objective, a scope, resources and deliverable are defined. A material sample can be linked to multiple projects.

3.10. Protocol

Predefined written procedural method in the design and implementation of experiments in natural sciences. (from Wikidata)

3.11. Split

The concept of a split represents the action of creating new material sample(s) from an existing material sample. The provenance of the new material sample(s) is preserved. For example, the action can be a dissection or fungal/bacterial propagation.

Split can be configured using a form template with a Split Configuration setup.

Limitation: The result of a split (called children) cannot have their own collecting event. Since the extraction from nature happened on the first material sample, children will inherit the one from the first parent.

3.11.1. Direct Parent Naming Strategy

Using that strategy, the generated children will get the next name available among the list of children of the direct parent.

ABC-01
|_ ABC-01-A
  |_ ABC-01-A-a
  |_ ABC-01-A-b
|_ ABC-01-B
  |_ ABC-01-B-a

Based on the structure above:

Table 2. Direct Parent Strategy examples
Split From Result

ABC-01

ABC-01-C

ABC-01-A

ABC-01-A-c

ABC-01-B

ABC-01-B-b

3.11.2. Material Sample Type Naming Strategy

Using that strategy, the generated children will get the next name available among the complete set of material sample of the same Material Sample Type in the entire lineage.

ABC-01 (Whole Organism)
|_ ABC-01-A (Culture Strain)
  |_ ABC-01-B
  |_ ABC-01-E
|_ ABC-01-C
  |_ ABC-01-D

Based on the structure above:

Table 3. Type Based Strategy examples
Split From Type Created Result

ABC-01

Culture Strain

ABC-01-F

ABC-01-A

Culture Strain

ABC-01-F

ABC-01-B

Molecular Extract

ABC-01-B-a

3.12. Restrictions

Restriction levels are regulations set by the Public Health Agency of Canada (PHAC) and the Canadian Food Inspection Agency (CFIA). Levels set, or restrictions remarks made will tag the material sample with the appropriate level or note. The “Restricted” button toggle is decoupled from the tags.

Risk groups(RG) are classifications defined by the PHAC based on a biologic’s inherent characteristics and its prevalence for pathogenicity, virulence, risk of spread and availability of effective treatment. The risk group directs the appropriate containment level required to safely handle the specimen and dictates standard operating procedures.

Notes made in the Restrictions Remarks section will have its own red alert box when viewing the material sample. Note that only a single box will be created for the restrictions remarks; a new line does not create a new box.

3.13. Scheduled Actions

Only for reporting and record keeping purposes. No alerts will be triggered automatically on assigned date. Multiple actions can exist.

4. Storage Component

Storage components follow a tree-like hierarchy, with each subsequent child storage unit created having the parent as its location.

For example, suppose a Room Storage Unit Type is to be created with name "Room 101" that exists as a place within a building and has a freezer within the room. The Building should be first created, and then the Room as a Add New Child Storage Unit. Once the room is created, Freezer storage unit type should be created as a Add New Child Storage Unit for the Room.

The Freezer will have location Building > Room.

Components that are created can be assigned as a child of another Storage Unit using the Add Existing Storage Unit button.

4.1. Storage Unit Type

Generic classification description for a storage object that is created. Used as a means of categorizing. A storage unit type can have the grid option meaning that it can store content using coordinates.

4.2. Storage Unit

Individual instance of a Storage Unit Type. For example, "Room 101" is a storage unit that has a storage unit type of Room.

5. Object Store Component

5.1. Metadata

Data about an object stored or represented in the object-store.

5.2. Derivative

Represents a derivative from a metadata object. Its lifecycle is directly attached to the metadata object meaning that if the metadata object is deleted the derivative will automatically be deleted. Derivatives are usualy a visual representation of the main object when the main object can’t be easily represented like raw formats. They are also used to store thumbnails.

5.3. File Upload

Represents a file uploaded to the object-store-api. The files are uniquely identified and available to attach metadata or derivative.

5.4. External Resource

External resources are represented in the object-store by a URL. No copy or storage of the file is available in the object-store but instead a link to the resource. This is mostly used to allow the object-store to point to a resource that could not be represented as a file (e.g. protocols.io) or that the level of protection required is higher than what the object-store can support.

6. Sequence Component

6.1. PCR Primer

Information about Primers used for amplification of a region on a targeted organism.

6.2. Thermocycler Profile

Used to track different amplification cycles and melting temperature programmed for each gene region and its associated primer pairs.

6.3. PcrBatch

Details of the PCR Master Mix used for gene amplification. PCRBatch will connect to Gene Region, PCR Primers and Thermocycler Profiles.

6.4. PcrReaction

6.5. NGS Index

Used to distinguish between different samples in a single sequencing run of Next-Generation Sequencing (NGS).

7. Workbook Upload

The Workbook Upload functionality can be used to quickly add some records to DINA. It should be used to add a small number of new records but it is not a mechanism designed to perform a data migration from another source. Migration should be done at the API level since a lot of coordination, validation and checks are necessary.

7.1. Limitations

  • Usage limited to material-sample and its relationships

  • The relationships should already exist in the system and can’t be created by the same Workbook with the exception of the followings:

  • No records can be updated using the Workbook Upload, records can only be added

7.2. Relationships

Relationships in Workbooks are expressed as textual representation unless a UUID (Universal Unique Identifier) is provided. The Workbook Upload will need to map the textual representation to existing concepts in the DINA system. With the exception of collecting-event, all records where the relationships are pointing must already exist before the import.

7.2.1. Text vs Concept

In a Workbook, textual representation are used to express concepts. For example, the text "Michael Jordan" could mean Michael Jordan or Michael Jordan or one of multiple people. There is no way to automatically pick the right person without having more information. A globally unique and persistent identifier exists and can be used to clearly identified a concept. For researchers ORCID can be used to identify researchers without any ambiguity. DINA generates DINA Identifiers for all of the data that it stores.

8.1. IN Operator

The IN operator can be used to run a query that would return all the elements from a comma separated list.

IN Operator
Figure 1. IN Operator

The previous query would return all records with primaryID is equal to REC-1, REC-2 or REC-4.

8.2. BETWEEN Operator

The BETWEEN operator can be used to run a query that would return all the elements that are within the upper and lower bound.

The operator is also available on some alphanumeric fields (when configured).

BETWEEN Operator
Figure 2. BETWEEN Operator

The previous query would return all records where the primaryID is greater or equals to REC-1 and less or equals to REC-9.

8.3. Global Search Syntax

This section explains the special characters you can use to refine your searches within the Global Search feature. These options allow you to construct more precise and targeted global searches, helping you find the information you need more effectively.

Operators:

  • + (AND): This operator requires all specified terms to be present in a record for it to be considered a match.

    • Example: apple + banana will only find records containing both "apple" and "banana".

  • | (OR): This operator includes records containing any of the specified terms in your search.

    • Example: apple | banana will find records containing either "apple" or "banana" or both.

  • - (NOT): This operator excludes records containing the following term.

    • Example: red -apple will find records containing "red" but not "apple".

Phrases and Wildcards:

  • " ": Enclosing terms in quotation marks instructs the search to look for the exact phrase as a whole.

    • Example: "red apple" will only find records containing the exact phrase "red apple".

  • *: Using an asterisk at the end of a term searches for words that start with that term.

    • Example: app* will find records containing "apple", "appliance", "application", etc.

Precedence and Grouping:

  • ( ): Use parentheses to group search terms and control the order of operations within your query. This allows you to create more complex expressions.

    • Example: (apple + banana) - orange will first find records containing "apple" or "banana" and then exclude records containing "orange" from that set.

Advanced Options:

  • ~#: This signifies edit distance. It allows for typos or variations in the search term with a maximum edit distance of #.

    • Example: color~1 might match records containing "color" or "colour" due to the edit distance of 1 allowed. It will also allow typos of 1 character like "coloir".

  • ~# after a phrase: This signifies word distance, which specifies the allowed distance (number of words) between terms within a phrase search.

    • Example: "red apple"~1 might match records containing "green apple" or "red strawberries" due to the word distance of 1 allowed.

Escaping Characters:

If you want to use any of the special characters listed above literally in your search query (e.g., searching for + itself), you can escape them with a backslash (\) before the character.