observations-table-schema.json

{
  "name": "observations",
  "title": "observations",
  "description": "`observations.csv` is a [tabular data](https://datapackage.org/standard/glossary/#tabular-data) resource from a GeoLocator Data Package containing relevant [events](http://rs.tdwg.org/dwc/terms/Event) (datetime and location) that typically happen in the field and provide important information for analysis. These observations should include at least equipment and, when appropriate, retrieval events, as well as ringing controls or direct sightings.\n\n{:.alert .alert-info}\nYou can think of `observations` as your log entries in your ringing book.\n\nAn observation is described at minimum by `datetime`, location (`latitude` and `longitude`), `ring_number`, and `observation_type` (e.g., equipment, retrieval, or capture). In addition, `sex` and `age_class` are required (use `U` for unknown `sex` and `0` for unknown `age_class`).\n\nAlso include ringing events for any control group (i.e., birds ringed but not equipped with a tag).\n\n **Example:** [`observations.csv`](https://github.com/GeoPressure/GeoLocator-DP/blob/main/example/observations.csv)",
  "$schema": "https://datapackage.org/profiles/2.0/tableschema.json",
  "fields": [
    {
      "name": "ring_number",
      "description": "Ring number associated with the observed bird. This is the bird-level identifier used to connect observations over time. It is not a strict foreign key because the same `ring_number` can appear in multiple `tags` rows (e.g., multiple deployments on the same bird).",
      "type": "string",
      "constraints": {
        "required": true
      },
      "skos:exactMatch": "https://vocab.nerc.ac.uk/collection/MVB/current/MVB000022",
      "example": "F58445"
    },
    {
      "name": "tag_id",
      "description": "Unique identifier of the tag. `tag_id` is NOT required in this table so that you can enter any relevant ringed species (e.g., control group). Foreign key to [`tags.tag_id`](/GeoLocator-DP/core/tags#tag_id). When provided, it should refer to a deployment associated with the same bird (`ring_number`).",
      "type": "string",
      "constraints": {
        "required": false
      },
      "example": "18LX"
    },
    {
      "name": "observation_type",
      "description": "Type of observation.\n - `equipment`: Attachment of the tag to the bird. If you equip a new tag at the same time as retrieving an old one from the same bird, create two dedicated rows in the dataset: one for retrieval and one for equipment.\n - `retrieval`: Retrieval of the data, generally through recapture and tag removal, but it can also happen through remote download readout methods (see [`tags.readout_method`](/GeoLocator-DP/core/tags#readout_method)).\n - `capture`: General case of capturing a bird while neither deploying nor retrieving a tag. This option covers (1) recapturing a bird without a device (choose `missing` in `device_status`), (2) a capture before `equipment` or after `retrieval`, and (3) captures of individuals from the control group. Recapture/retrap are not hard-coded in the dataset, but inferred from consecutive captures of the same `ring_number`.\n - `sighting`: Known presence of the bird on a date and location outside ringing (e.g., direct field observation with a color ring).\n - `other`: Any other observation type. Avoid using this; if used, always provide [`observation_comments`](/GeoLocator-DP/core/observations#observation_comments).",
      "type": "string",
      "constraints": {
        "required": true,
        "enum": ["equipment", "retrieval", "capture", "sighting", "other"]
      },
      "example": "equipment"
    },
    {
      "name": "datetime",
      "description": "Date and optionally time of the observation. Accepts any valid [ISO 8601](https://wikipedia.org/wiki/ISO_8601) date or datetime string, including date-only (`YYYY-MM-DD`), full datetime in local time (`YYYY-MM-DDThh:mm`), in UTC (`YYYY-MM-DDThh:mmZ`), or in any specific timezone (`YYYY-MM-DDThh:mm+hh:mm`).",
      "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/eventDate",
      "type": "datetime",
      "constraints": {
        "required": true
      },
      "example": "2020-03-01T22:00:00Z",
      "skos:closeMatch": " http://vocab.nerc.ac.uk/collection/MVB/current/MVB000352"
    },
    {
      "name": "latitude",
      "description": "Latitude of the observation location in decimal degrees, using the WGS84 datum.",
      "skos:closeMatch": [
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000074",
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000078"
      ],
      "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/decimalLatitude",
      "type": "number",
      "constraints": {
        "required": true,
        "minimum": -90,
        "maximum": 90
      },
      "example": "52.70442"
    },
    {
      "name": "longitude",
      "description": "Longitude of the observation location in decimal degrees, using the WGS84 datum.",
      "skos:closeMatch": [
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000075",
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000079"
      ],
      "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/decimalLongitude",
      "type": "number",
      "constraints": {
        "required": true,
        "minimum": -180,
        "maximum": 180
      },
      "example": "23.84995"
    },
    {
      "name": "location_name",
      "description": "Given name of the observation location. It might be helpful to keep a human-readable name of the location to differentiate the location of different observations more easily.",
      "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/locality",
      "type": "string",
      "constraints": {
        "required": false
      },
      "example": "Mwamba center--Nest box #2"
    },
    {
      "name": "device_status",
      "description": "Status of the tag itself (not the data inside the tag):\n - `present`: Tag on the bird.\n - `none`: No tag on the bird and this is expected (e.g., pre-equipment, post-removal, or control group). Only for `observation_type='capture'`.\n - `missing`: Tag lost by the bird. Only for `observation_type='capture'`. If a new tag is deployed on a bird that lost its previous tag, create two rows: one `capture`-`missing` and one `equipment`-`present`.\n - `unknown`: Only for `observation_type='sighting'`.\n\nCan only be `present` for `observation_type` `equipment` or `retrieval`.",
      "type": "string",
      "skos:relatedMatch": "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000084",
      "constraints": {
        "required": false,
        "enum": ["present", "none", "missing", "unknown"]
      },
      "example": "present"
    },
    {
      "name": "observer",
      "description": "The name of the individual or group who made the observation.",
      "type": "string",
      "constraints": {
        "required": false
      },
      "skos:exactMatch": [
        "https://vocab.nerc.ac.uk/collection/MVB/current/MVB000372/",
        "http://rs.tdwg.org/dwc/terms/recordedBy"
      ],
      "example": "Yann Rime"
    },
    {
      "name": "catching_method",
      "description": "Catching method according to [EURING Exchange Code](https://euring.org/files/documents/E2020ExchangeCodeV201.pdf#page=12). Generally, one of:\n - `M`: *m*ist-net\n - `N`: on *n*est\n - `Z`: unknown",
      "type": "string",
      "constraints": {
        "required": false,
        "enum": [
          "-",
          "A",
          "B",
          "C",
          "D",
          "F",
          "G",
          "H",
          "L",
          "M",
          "N",
          "O",
          "P",
          "R",
          "S",
          "T",
          "U",
          "V",
          "W",
          "Z"
        ]
      },
      "skos:relatedMatch": "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000397",
      "example": "M"
    },
    {
      "name": "age_class",
      "description": "Life stage of the bird according to the age class in [EURING Exchange Code](https://euring.org/files/documents/E2020ExchangeCodeV201.pdf#page=14). \n- `0`: Unknown\n- `1`: Pullus\n- `2`: Full-grown\n- `3`: 1yr\n- `4`: >1yr\n- `5`: 2yr\n- `6`: >2yr\n- ...",
      "type": "string",
      "constraints": {
        "required": true,
        "enum": [
          "0",
          "1",
          "2",
          "3",
          "4",
          "5",
          "6",
          "7",
          "8",
          "9",
          "A",
          "B",
          "C",
          "D",
          "E",
          "F",
          "G",
          "H"
        ]
      },
      "skos:closeMatch": [
        "http://rs.tdwg.org/dwc/terms/lifeStage",
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000018"
      ],
      "example": "1"
    },
    {
      "name": "sex",
      "description": "Sex of the bird according to [EURING Exchange Code](https://euring.org/files/documents/E2020ExchangeCodeV201.pdf#page=13) as male `M`, female `F` or unknown `U`.",
      "skos:closeMatch": [
        "http://rs.tdwg.org/dwc/terms/sex",
        "https://vocab.nerc.ac.uk/collection/MVB/current/MVB000023"
      ],
      "type": "string",
      "constraints": {
        "required": true,
        "enum": ["U", "M", "F"]
      },
      "example": "female"
    },
    {
      "name": "condition",
      "description": "Condition of the bird following a simplified version of the [EURING Exchange Code](https://euring.org/files/documents/E2020ExchangeCodeV201.pdf#page=23). Assumed to be `alive` if not provided.",
      "type": "string",
      "constraints": {
        "required": false,
        "enum": ["alive", "unhealthy", "dead", "unknown"]
      },
      "example": "alive",
      "skos:closeMatch": "http://rs.tdwg.org/dwc/terms/vitality"
    },
    {
      "name": "mass",
      "description": "Mass of the tagged bird. See [EURING Exchange Code](https://euring.org/files/documents/E2020ExchangeCodeV201.pdf#page=27). Expressed in grams.",
      "type": "number",
      "constraints": {
        "required": false,
        "minimum": 0
      },
      "unit": "grams",
      "skos:exactMatch": "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000019",
      "example": "23.3"
    },
    {
      "name": "wing_length",
      "description": "Maximum chord measurement. See [EURING Exchange Code](https://euring.org/files/documents/E2020ExchangeCodeV201.pdf#page=26). Expressed in millimeters.",
      "type": "number",
      "constraints": {
        "required": false,
        "minimum": 0
      },
      "unit": "mm",
      "example": "15.4"
    },
    {
      "name": "additional_metric",
      "description": "A list of additional measurements, facts, characteristics, or assertions about the record. Recommended best practice is to use a key:value encoding schema for a data interchange format such as JSON.",
      "type": "string",
      "constraints": {
        "required": false
      },
      "skos:exactMatch": ["http://rs.tdwg.org/dwc/terms/dynamicProperties"],
      "skos:narrowMatch": [
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000356",
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000354"
      ],
      "example": "{'RP3':32, 'fat':2, 'tarsusLengthInMeters':0.014, 'weightInGrams':120}"
    },
    {
      "name": "observation_comments",
      "description": "Comments or notes about the observation.",
      "skos:broadMatch": [
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000396",
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000077",
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000082",
        "http://vocab.nerc.ac.uk/collection/MVB/current/MVB000083"
      ],
      "type": "string",
      "constraints": {
        "required": false
      },
      "example": ""
    }
  ],
  "missingValues": ["", "NA"],
  "foreignKeys": [
    {
      "fields": "tag_id",
      "reference": {
        "resource": "tags",
        "fields": "tag_id"
      }
    }
  ],
  "fieldsMatch": ["superset"]
}