Manual:

Back to overviewNext PageLast Page


Introduction

This manual covers generic usage of the Wildbook framework.

Basic assumptions and data structure

Wildbook is a software application for storing and analyzing data about animals in a study population. Its ultimate goal is to make it easy for a wildlife project to quickly go from data collection to analysis and generation of new knowledge.

A single software instance of Wildbook application is deployed into a web server and can host one or multiple distinct mark-recapture studies. We will call this distinct instance of the application for a particular study a “wildbook”.

Wildbook divides its managed mark-recapture data into these distinct types:

A SinglePhotoVideo represents a media object (photo or video) captured in a wildlife study. The corresponding data construct within Wildbook is org.ecocean.SinglePhotoVideo.

An Encounter is an individual sighting of a member of a target population of a single species. An encounter report is submitted to the framework via a web interface and may represent (if enough data is present for identification) a “mark” (first sighting) or “recapture” (subsequent re-sighting) of an individual from a study population. Each encounter contains data that represent one individual at one point in time. For example, an Encounter may represent the photographing of a single dolphin at a specific point in time and/or the collection of a tissue sample for genetic identification later. An encounter can be added to a previously identified marked individual in the database, representing a re-sighting of that animal, or it can be allocated as a new marked individual and given a name or tag number (e.g. “A-001”), representing a new animal previously undocumented in the wildbook. The corresponding data construct within Wildbook is org.ecocean.Encounter.

A Marked Individual is an uniquely identified member of a population and includes one or more reported encounters. It is up to each library and its research staff to determine the minimum amount of data and procedures required for a unique identification (e.g., a distinct ear tag, a visual photo-identification, digital extraction of spot patterning, a distinct DNA pattern, etc.). As the study acquires more and more encounters for each individual in the wildbook, it will be able to build up robust metrics for population analysis, allowing its research team to better understand population trends. The corresponding data construct within Wildbook is org.ecocean.MarkedIndividual.

An Occurrence represents a observation of multiple individuals together and includes one or more encounters over a short duration of time. The purpose of an occurrence is to provide an hierarchical category to represent groups of individuals and potentially the relationships among them at a point in time and space. For example, an occurrence might represent a pod of baleen whales, which are typically fluid in membership, even over brief periods of observation (e.g., less than an hour), or more stable groups, such as sperm whales, which might remain relatively stable over a longer period of continuous observation (e.g., several hours). The corresponding data construct within Wildbook is org.ecocean.Occurrence.

A Biological Sample (a.k.a. “Tissue Sample” but not strictly a tissue) represents the retrieval of a small amount of biological material from an animal. For example, this may be a direct biopsy, a fecal sample, a blood sample, or a mucus sample. Because a biological sample is collected at a location and point in time, it is added to an Encounter, representing an additional part of an animal sighting record. Wildbook currently allows you to add data for these types of subsequent analyses upon a Biological Sample:

  • One or more haplotype analyses and determinations
  • One or more genotype analyses (microsatellite markers)
  • One or more genetic sex determinations
  • One or more biological/chemical measurement. For example, you could record a stable isotope determination of “-2.4 ppm for 13C” or record a pollutant measurement detected in the sample.

The corresponding data construct within Wildbook is org.ecocean.genetics.TissueSample.

A Relationship (e.g., the mother-calf relationship between a whale and her offspring) represents an observed relationship between two animals in the wild. The corresponding data construct within Wildbook is org.ecocean.social.Relationship.

A Social Unit (e.g., a pack of wolves, a pod of dolphins, etc.) represents a formal grouping of animals linked by a set of observed Relationships, and those relationships exist within the context of a social unit. The corresponding data construct within Wildbook is org.ecocean.social.SocialUnit.

Recorded data

Wherever possible, the data attributes recorded for an Encounter or a Marked Individual are named according to their Darwin Core equivalents. A definition of the Darwin Core can be found on the TDWG web site:

“The Darwin Core is body of standards. It includes a glossary of terms (in other contexts these might be called properties, elements, fields, columns, attributes, or concepts) intended to facilitate the sharing of information about biological diversity by providing reference definitions, examples, and commentaries. The Darwin Core is primarily based on taxa, their occurrence in nature as documented by observations, specimens, and samples, and related information.”

This is not a clean one-to-one mapping (the Darwin Core does not specifically address mark-recapture or its terminology), but our implementation does make it fairly easy to map a TapirLink provider or IPT web application to the Encounter database table if you're using Wildbook Framework with a relational database. This allows mark-recapture data to serve a dual purpose: local population analysis and broader biodiversity analysis in frameworks such as the GBIF and OBIS.

Let's take a look at the fields recorded for Encounter and Marked Individual records. If you're using a relational database (e.g., Wildbook framework ships with an Apache Derby database that is created on first startup), these fields (or “attributes”) map to columns in the appropriately named database tables (i.e., “Encounter” and “MarkedIndividual”).

Encounter

The following attributes are described in the Darwin Core quick reference at: http://rs.tdwg.org/dwc/terms/#dcterms:type

Wherever possible, this class will be extended with Darwin Core attributes for greater adoption of the standard.

  • catalogNumber - “An identifier (preferably unique) for the record within the data set or collection.” In Wildbook, the catalogNumber is the primary key for encounters in the database.
  • otherCatalogNumbers - “A list (concatenated and separated) of previous or alternate fully qualified catalog numbers or other human-used identifiers for the same Occurrence, whether in the current or any other data set or collection.” Often times, researchers will assign an encounter number to a sighting in the field, and that number will differ to the catalogNumber assigned when the sighting is added to the database in Wildbook. This field allows multiple catalog numbers to be recorded to account for this.
  • individualID - “An identifier for an individual or named group of individual organisms represented in the Occurrence. Meant to accommodate resampling of the same individual or group for monitoring purposes. May be a global unique identifier or an identifier specific to a data set.”
  • locationID - “An identifier for the set of location information (data associated with dcterms:Location). May be a global unique identifier or an identifier specific to the data set.”
  • decimalLatitude - “The geographic latitude (in decimal degrees, using the spatial reference system given in geodeticDatum) of the geographic center of a Location. Positive values are north of the Equator, negative values are south of it. Legal values lie between -90 and 90, inclusive.”
  • decimalLongitude - “The geographic longitude (in decimal degrees, using the spatial reference system given in geodeticDatum) of the geographic center of a Location. Positive values are east of the Greenwich Meridian, negative values are west of it. Legal values lie between -180 and 180, inclusive.”
  • verbatimLocality - “The original textual description of the place.”
  • maximumDepthInMeters - “The greater depth of a range of depth below the local surface, in meters.”
  • maximumElevationInMeters - “The upper limit of the range of elevation (altitude, usually above sea level), in meters.”
  • sex - “The sex of the biological individual(s) represented in the Occurrence. Recommended best practice is to use a controlled vocabulary.”
  • day - “The integer day of the month on which the Event occurred.”
  • month - “The ordinal month in which the Event occurred.”
  • year - “The four-digit year in which the Event occurred, according to the Common Era Calendar.”
  • verbatimEventDate - “The verbatim original representation of the date and time information for an Event.”
  • occurrenceRemarks - “Comments or notes about the Occurrence.”
  • modified - “The most recent date-time on which the resource was changed. For Darwin Core, recommended best practice is to use an encoding scheme, such as ISO 8601:2004(E).”
  • occurrenceID - “An identifier for the Occurrence (as opposed to a particular digital record of the occurrence). In the absence of a persistent global unique identifier, construct one from a combination of identifiers in the record that will most closely make the occurrenceID globally unique.”
  • recordedBy - “A list (concatenated and separated) of names of people, groups, or organizations responsible for recording the original Occurrence. The primary collector or observer, especially one who applies a personal identifier (recordNumber), should be listed first.”
  • behavior - “A description of the behavior shown by the subject at the time the Occurrence was recorded. Recommended best practice is to use a controlled vocabulary.”
  • eventID - “An identifier for the set of information associated with an Event (something that occurs at a place and time). May be a global unique identifier or an identifier specific to the data set.”
  • dynamicProperties - “A list (concatenated and separated) of additional measurements, facts, characteristics, or assertions about the record. Meant to provide a mechanism for structured content such as key-value pairs.”
  • identificationRemarks - “Comments or notes about the Identification.”
  • genus - “The full scientific name of the genus in which the taxon is classified.”
  • specificEpithet - “The name of the first or species epithet of the scientificName.”

The following fields are specific to this mark-recapture project and do not have an easy to map Darwin Core equivalent.

  • dwcImageURL - An URL to a thumbnail image representing the encounter.
  • measurements - An array of physical Measurement objects that define point-in-time measurements on the animal (e.g., height, weight, etc.)
  • livingStatus - Defines whether the sighting represents a living or deceased individual. Currently supported values are: “alive” and “dead”.
  • dwcDateAdded - Date the encounter was added to the library.
  • researcherComments - Additional comments added by library users
  • submitterID - Username of the logged in researcher assigned to the encounter.
  • submitterEmail, submitterPhone, submitterAddress - name, email, phone, address of the encounter submitter.
  • informothers - other email addresses to inform of status changes to this encounter (e.g., other members of a tour group reporting this encounter)
  • photographerName, photographerEmail, photographerPhone, photographerAddress - name, email, phone, address of the encounter photographer.
  • additionalImageNames - names and relative paths of the photos submitted for this encounter.
  • interestedResearchers - researcher email addresses to notify when data for this encounter is modified.
  • hour - hour of the sighting
  • minutes - minutes of the sighting
  • patterningCode - an open ended string that allows a type of patterning to be identified. As an example, see the use of color codes at splashcatalog.org, allowing pre-defined fluke patterning types to be used to help narrow the search for a marked individual.
  • images - an array of the SinglePhotoVideo objects that represent individual photos and videos gathered during this encounter.
  • tissueSamples - an array of the TissueSample objects that represent biological samples (biopsies, blood samples, etc.) gathered during this encounter.

Marked Individual

The following data are recorded for marked individuals.

  • individualID - unique identification string of the MarkedIndividual, such as 'A-109. This is the same intended value as Encounter.individualID.
  • alternateid - alternate id for the MarkedIndividual, such as a physical tag number of reference in another database.
  • encounters - an array of the encounters of this marked individual.
  • comments - additional comments added by researchers.
  • sex - overall determined sex of the MarkedIndividual.
  • nickName - nickname for the MarkedIndividual.
  • nickNamer - individual (person) who nicknamed this marked individual.
  • dataFiles - an array of filenames of additional data files added to the MarkedIndividual.
  • interestedResearchers - a list of email addresses to notify when this MarkedIndividual is modified.
  • dateTimeCreated - creation time of this data object.
  • dynamicProperties - from the Darwin Core: “A list (concatenated and separated) of additional measurements, facts, characteristics, or assertions about the record. Meant to provide a mechanism for structured content such as key-value pairs.”
  • patterningCode - an open-ended string that allows a type of patterning to be identified. As an example, see the use of color codes at splashcatalog.org, allowing pre-defined fluke patterning types to be used to help narrow the search for a marked individual.

Occurrence

The following data are recorded for occurrences.

  • encounters - an array of the encounters comprising this encounter.
  • comments - additional comments added by researchers.
  • groupBehavior - description of the aggregate behaviors of the individuals in the group represented by this occurrence.
  • individualCount - estimated number of total individuals in this occurrence, which may be greater than the number “captured” and recorded.


Manual:

Back to overviewNext PageLast Page