Merge pull request #395 from BioKIC/material-sample

Material Sample documentation

content/editor/edit/fields/_index.en.md

@@ -1,25 +1,29 @@
 ---
 title: "Symbiota Data Fields"
 date: 2014-07-21
-lastmod: 2022-02-28
+lastmod: 2023-09-29
 draft: false
 authors: ["Ed Gilbert"]
-editors: ["Laura Rocha Prado","Katie Pearson"]
-keywords: ["edit","fields","data fields", "terms", "dwc terms"]
+editors: ["Laura Rocha Prado","Katie Pearson", "Lindsay Walker"]
+keywords: ["edit","fields","data fields", "terms", "dwc terms", "paleontology fields", "material sample fields"]
 ---
 
 The Symbiota data schema is strongly aligned to the <a href="https://www.tdwg.org/standards/dwc/" target="_blank" rel="noopener noreferrer">Darwin Core</a> data exchange standard. For more details, links to the Darwin Core definitions are supplied for each term. Learn more about Darwin Core terms in the following TDWG pages:
 - [TDWG - Darwin Core quick reference guide](https://dwc.tdwg.org/terms/)
 - [TDWG - List of Darwin Core terms](https://dwc.tdwg.org/list)
 
+ ### Table of Contents
+ - [Standard Fields](#standard-fields)
+ - [Material Sample Fields](#material-sample-fields)
+ - [Paleontology Fields](#paleontology-fields)
+
 {{< notice note >}}
   Since portals have the ability to customize the field names found on their data entry form, field names may differ from the core field definition and how it is mapped to Darwin Core export tools.
 {{</ notice >}}
 
 {{< button href="../../../documents/SymbiotaDataFields_202111.csv" text="Download full content as a CSV" >}}
 {{< button href="https://github.com/BioKIC/symbiota-docs/blob/master/static/documents/SymbiotaDataFields_202111.csv" text="See full content as a CSV" >}}
 
-
 ### Standard Fields
 
 {{< dwc-term id="catalogNumber" verbatim="Catalog Number" descr="The unique identifier (primary key) for the specimen record. This field should be used to store the barcode or the accession number (herbaria only). This field is enforced to be unique per collection" ex="WIS-L-0123456, ASU0012345, 12345" dwc="catalogNumber" >}}
@@ -160,9 +164,52 @@ See Darwin Core's <a href="http://rs.tdwg.org/dwc/terms/minimumDepthInMeters" ta
 
 {{< dwc-term id="duplicateQuantity" verbatim="Duplicate Quantity" descr="The number of duplicate specimens created. This will dictate the number of labels printed for specimen." ex="10" >}}
 
+### Material Sample Fields
+
+| ![Material Sample Module](/symbiota-docs/images/materialsampleblank.png) |
+|:--:|
+| Material Sample tab |
+
+{{< notice note >}}
+  Controlled vocabularies for Material Sample data fields are managed per portal, and the suggested examples provided below are derived from vocabularies used for the [NEON Biorepository](https://biorepo.neonscience.org/portal/). These vocabularies vary by portal, and modifications may require community input. Contact your Portal Administrator for more information.
+{{</ notice >}}
+
+{{< dwc-term id="sampleType" verbatim="Sample Type" descr="Controlled vocabulary defining the sample type, which is often anatomical in nature." ex="skull, liver, gastrointestinal tract, ectoparasite" dwc="" >}}
+
+{{< dwc-term id="catalogNumber" verbatim="Catalog Number / Barcode" descr="The unique identifier for the specimen occurrence from which the material sample was derived. This field can also be used to assign a unique catalog number to the sample itself." ex="WIS-L-0123456, ASU0012345" dwc="catalogNumber" >}}
+
+{{< dwc-term id="matSampleID" verbatim="Material Sample ID (GUID)" descr="An identifier for the material sample, which is a material entity that represents an entity of interest in whole or in part. In the absence of a persistent global unique identifier, construct one from a combination of identifiers in the record that will make this identifier globally unique." ex="06809dc5-f143-459a-be1a-6f03e63fc083" dwc="materialSampleID" >}}
+
+{{< dwc-term id="sampleCondition" verbatim="Condition" descr="Free text field to describe the physical condition of the sample. Use of a controlled vocabulary is recommended but not forced." ex="very poor, poor, fair, good, unknown" dwc="" >}}
+
+{{< dwc-term id="disposition" verbatim="Disposition" descr="Controlled vocabulary describing the current state of a sample with respect to its collection." ex="in collection, being processed, consumed, on loan" dwc="disposition" >}}
+
+{{< dwc-term id="preservationType" verbatim="Preservation type" descr="Controlled vocabulary defining the physical storage/preservation method of a sample." ex="dry, ethanol, frozen, pinned" dwc="" >}}
+
+{{< dwc-term id="preparationDate" verbatim="Preparation date" descr="The date of a sample's physical preparation. Dates in this field visually conform to MM/DD/YYYY formatting. Manual data entry into this field is validated using a calendar form." ex="08/01/2022" dwc="" >}}
+
+{{< dwc-term id="preparedByUid" verbatim="Prepared by" descr="Name of the individual who prepared a sample. The individual must have an user account in the portal to be recorded in this field." ex="Liao, Rosie; Johnston, Andrew" dwc="" >}}
+
+{{< dwc-term id="preparationDetails" verbatim="Preparation details" descr="Free text field to record notes providing more context about the physical preparation and condition of the sample." ex="upper and lower GI tract; kidney, left, whole; prepared with borax" dwc="" >}}
+
+{{< dwc-term id="individualCount" verbatim="Individual count" descr="The number of loanable objects associated with the sample, i.e. all pieces of the sample assigned to the same unique materialSampleID (see above)." ex="0, 1, 100" dwc="individualCount" >}}
+
+{{< dwc-term id="sampleSize" verbatim="Sample Size" descr="Free text field to quantify the sample beyond counted number of objects, e.g. dry weight." ex="200 uL" dwc="" >}}
+
+{{< dwc-term id="storageLocation" verbatim="Storage Location" descr="Free text field to describe a sample's permanent physical storage location." ex="Freezer 3; Oversize Storage; Cab011, Dwr002" dwc="" >}}
+
+{{< dwc-term id="remarks" verbatim="Remarks" descr="Free text field to provide additional notes, comments, and context unique to a sample that cannot be captured by other existing data fields. Limited to 250 characters." ex="genotype sampling; left jaw consumed in research; with post-cranial skeleton" dwc="" >}}
 
 ### Paleontology Fields
 
+| ![Paleo Module](/symbiota-docs/images/paleo_module.png) |
+|:--:|
+| Paleo Module on the Occurrence Data tab |
+
+{{< notice note >}}
+  Controlled vocabularies for the following data fields are managed per portal. Modifications to these values may require community discussion. Contact your Portal Administrator for more information.
+{{</ notice >}}
+
 <a id="eon"><b>Eon:</b></a> The longest geologic time intervals.
 Ex: Archean, Proterozoic, Phanerozoic
 See Darwin Core's <a href="https://dwc.tdwg.org/terms/#dwc:earliestEonOrLowestEonothem" target="_blank" rel="noopener noreferrer">earliestEonOrLowestEonothem</a>, <a href="https://dwc.tdwg.org/terms/#dwc:latestEonOrHighestEonothem" target="_blank" rel="noopener noreferrer">latestEonOrHighestEonothem</a>

content/editor/edit/materialsample/_index.en.md

@@ -0,0 +1,53 @@
+---
+title: "Material Samples"
+date: 2023-09-29
+draft: false
+authors: ["Lindsay Walker"]
+weight: 10
+keywords: ["Material Sample"]
+---
+
+{{< notice info >}}
+  This page describes how to add and edit material sample records associated with specimen occurrences. This tab will only be visible if it has been activated for your collection. Contact your Collection Administrator or Portal Manager to find out if this tab has been configured for your Symbiota portal.
+{{</ notice >}}
+
+| ![Material Sample Module](/symbiota-docs/images/materialsampleblank.png) |
+|:--:|
+| Material Sample tab within the Occurrence Editor |
+
+## Material Sample Data Fields
+
+Definitions for data fields displayed on the Material Sample tab are defined in the [Symbiota Data Fields](/symbiota-docs/editor/edit/fields/#material-sample-fields) documentation.
+
+## Adding/Editing Material Sample Records
+
+{{< notice note >}}
+ One specimen occurrence in a Symbiota portal can be associated with one or more material samples. 
+{{</ notice >}}
+
+### Adding Individual Material Samples
+
+| ![Material Sample Example](/symbiota-docs/images/materialsampleeditor.png) |
+|:--:|
+| Specimen occurrence with multiple associated material sample records as viewed from within the Occurrence Editor. [This example](https://biorepo.neonscience.org/portal/collections/individual/index.php?occid=277316) is from the NEON Biorepository's Symbiota portal. |
+
+**To add a new material sample to an existing catalog record:**
+
+1) Navigate to the Occurrence Editor: _My Profile > Occurrence Records > name of collection > Edit Existing Records_
+2) [Search](/symbiota-docs/editor/edit) for the record that the sample will be associated with. Open the record so that the Occurence Editor form appears.
+3) At the top of the form, select the Material Sample tab.
+4) Select the green plus sign (➕) to begin adding a new material sample.
+5) As you fill out the form, consult the [Symbiota definitions for Material Sample data fields](/symbiota-docs/editor/edit/fields/#material-sample-fields) if you are unfamiliar with these terms.
+6) Select the "Add Record" button to save the new material sample record.
+7) Repeat, starting at step 5, to add additional material sample records.
+
+{{< notice tip >}}
+  To **edit** existing material sample records, navigate to the Material Sample tab and select the pencil icon (✏️) to reopen the editable form.
+{{</ notice >}}
+
+### Batch Adding Material Samples
+
+At present, material sample records cannot be [batch uploaded](/symbiota-docs/coll_manager/upload/) from within a Symbiota portal's user interface, which is a task reserved for users with Administrator permissions. Collection Administrators are advised to contact the Symbiota Support Hub for assistance if this is desired. 
+
+### Downloading Material Samples
+Data entered into the Material Sample tab can be [downloaded](/symbiota-docs/editor/download/dwc/) from Symbiota as Darwin Core Archive or Symbiota data backup file. The output file will be named _materialSample.csv_.

content/editor/edit/tabs/_index.en.md

@@ -1,10 +1,10 @@
 ---
 title: "Record Editor Tabs"
 date: 2021-10-26
-lastmod: 2021-10-26
+lastmod: 2023-09-29
 draft: false
 authors: ["Katie Pearson"]
-editors: [""]
+editors: ["Lindsay Walker"]
 keywords: ["edit","tabs"]
 ---
 
@@ -16,12 +16,16 @@ Upon opening the Record Editor page, you will see 4-5 tabs, depending on your le
 
 ![Occurrence Editor Tabs](/symbiota-docs/images/editortabs.png)
 
-Occurrence Data – See [Symbiota Data Fields](https://biokic.github.io/symbiota-docs/editor/edit/fields/)
+**Occurrence Data** – See [Symbiota Data Fields](https://biokic.github.io/symbiota-docs/editor/edit/fields/)
 
-Determination History – where annotations are shown and can be entered. Annotations can also be batch uploaded from separate files. See [Annotations](https://biokic.github.io/symbiota-docs/editor/edit/annotations/)
+**Determination History** – where annotations are shown and can be entered. Annotations can also be batch uploaded from separate files. See [Annotations](https://biokic.github.io/symbiota-docs/editor/edit/annotations/)
 
-Images – provides information on image(s) associated with the record. See [Images](https://biokic.github.io/symbiota-docs/editor/images/)
+**Images** – provides information on image(s) associated with the record. See [Images](https://biokic.github.io/symbiota-docs/editor/images/)
 
-Linked Resources – allows linkage of checklists, duplicates, and genetic resources to the record
+**Material Sample** - allows for association of multiple material sample records per specimen occurrence. For this tab to be visible, it must be configured per portal and activated per collection. Contact your Collection Administrator for more information. See [Material Sample](https://biokic.github.io/symbiota-docs/editor/materialsample/)
 
-Admin – tracks changes made to Edit History, allows for transfers of specimens between collections, and provides a means for deleting an occurrence record. Only users with administrative permissions can view this tab
+**Linked Resources** – allows linkage of checklists, duplicates, and genetic resources to the record. See [Linking Records/Resources](https://biokic.github.io/symbiota-docs/editor/links/)
+
+**Traits** - allows for scoring of trait data. For this tab to be visible, it must be configured per portal and activated per collection. Contact your Collection Administrator for more information. See [Traits](https://biokic.github.io/symbiota-docs/editor/trait/)
+
+**Admin** – tracks changes made to Edit History, allows for transfers of specimens between collections, and provides a means for deleting an occurrence record. Only users with administrative permissions can view this tab