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.
- 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:
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.
(based on http://www.wikidata.org/entity/Q5824490)
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:
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:
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:
-
Collecting Event that is only linked to the new material-sample
-
-
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. Search
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.
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).
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.