From 8aff5632e359d3099cdc76885c372ace3ef8b2bd Mon Sep 17 00:00:00 2001 From: Jakub Bubnicki Date: Tue, 24 Sep 2024 22:50:22 +0200 Subject: [PATCH] first draft with 2 new tables (annotations & models) --- annotations-table-schema.json | 412 +++++++++++++++++++++++++++++++++ camtrap-dp-profile.json | 3 +- deployments-table-schema.json | 22 +- models-table-schema.json | 21 ++ observations-table-schema.json | 22 ++ 5 files changed, 477 insertions(+), 3 deletions(-) create mode 100644 annotations-table-schema.json create mode 100644 models-table-schema.json diff --git a/annotations-table-schema.json b/annotations-table-schema.json new file mode 100644 index 0000000..8cdcde5 --- /dev/null +++ b/annotations-table-schema.json @@ -0,0 +1,412 @@ +{ + "name": "annotations", + "title": "annotations", + "description": "Table with annotations derived from the media files. Associated with deployments (`deploymentID`). annotations can mark non-animal events (camera setup, human, blank) or one or more animal annotations (`annotationType` = `animal`) of a certain taxon, count, life stage, sex, behavior and/or individual. annotations can be made at different levels (`annotationLevel`).", + "fields": [ + { + "name": "annotationID", + "description": "Unique identifier of the annotation.", + "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/occurrenceID", + "type": "string", + "constraints": { + "required": true, + "unique": true + }, + "example": "ann2" + }, + { + "name": "annotationSourceID", + "description": "Identifier of a previous annotation used as input, providing the provenance of annotations made by either machines or humans.", + "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/occurrenceID", + "type": "string", + "constraints": { + "required": false + }, + "example": "ann1" + }, + { + "name": "observationID", + "description": "Unique identifier of the (consensus) observation the annotation belongs to. Foreign key to `observations.observationID`.", + "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/occurrenceID", + "type": "string", + "constraints": { + "required": true, + "unique": true + }, + "example": "obs1" + }, + { + "name": "deploymentID", + "description": "Identifier of the deployment the annotation belongs to. Foreign key to `deployments.deploymentID`.", + "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/parentEventID", + "type": "string", + "constraints": { + "required": true + }, + "example": "dep1" + }, + { + "name": "mediaID", + "description": "Identifier of the media file that was classified. Only applicable for media-based annotations (`annotationLevel` = `media`). Foreign key to `media.mediaID`.", + "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/associatedMedia", + "type": "string", + "constraints": { + "required": false + }, + "example": "m1" + }, + { + "name": "eventID", + "description": "Identifier of the event the annotation belongs to. Facilitates linking event-based and media-based annotations with a permanent identifier.", + "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/eventID", + "type": "string", + "constraints": { + "required": false + }, + "example": "sequence1" + }, + { + "name": "eventStart", + "description": "Date and time at which the event started. Formatted as an ISO 8601 string with timezone designator (`YYYY-MM-DDThh:mm:ssZ` or `YYYY-MM-DDThh:mm:ss±hh:mm`).", + "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/eventDate", + "skos:narrowMatch": "http://rs.tdwg.org/ac/terms/startTimestamp", + "type": "datetime", + "format": "%Y-%m-%dT%H:%M:%S%z", + "constraints": { + "required": true + }, + "example": "2020-03-01T22:00:00Z" + }, + { + "name": "eventEnd", + "description": "Date and time at which the event ended. Formatted as an ISO 8601 string with timezone designator (`YYYY-MM-DDThh:mm:ssZ` or `YYYY-MM-DDThh:mm:ss±hh:mm`).", + "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/eventDate", + "skos:narrowMatch": "http://rs.tdwg.org/ac/terms/endTimestamp", + "type": "datetime", + "format": "%Y-%m-%dT%H:%M:%S%z", + "constraints": { + "required": true + }, + "example": "2020-04-01T22:00:00Z" + }, + { + "name": "annotationLevel", + "description": "Level at which the annotation was classified. `media` for media-based annotations that are directly associated with a media file (`mediaID`). These are especially useful for machine learning and don't need to be mutually exclusive (e.g. multiple classifications are allowed). `event` for event-based annotations that consider an event (comprising a collection of media files). These are especially useful for ecological research and should be mutually exclusive, so that their `count` can be summed.", + "type": "string", + "constraints": { + "required": true, + "enum": [ + "media", + "event" + ] + }, + "example": "media" + }, + { + "name": "annotationType", + "description": "Type of the annotation. All categories in this vocabulary have to be understandable from an AI point of view. `unknown` describes classifications with a `classificationProbability` below some predefined threshold i.e. neither humans nor AI can say what was recorded.", + "type": "string", + "constraints": { + "required": true, + "enum": [ + "animal", + "human", + "vehicle", + "blank", + "unknown", + "unclassified" + ] + }, + "example": "animal" + }, + { + "name": "cameraSetupType", + "description": "Type of the camera setup action (if any) associated with the annotation.", + "type": "string", + "constraints": { + "required": false, + "enum": [ + "setup", + "calibration" + ] + }, + "example": "calibration" + }, + { + "name": "scientificName", + "description": "Scientific name of the observed individual(s).", + "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/scientificName", + "type": "string", + "constraints": { + "required": false + }, + "example": "Canis lupus" + }, + { + "name": "count", + "description": "Number of observed individuals (optionally of given life stage, sex and behavior).", + "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/individualCount", + "type": "integer", + "constraints": { + "required": false, + "minimum": 1 + }, + "example": 5 + }, + { + "name": "lifeStage", + "description": "Age class or life stage of the observed individual(s).", + "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/lifeStage", + "type": "string", + "constraints": { + "required": false, + "enum": [ + "adult", + "subadult", + "juvenile" + ] + }, + "example": "adult" + }, + { + "name": "sex", + "description": "Sex of the observed individual(s)", + "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/sex", + "type": "string", + "constraints": { + "required": false, + "enum": [ + "female", + "male" + ] + }, + "example": "female" + }, + { + "name": "behavior", + "description": "Dominant behavior of the observed individual(s), preferably expressed as controlled values (e.g. grazing, browsing, rooting, vigilance, running, walking). Formatted as a pipe (`|`) separated list for multiple values, with the dominant behavior listed first.", + "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/behavior", + "type": "string", + "constraints": { + "required": false + }, + "example": "vigilance" + }, + { + "name": "individualID", + "description": "Identifier of the observed individual.", + "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/organismID", + "type": "string", + "constraints": { + "required": false + }, + "example": "RD213" + }, + { + "name": "individualPositionRadius", + "description": "Distance from the camera to the observed individual identified by `individualID`. Expressed in meters. Required for distance analyses (e.g. [Howe et al. 2017](https://doi.org/10.1111/2041-210X.12790)) and random encounter modelling (e.g. [Rowcliffe et al. 2011](https://doi.org/10.1111/j.2041-210X.2011.00094.x)).", + "type": "number", + "constraints": { + "required": false, + "minimum": 0 + }, + "unit": "m", + "example": 6.81 + }, + { + "name": "individualPositionAngle", + "description": "Angular distance from the camera view centerline to the observed individual identified by `individualID`. Expressed in degrees, with negative values left, `0` straight ahead and positive values right. Required for distance analyses (e.g. [Howe et al. 2017](https://doi.org/10.1111/2041-210X.12790)) and random encounter modelling (e.g. [Rowcliffe et al. 2011](https://doi.org/10.1111/j.2041-210X.2011.00094.x)).", + "type": "number", + "constraints": { + "required": false, + "minimum": -90, + "maximum": 90 + }, + "unit": "°", + "example": -8.56 + }, + { + "name": "individualSpeed", + "description": "Average movement speed of the observed individual identified by `individualID`. Expressed in meters per second. Required for random encounter modelling (e.g. [Rowcliffe et al. 2016](https://doi.org/10.1002/rse2.17)).", + "type": "number", + "constraints": { + "required": false, + "minimum": 0 + }, + "unit": "m/s", + "example": 1.75 + }, + { + "name": "individualLength", + "description": "Length of the observed individual identified by `individualID`. Expressed in centimetres.", + "type": "number", + "constraints": { + "required": false, + "minimum": 0 + }, + "unit": "cm", + "example": 10 + }, + { + "name": "individualBiomass", + "description": "Biomass of the observed individual identified by `individualID`. Expressed in grams.", + "type": "number", + "constraints": { + "required": false, + "minimum": 0 + }, + "unit": "g", + "example": 3500 + }, + { + "name": "bboxX", + "description": "Horizontal position of the top-left corner of a bounding box that encompasses the observed individual(s) in the media file identified by `mediaID`. Or the horizontal position of an object in that media file. Measured from the left and relative to media file width.", + "skos:broadMatch": "http://rs.tdwg.org/ac/terms/XFrac", + "type": "number", + "constraints": { + "required": false, + "minimum": 0, + "maximum": 1 + }, + "example": 0.2 + }, + { + "name": "bboxY", + "description": "Vertical position of the top-left corner of a bounding box that encompasses the observed individual(s) in the media file identified by `mediaID`. Or the vertical position of an object in that media file. Measured from the top and relative to the media file height.", + "skos:broadMatch": "http://rs.tdwg.org/ac/terms/YFrac", + "type": "number", + "constraints": { + "required": false, + "minimum": 0, + "maximum": 1 + }, + "example": 0.25 + }, + { + "name": "bboxWidth", + "description": "Width of a bounding box that encompasses the observed individual(s) in the media file identified by `mediaID`. Measured from the left of the bounding box and relative to the media file width.", + "skos:broadMatch": "http://rs.tdwg.org/ac/terms/widthFrac", + "type": "number", + "constraints": { + "required": false, + "minimum": 1e-15, + "maximum": 1 + }, + "example": 0.4 + }, + { + "name": "bboxHeight", + "description": "Height of the bounding box that encompasses the observed individual(s) in the media file identified by `mediaID`. Measured from the top of the bounding box and relative to the media file height.", + "skos:broadMatch": "http://rs.tdwg.org/ac/terms/heightFrac", + "type": "number", + "constraints": { + "required": false, + "minimum": 1e-15, + "maximum": 1 + }, + "example": 0.5 + }, + { + "name": "classificationMethod", + "description": "Method (most recently) used to classify the annotation.", + "type": "string", + "constraints": { + "required": false, + "enum": [ + "human", + "machine" + ] + }, + "example": "human" + }, + { + "name": "classifiedBy", + "description": "Name or identifier of the person or AI algorithm that (most recently) classified the annotation.", + "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/identifiedBy", + "type": "string", + "constraints": { + "required": false + }, + "example": "MegaDetector V5" + }, + { + "name": "classifiedByModelID", + "description": "Unique identifier of the model used for the annotation. Foreign key to `models.modelID`.", + "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/identifiedBy", + "type": "string", + "constraints": { + "required": false + }, + "example": "mod1" + }, + { + "name": "classificationTimestamp", + "description": "Date and time of the (most recent) classification. Formatted as an ISO 8601 string with timezone designator (`YYYY-MM-DDThh:mm:ssZ` or `YYYY-MM-DDThh:mm:ss±hh:mm`).", + "skos:broadMatch": "http://rs.tdwg.org/dwc/terms/dateIdentified", + "type": "datetime", + "format": "%Y-%m-%dT%H:%M:%S%z", + "constraints": { + "required": false + }, + "example": "2020-08-22T10:25:19Z" + }, + { + "name": "classificationProbability", + "description": "Degree of certainty of the (most recent) classification. Expressed as a probability, with `1` being maximum certainty. Omit or provide an approximate probability for human classifications.", + "type": "number", + "constraints": { + "required": false, + "minimum": 0, + "maximum": 1 + }, + "example": 0.95 + }, + { + "name": "annotationTags", + "description": "Tag(s) associated with the annotation. Formatted as a pipe (`|`) separated list for multiple values, with values optionally formatted as `key:value` pairs.", + "skos:exactMatch": "http://rs.tdwg.org/ac/terms/tag", + "type": "string", + "constraints": { + "required": false + }, + "example": "travelDirection:left" + }, + { + "name": "annotationComments", + "description": "Comments or notes about the annotation.", + "skos:exactMatch": "http://rs.tdwg.org/dwc/terms/occurrenceRemarks", + "type": "string", + "constraints": { + "required": false + }, + "example": "" + } + ], + "missingValues": [ + "" + ], + "primaryKey": "annotationID", + "foreignKeys": [ + { + "fields": "annotationSourceID", + "reference": { + "resource": "", + "fields": "annotationID" + } + }, + { + "fields": "deploymentID", + "reference": { + "resource": "deployments", + "fields": "deploymentID" + } + }, + { + "fields": "mediaID", + "reference": { + "resource": "media", + "fields": "mediaID" + } + } + ] +} diff --git a/camtrap-dp-profile.json b/camtrap-dp-profile.json index 6c8a05d..389f2b4 100644 --- a/camtrap-dp-profile.json +++ b/camtrap-dp-profile.json @@ -113,7 +113,8 @@ "principalInvestigator", "rightsHolder", "publisher", - "contributor" + "contributor", + "funder" ] } } diff --git a/deployments-table-schema.json b/deployments-table-schema.json index 00aa396..3d6c8e0 100644 --- a/deployments-table-schema.json +++ b/deployments-table-schema.json @@ -173,6 +173,15 @@ "unit": "°", "example": -90 }, + { + "name": "cameraSettings", + "description": "Other custom camera settings used for the deployment. Formatted as a valid JSON object.", + "type": "any", + "constraints": { + "required": false + }, + "example": "{\"setting1\":200,\"setting2\":true}" + }, { "name": "cameraHeading", "description": "Angle at which the camera was deployed in the horizontal plane. Expressed in decimal degrees clockwise from north, with values ranging from `0` to `360`: `0` = north, `90` = east, `180` = south, `270` = west.", @@ -206,14 +215,23 @@ "example": false }, { - "name": "baitUse", - "description": "`true` if bait was used for the deployment. More information can be provided in `tags` or `comments`.", + "name": "attractantUse", + "description": "`true` if any attractant was used for the deployment. More information can be provided in `attractantType`", "type": "boolean", "constraints": { "required": false }, "example": true }, + { + "name": "attractantType", + "description": "Type of attractant that was used.", + "type": "string", + "constraints": { + "required": false + }, + "example": "fish" + }, { "name": "featureType", "description": "Type of the feature (if any) associated with the deployment.", diff --git a/models-table-schema.json b/models-table-schema.json new file mode 100644 index 0000000..2fe216f --- /dev/null +++ b/models-table-schema.json @@ -0,0 +1,21 @@ +{ + "name": "models", + "title": "models", + "description": "Table with details of the ML/AI models used to produce the annotations.", + "fields": [ + { + "name": "modelID", + "description": "Unique identifier of the model.", + "type": "string", + "constraints": { + "required": true, + "unique": true + }, + "example": "mod1" + } + ], + "missingValues": [ + "" + ], + "primaryKey": "modelID" +} diff --git a/observations-table-schema.json b/observations-table-schema.json index d5b1c11..323b367 100644 --- a/observations-table-schema.json +++ b/observations-table-schema.json @@ -215,6 +215,28 @@ "unit": "m/s", "example": 1.75 }, + { + "name": "individualLength", + "description": "Length of the observed individual identified by `individualID`. Expressed in centimetres.", + "type": "number", + "constraints": { + "required": false, + "minimum": 0 + }, + "unit": "cm", + "example": 10 + }, + { + "name": "individualBiomass", + "description": "Biomass of the observed individual identified by `individualID`. Expressed in grams.", + "type": "number", + "constraints": { + "required": false, + "minimum": 0 + }, + "unit": "g", + "example": 3500 + }, { "name": "bboxX", "description": "Horizontal position of the top-left corner of a bounding box that encompasses the observed individual(s) in the media file identified by `mediaID`. Or the horizontal position of an object in that media file. Measured from the left and relative to media file width.",