Coder Social home page Coder Social logo

taxonworks_doc's Introduction

TaxonWorks Documentation

Content

This repository documents TaxonWorks for both users and developers. It is the source for the TaxonWorks Documentation.

Content is being migrated from and/or also available from various other locations. You might also see:

Building

Use the development branch

Install packages.

npm install

Start a development server at http://localhost:8080. Changes to files will be detected automatically. Adding/removing files may require restart.

npm run docs:dev

While not needed because it is handled by continunous integration (CI) you can build the docs locally with:

npm run docs:build 

Docs are built using VuePress and served on Github pages.

Tired of reading all this stuff? Can't find what you are looking for? Talk to a human, Gitter.

taxonworks_doc's People

Contributors

arbolitoloco avatar debpaul avatar hhopkins77 avatar jlpereira avatar jrflood avatar kandakoj avatar locodelassembly avatar mjy avatar proceps avatar tmcelrath avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

taxonworks_doc's Issues

Getting Started in TaxonWorks

Following text copied from TryTaxonworks.docx with some modifications:

Getting Started in TaxonWorks

Please read the sandbox guidelines:
([http://wiki.taxonworks.org/index.php/Sandbox]).

Your administrator will provide you with the specific sandbox URL you will need to use.

Your username is your email. You will need to request a password change to logon. Check your email after you do for instructions on updating your password.

We do our best to maintain users across sandbox updates, however your account may be wiped. If you cannot request a new password, request a new sandbox account.

Remember, some aspects of what you see are in early development in terms of the user interface (UI) and user experience (UX).

• The quickest way to get other feedback is to contact us on the TaxonWorks Gitter channel: [https://gitter.im/SpeciesFileGroup/taxonworks].
• Features seen at [https://twitter.com/TaxonWorks] may not be in the sandbox.
• We would love to hear from you: See [https://github.com/SpeciesFileGroup/taxonworks_doc/blob/master/CONTRIBUTING.md].

You may be flagged as an administrator. Administrators can do everything in the workbench.

If you are flagged as an administrator ("Adminstration" link visible on top right):
• Feel free to add users to the sandbox through the "administrator" link. If you do, please provide this text to them.
• Feel free to add yourself to projects that are currently not visible to you. The route to do this is not yet optimized, but you can do this (click "links"):

"Administration" (top right) ->
"Projects overview" (on left) ->
"List" ->
Double click a row ->
"Add project member"

As a developer I need a top nav outline

Left:

  • [full logo] Docs

Floated right, left to right

  • [Guide] { guide/README.md, submenu is level 2 subheaders in left menu of guide }
  • [Develop] { guide/README.md, submenu is level 2 subheaders in left menu of develop }
  • [Use TaxonWorks] { guide/start_a_project.md }
  • [Cite] { about/citing.md }
  • [API] { guide/api.md }
  • [Report bug] { guide/bug_reports.md ? # may move, but here for now }
  • [Contact] {about/contact.md }
  • [Languages] { see https://v2.vuepress.vuejs.org/guide/i18n.html#theme-i18n-config }
  • [Github {submenu: Docs (this repo), Code (taxonworks repo), API (taxonworks_api repo), Install (install taxonworks repo) }
  • [Darkmode toggle (default lightmode)
  • [Search]

Clarification - relating subgenera

Currently, there is a soft validation warning for both a genus and its child subgenus if the taxon is nominotypical (e.g. Rhizophagus subgenus Rhizophagus and genus Rhizophagus), that shows up even if the parent genus and the child are identical in every way.

The message is "The original genus does not match with the original genus of coordinated genus" (for subgenus) and "The original genus does not match with the original genus of coordinated subgenus" (for genus).

Basically, is the "method" for relationshipping subgenera to create a clone of the genus exactly, just with a parent one level down? Or is there something we need to change to make that Soft Validation go away?

Examples:
Genus:
image

Subgenus:
image

Describe Family Group name relationships in manual

@proceps can you write up how we handle this in the manual here- https://github.com/SpeciesFileGroup/taxonworks_doc/blob/master/manuals/NOMENCLATURE_BASICS.md#family-group-names

"In the same way you have a module just to say if a nomen was originally a genus or a subgenus, you could create another module for families and their coordinate categories.
Many times a family is created as a tribe, subfamily or vice-versa and this should be reflected in a catalog."

Paper for BASIC_ARTICLE_PARSING.md Exercise is not open acess

For the BASIC_ARTICLE_PARSING.md the paper being used in the exercise is only available with log in and journal subscription. Perhaps consider updating this example with an alternative paper that is open access? Or is there a reason you would not want that? (Note the cite says "open access" for this paper, but clicking on the DOI or PDF link produces no result).

Describe preferred mechanism for handling aberations.

@proceps can you please answer Donald's question in the "Nomenclature basics" manual in this repo?

Donald Hobern writes:

For context, I have one that needs to be included, because it has become part of a messed-up synonymy based on a misreading of the original French text: https://gallica.bnf.fr/ark:/12148/bpt6k55313167/f220.image. Here is what I now have in TaxonWorks: https://sfg.taxonworks.org/tasks/nomenclature/browse/28598. Jourheuille named Alucita huebneri ab. cartereaui, which Gielis and others have misread as an aberration of A. hexadactyla and which now appears in Fauna Europaea and elsewhere as a (never used in this form) heterotypic synonym Alucita cartereaui. I've done what I can to clean up the mess (although I haven't done anything about Jourheuille's assertion that Hübner misapplied the name Alucita hexadactyla).

I've ended up entering Alucita huebneri ab. cartereaui as Alucita huebneri f. cartereaui, which incorrectly raises it to a formal infrasubspecific rank, but I could see no structured way to present an aberration name. Does TaxonWorks give me a way to do this?

Understanding Combinations

Understanding Combinations

This is version 0.0.1. All changes beyond grammar will result in an increment. Higher level increments reflect larger changes that may reflect new ways of doing things, or differences in user interfaces, etc.

You can ask for help and clarification live in person on Gitter!

Overview

This is more of an overview than an exercise.

Exercise target audience

Users who are asking questions about how Combinations are represented in the data model.

Manual goals

The goals are to describe:

  • The basic Combination model
  • How data are represented in the underlying tables

At the end of the exercise you should:

  • Download raw data and understand how the relations among IDs are setup

Assumptions

  • We assume that you have used the New taxon name task relatively extensively, and understand how to add original combinations therein.
  • We assume that you have used the New Combination task, and have entered multiple records using it.
  • We assume that you are interested in the underlying models of the data.

Related exercises

Manual

The Combination model

Asside from the documentation here the Combination model and the Nomenclatural concepts overview are useful references.

Combinations are a subclass of TaxonName with no name

Combinations are a subclass of TaxonName that have no name field filled out. They are "anonymous" in this sense. Their cached values are built through the values referenced through the taxon name relationships that link to this name. For example, if a combination has 3 parts, then there is one name linked to three individual names via three taxon name relationships. We use the id of the combination as the object id of the triple stored in the taxon name relationship.

The parent id of a Combination

The parent ID of a Combination is automatically set to the id of the parent of the highest ranked protonym in the Combination.

Original combinations are not Combinations

For various reasons that might ultimately change "original combinations" are not Combinations (upper case) in TaxonWorks. They are created by a special set of relationships unique to "original" that are applied between protonyms. There is no "anonymous" TaxonName that groups these original combinations, rather it is the protonym in question that is linked to.

Wrapping up

  • Remember that each Combination is a unique combination of relationships among protonyms.
  • Protonym records remain untouched.

People manual

This template is an experiment in the works, feel free to modify/propose changes.

People and AgentStrings

This is version 0.0.1. All changes beyond grammar will result in an increment. Higher level increments reflect larger changes that may reflect new ways of doing things, or differences in user interfaces, etc.

You can ask for help and clarification live in person on Gitter!

Overview

This is a brief manual on curating People and references to people ("AgentStrings", i.e. data not yet formalized to People instances) in TaxonWorks.

Exercise target audience

Data curators.

Exercise goals

The goals are to describe:

  • Describe input patterns for common name variants
  • Describe mechanisms to add identifiers to people
  • Point to (but not fully describe) tools in TaxonWorks that facilitate the curation of People
  • Describe caveats for how People are rendered when displayed in various scenarios (e.g. Citations, Citation lists, as Taxon Name authors, etc.)
  • Describe how to link your user account to your representation as People data

At the end of the exercise you should:

  • Enter names for People like "Simon van Noort", "<TODO d', l', le, ben-> alternates
  • Understand how to add alternate values (character encodings, abbreviations, etc.) to People
  • Add ORCID ids (and other identifers) to people
  • Add an ORCID id to your User account (i.e. link yourself to your representation as a Person data element)

Assumptions

  • You have a User account in a TaxonWorks instance

Gotchas

  • TaxonWorks is only officially supported on Firefox and Chrome.

Tips

  • Tip 1
  • Tip 2
  • Tip 3

Related exercises

  • Related exercise 1 (link to other manual)

Exercise

Syntax

  • In the exercise bulleted points are actions you should take, non-bulleted tasks are comments or guiding questions.
  • Highlighted words refer to text or elements in the application, for example button or field names.
  • "Quoted words" are literal values to be input or noticed

People names

We acknowledge that globally the names of people follow many different patterns and idiosyncracies and that the present model employed in TaxonWorks is decidely Western/European scientific, this reflects the available libraries for things like parsing names, modelling sources, and rendering citation lists. This clear bias obviously isn't optimal. While we can not re-write large code-libraries that we depend on (e.g. CSL rendering, BibTeX standards), we can and do provide mechanisms (e.g. alternate values, translations, etc.) that can start to faciliate a more global perspective on how to represent the names of People.

It is important to remember, from a data modelling perspective, that a name is not the same as the Person. This is another way of saying, "your name matters to nobody but yourself, you matter to everyone".

Subsection title (1a)

Section title 2

...

Section title 3

...

Wrapping up

Reminder of what was taught/learned.

Addendum

Addendum topic 1

As a videographer I want ideas/storyboarding for describing the Matrix functionality

  • Matrices in TaxonWorks: Background, concepts, role
    • Filter to Matrix related tasks/data
    • The models
    • Related data
  • Descriptors I - Basics
  • Descriptors II - Extended options
  • Descriptors III - Sequence descriptors
  • Creating a matrix I - Basic rows and columns
  • Creating a matrix II - Advanced options
    • Dynamic rows and columns
  • The matrix row coder - I basics
  • The matrix row coder - II Annotations - Citing, Attaching Images, Confidence levels and more
  • Viewing and exporting matrices
  • The matrix hub - all your matrices
  • The matrix dashboard - statistics
  • Image matrices
  • Interactive keys (perhaps I and II)
  • Workflow and Integration tips
    • Modals that auto-add matrix related content
    • Pinboard

VSCode basic setup

Write a basic documentation of the essential plugins and configuration for vscode.

DwC-A Import Manual

This template is an experiment in the works, feel free to modify/propose changes.

DwC-A Importer

This is version 0.0.1. All changes beyond grammar will result in an increment. Higher level increments reflect larger changes that may reflect new ways of doing things, or differences in user interfaces, etc.

You can ask for help and clarification live in person on Gitter!

Overview

Describe what's going on here.

Exercise target audience

Describe audience.

Exercise goals

The goals are to describe:

  • The import process and approach, particularly when records are matched versus when they are created anew.
  • What fields are possible to import, and where they map to in TaxonWorks

At the end of the exercise you should:

  • Skill 1
  • Know where to look in TaxonWorks for the values you imported.
  • Skill 3

Assumptions

  • We assume you have the following cards on your hub Favorites tab:
    • Tasks
      • Card 1
    • Data
      • Card 1
      • Card 2

Gotchas

  • TaxonWorks is only officially supported on Firefox and Chrome.

Tips

  • Tip 1
  • Tip 2
  • Tip 3

Related exercises

  • Related exercise 1 (link to other manual)

Exercise

Syntax

  • In the exercise bulleted points are actions you should take, non-bulleted tasks are comments or guiding questions.
  • Highlighted words refer to text or elements in the application, for example button or field names.
  • "Quoted words" are literal values to be input or noticed

Section title 1

Subsection title (1a)

Section title 2

...

Section title 3

...

Section title N - OTU vs. TaxonNames

Within TaxonWorks informal names are not TaxonNames (they are not intended to be governed by a rule of nomenclature), they are OTU names. Within the import the following is how data are mapped to an Otu#name vs. a TaxonName#name:

  • TODO: @LocoDelAssembly when/how does speciesEpithet(?) map to OTU#name? (I'll look at code too)

Wrapping up

Reminder of what was taught/learned.

Addendum

Addendum topic 1

SOP/Best practices - representing family group name relationships

As a curator I want to represent ICZN family group names. Describe how to:

  • Create a protonym representing the form of the original family group name, as it was made available.
  • Relate that original protonym to a subsequent protonym that is the current family group name.
  • Relate any family-group protonym to higher taxon in "source classified as", i.e. historical context

Clarify soft validation triggers for original combinations of species in subgenera

Not clarified here:
https://github.com/SpeciesFileGroup/taxonworks_doc/blob/master/manuals/NOMENCLATURE_BASICS.md

Example:

  1. Monotoma bicolor is described in 1800 in genus Monotoma.
  2. 1900 someone creates subgenus of Monotoma, Monotoma (Gyrocecis)
  3. New "combination" is now Monotoma (Monotoma) bicolor.
  4. When creating prononym in TW, what names do I put in "Original Combination" fields?

Right now, only way to get soft validation (of: "Original Combination: Relationship should move from genus Monotoma to subgenus Monotoma”) to disappear is by placing the subgenus name "Monotoma" in the genus rank in Original Combination.
Example:
image

Is this correct?

Pinboard Cheatsheet

A cheatsheet describing the functionality linked to and derived from using the pinboard?

Importing to TaxonWorks

in progress

Importing to TaxonWorks

This is version 0.0.1. All changes beyond grammar will result in an increment. Higher level increments reflect larger changes that may reflect new ways of doing things, or differences in user interfaces, etc.

You can ask for help and clarification live in person on Gitter!

Overview

This manual overviews the ways that data can be batch/bulk/en-masse imported into TaxonWorks.

Exercise target audience

Curators adding significant quantities of data. For "scientific" purposes "significant" means, more or less, "it would take a trained user more than 4 hours to do this piecemeal", or I have > 500 records.

Exercise goals

The goals are to describe:

  • The three major approaches to adding blocks of new data to TaxonWorks.
  • Pointing to specific batch-loading details.

At the end of the exercise you should:

  • Understand what is happening when you transform your data into TaxonWorks semantics.
  • Identify the major routes to batch-importing data.
  • Know where to suggest a new importer, or ask for help on a current one.
  • Know where to look next if you seek to build code your own Task to do a one off import.
  • Understand that all imports have benefits, and most have limitations.

Assumptions

  • We assume you have the following cards on your hub Favorites tab:
    • Tasks
      • Card 1
    • Data
      • Card 1
      • Card 2

Gotchas

  • TaxonWorks is only officially supported on Firefox and Chrome.
  • One import route (coding your own Rake tasks) requires the help of sys-admin for the instance of TaxonWorks being served.

Tips

  • Tip 1
  • Tip 2
  • Tip 3

Related exercises

  • Related exercise 1 (link to other manual)

Exercise

Syntax

  • In the exercise bulleted points are actions you should take, non-bulleted tasks are comments or guiding questions.
  • Highlighted words refer to text or elements in the application, for example button or field names.
  • "Quoted words" are literal values to be input or noticed

Import types

Model based "Batch load" options

Major format batch loaders

DwC-Archive
BibTeX

Coding your own batch-loader

Rake tasks

Ruby's "make" language is called Rake that creates "tasks' (not to be confused with TaxonWorks' "Task" interfaces cards).. Using Rake you have full access to the full TaxonWorks environment. You can setup your own repository, point to the TaxonWorks Rails environment, and code away. While we are moving these tasks out of the core code base, you can see some of them here.

A New Task

Technically you can contribute a whole new interface and underlying model for importing your data, this can be as customized as you wish if you have the chops!

Section title 2

...

Section title 3

...

Wrapping up

Reminder of what was taught/learned.

Addendum

Addendum topic 1

SOP/Best practices for OTU - OTU missidentifications

Missidentifications are OTU assertions.

As a curator I want to know how to represent historical missidentifications that have been subsequenctly cited in the literature as corrected.

How do I represent the OTU and persist the old name used, and the (non-nomenclatural) synonym?

How do I represent these data in the absence of using TaxonDeterminations on Specimens.

As a developer I need a top-level site-map

All files are in /docs

README.md follows the general style of SFG/Vue.  Large top center splash.  Three panels with directives underneath.  No side pannel.

# All these have side-pannels.  There will be significant file nesting in within each.
guide/README.md
develop/README.md
about/README.md

As a curator, I want a list of fields that TW understands for DwC/batch specimen imports.

Now that direct naming of TW fields inside DwC tsv imports is possible (eg TW::CollectionObject::BufferedDeterminations), it would be very helpful to have a complete list of the available TW fields.

This would allow me to cut out the DwC middleman and map our native db column names directly to TW ones.

Not all DwC fields have mappings in TW, and so making my data DwC compliant does not necessarily mean it's in the best format for TW.

Also, the identification/namespace fields are not well documented in how they map to TW, but maybe that's just me.

DwC field TW Field
institutionCode repository
collectionCode local namespace

As a curator I want to understand nominotypical names

Please add, with answers to BASIC_NOMENCLATURE:

For family group names:
  * What protonyms do I need to create for each form of the name
  * To which ranked Protonym do I attach the type Genus 
  * Do I have to re-attach the type genus to each family group protonym?
For genus group names:
  * Do I have to create a nominotypical subgenus?
  * To which rank should I attach the type species in cases where nominotypical genera exist, genus, or subgenus?  What if I have done the opposite?
  * Does the attachment of the type species differ if the nominotypical subgenus came with, or after the original description of the genus?
For species group names:
  * Do I have to create a nominotypical subspecies?
  * Which ranked name should I attach the type material to, species, or subspecies? 
  * What if I attached the type material to the opposite of what is required above?
  * When I create the original combination of a species group name, and it references a genus that has nominotypical subgenera, and those subgenera are currently in use, which genus protonym do I use in the original combination in the genus slot, the subgenus, or genus? For example Aus (Aus) exists and is accepted, and the original combination of the species is is "Aus bus".  Which Aus should I use in the genus slot, the current subgenus, or genus?

Request to define terms

  • Buffered collecting event
  • SHA—6 digit code at top of sandbox [anything more than this?]
  • Clone
  • Placeholder
  • Serial [as in "add a serial for the source"]
  • Soft validation
  • Parsed fields
  • pdf parser
  • x and y pdfs
  • Ghost
  • Centroid
  • Shapes
  • Local identifier type (from Comprehensive Digitization task basics)
  • OCR
  • Segmented images

Define SOP/best practices for OTUs and subsequent combinations

OTUs, Taxon Names, and History

Our objective is to address this issue: _If an OTU label was used to pick an OTU and relate it to some data, then when a Protonym moves, the label reflected in the OTU changes how it looks. The new, updated label, may not look like the historical use, what should happen? This is the key issue, what are the steps to resolve these cases.

Basic principles and summary

  • Tie your data to OTUs that have labels that represent their historical use
  • Data are summarized across OTUs in a single page, through the proxy use of the nomenclatural classification.
  • When an OTU is linked to a Protonym, the label looks correct. When the Protonym moves in the classifiation, the label for the OTU in relation to the data it is linked to looks incorrect.
    • The data haven't moved, they are still tied to the correct concept. The label for that concept may need updating. Point it to a new subsequent Combination.

Background on the TaxonName classification

  • The current classification is defined by the curator, and the parent of the name
  • To record a historical use, i.e. change the current classification, we use Combinations
  • When a protonym moves, it gets a new parent, this parent is reflected in the OTU label

Side note: How are OTU data summarized?

  • Some of this sounds complicated, if I manage all this historical stuff, how will I get it summarized?
  • How the Browse taxon page aggregates data across OTUs and synonyms, so that you don't have to move data along to a single OTU
    • The OTU page finds the Protonym for that page
    • All synonyms of that protonym (or the valid name, and all its synonyms) are found
    • All OTUs linked to any of these p

TaxonNames and OTUs

  • What data goes where
    • Nomenclatural data are attached to names
    • Everything else (biology, geography, determinations, etc.) is attached to an OTU

A TaxonName and an OTU (1:1)

  • Side note: relationship (edge) between TaxonName and OTU would benefit from RC5 semantics between the two

One TaxonName, many OTUs

  • Enumerate cases where this is useful
    • Coding same taxon independently for proofing
    • Transcribing data from literature- capturing verbatim names as you go then filtering those OTUs into the same or related concepts

Many TaxonNames, Many OTUs

  • What might this look like?
    • Protonyms
    • Combinations
    • Synonyms

!! Which OTU should I use?

We might see:

  • OTU linked to Protonym
    • !! Is it OK to link data to OTUs linked to Protonyms if that Protonym is in its current combination
  • OTU linked to synonym of Protonym
  • OTU linked to subsequent combiantion of Protonym

Citing data linked to OTUs

  • When should I Cite data linked to an OTU linked to Protonym?
  • When should I Cite data linked to an OTU linked to a Combination?
  • What citations on an OTU (or data bound to an OTU) that is linked to a Protonym mean
  • What citations on an OTU (or data bound to an OTU) that is linked to a Combiantion mean

OTUs and new subsequent combinations

  • !! Identify and outline a very specific scenario and set of steps referencing the UI

When should I create a new OTU?

  • What are the hints that suggest you need a new OTU?

What are the mechanisms in TaxonWorks by which new OTUs created?

What happens when I use the "wrong" OTU?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.