Package {R2camtrapdp}

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Constraint keys that are valid for a given field type

Description

Constraint keys that are valid for a given field type

Usage

.ctdp_allowed_constraints(type)

Arguments

Coerce a value that may be a list (from jsonlite::fromJSON(simplifyVector = FALSE)) into a plain atomic vector.

Description

Coerce a value that may be a list (from jsonlite::fromJSON(simplifyVector = FALSE)) into a plain atomic vector.

Usage

.ctdp_as_vector(x)

Arguments

Default Camtrap DP date / time formats

Description

Default Camtrap DP date / time formats

Usage

.ctdp_date_format()

.ctdp_time_format()

Default Camtrap DP datetime format

Description

The Frictionless datetime format used by the Camtrap DP table schemas.

Usage

.ctdp_datetime_format()

Default Camtrap DP schema / profile URL templates

Description

Each template contains the literal ⁠<version>⁠ placeholder, substituted with the requested Camtrap DP version at load time.

Usage

.ctdp_default_urls()

Create an empty typed vector for a Frictionless field type

Description

Create an empty typed vector for a Frictionless field type

Usage

.ctdp_empty_vec(type, n = 0L)

Arguments

Ensure a datetime/time string carries a fractional-seconds part

Description

Inserts .000 after HH:MM:SS when no fractional part is present, so values conform to a schema format that requires fractional seconds (⁠%f⁠), e.g. the bioacoustics media.timestamp / observations.eventStart format ⁠%Y-%m-%dT%H:%M:%S.%f%z⁠. Values that already have a fractional part, missing values, and non-matching strings are returned unchanged.

Usage

.ctdp_ensure_fractional(x)

Arguments

Extract the first complete top-level JSON object from helper output

Description

Extract the first complete top-level JSON object from helper output

Usage

.ctdp_extract_json(txt)

Field types supported by the Frictionless Table Schema specification

Description

Field types supported by the Frictionless Table Schema specification

Usage

.ctdp_frictionless_types()

Build a Frictionless field definition for a custom column

Description

Build a Frictionless field definition for a custom column

Usage

.ctdp_infer_field(name, x)

Arguments

Infer a Frictionless field type from an R vector

Description

Infer a Frictionless field type from an R vector

Usage

.ctdp_infer_type(x)

Arguments

Value

A Frictionless type string.

Test whether a character value represents a Frictionless "missing value"

Description

Test whether a character value represents a Frictionless "missing value"

Usage

.ctdp_is_missing(x, missing_values = "")

Arguments

Constraint keys defined by the Frictionless Table Schema specification

Description

Constraint keys defined by the Frictionless Table Schema specification

Usage

.ctdp_known_constraints()

Setter-function hints for Camtrap DP metadata properties

Description

Maps each metadata property to the R6_CamtrapDP method(s) that create it.

Usage

.ctdp_metadata_setters()

Create a typed NA-filled vector for a Frictionless field type

Description

Create a typed NA-filled vector for a Frictionless field type

Usage

.ctdp_na_vec(type, n = 0L)

Arguments

Normalise a mapping into a tibble with source and target columns

Description

Normalise a mapping into a tibble with source and target columns

Usage

.ctdp_normalize_mapping(mapping)

Extract a property path from a Frictionless metadata-error note

Description

Handles the common JSON-Schema error note shapes, e.g. ⁠property "contributors[].email" is not valid "email"⁠, ⁠... at property 'temporal/start'⁠, and ⁠'taxonomic' is a required property⁠.

Usage

.ctdp_note_path(note)

Arguments

Value

A property path string, or NA_character_.

Work around the malformed ⁠#$defs/version⁠ $ref in the Camtrap DP 1.0 profile

Description

Given a package directory and the profile URL declared in its descriptor, returns the descriptor file name to validate: "datapackage.json" if no fix is needed, or a separate "datapackage.validate.json" (pointing at a locally corrected profile) when the profile contains the malformed ref. The original datapackage.json and CSVs are never modified.

Usage

.ctdp_patch_descriptor(directory, profile)

Recursively prune "empty" elements from a list / value

Description

Returns NULL for values that are NULL, zero-length, all-NA, or lists that reduce to nothing after pruning. Used to drop unset metadata from datapackage.json so that empty placeholders (⁠[]⁠, null) do not trigger spurious profile-validation errors.

Usage

.ctdp_prune_empty(x)

Arguments

Map a Frictionless field type to an R storage class

Description

Date / datetime / time values are stored as character strings formatted in the schema's expected format so that the values written to CSV match exactly what Frictionless validates.

Usage

.ctdp_r_class(type)

Arguments

Value

A length-one character vector naming an R class.

Resolve a property path against a parsed descriptor

Description

Walks a parsed datapackage.json list following a path that may use . or / separators and name[] (all array elements) or name[n] (a 0-based index). Returns the value(s) found, collapsed with |.

Usage

.ctdp_resolve_descriptor_path(descriptor, path)

Arguments

Value

A length-one character of the value(s), or NA_character_.

Resolve the path to the Python helper script

Description

Resolve the path to the Python helper script

Usage

.ctdp_resolve_frictionless_script(script = NULL)

Run the helper and return the parsed Frictionless report (a list)

Description

Run the helper and return the parsed Frictionless report (a list)

Usage

.ctdp_run_frictionless(directory, descriptor, python, script)

Deterministic short hash of a string (djb2)

Description

Used to disambiguate schema cache files: two different schema URLs that share the same (version, resource) – e.g. the camera-trap and the bioacoustics "deployments" schemas for version 1.0.2 – must not collide in the cache. Avoids digest/random/time so it is reproducible.

Usage

.ctdp_str_hash(s)

Arguments

Value

A 10-digit, zero-padded decimal token (filename-safe).

Substitute the ⁠<version>⁠ placeholder in a URL template

Description

Substitute the ⁠<version>⁠ placeholder in a URL template

Usage

.ctdp_sub_version(template, version)

Arguments

Convert a strptime-style date/time format to a validation regex

Description

R's own strptime does not understand all the tokens used in Frictionless / Camtrap DP formats (notably ⁠%f⁠ for fractional seconds, used by the bioacoustics schemas: ⁠%Y-%m-%dT%H:%M:%S.%f%z⁠). Rather than rely on strptime, build an anchored regex from the format so any version's format can be checked.

Usage

.ctdp_temporal_regex(fmt)

Arguments

Value

An anchored PCRE regex string.

All URLs found in a piece of text

Description

All URLs found in a piece of text

Usage

.ctdp_text_urls(x)

Example acoustic deployment field-notebook

Description

Example deployment notebook for an acoustic (audio) survey, used in the acoustic vignette. One row per device deployment. Coordinates are random points within the inland Izu Peninsula (Shizuoka, Japan).

Usage

Adep

Format

A data frame with 2 rows and 14 variables:

deploymentID

Unique identifier of the deployment.

longitude

Longitude in decimal degrees (WGS84).

latitude

Latitude in decimal degrees (WGS84).

locationID

Identifier of the deployment location.

startDate

Deployment start date.

startTime

Deployment start time.

endDate

Deployment end date.

endTime

Deployment end time.

deviceID

Identifier of the recording device.

deviceModel

Manufacturer and model of the recording device.

samplingFrequency

Sampling frequency of the recordings (Hz).

bitDepth

Bit depth of the recordings.

channels

Number of audio channels.

setupBy

Name or identifier of the person/organization that deployed the device.

See Also

Aobs

Example acoustic observation field-notebook

Description

Example observation notebook for an acoustic (audio) survey, used in the acoustic vignette. One row per observation; the filename column is the audio file from which the media table is derived.

Usage

Aobs

Format

A data frame with 6 rows and 19 variables:

institutionCode

Institution code.

collectionCode

Collection code.

obsID

Observation identifier (within an event).

eventID

Identifier of the event the observation belongs to.

deploymentID

Identifier of the deployment.

locationID

Identifier of the deployment location.

date

Date the recording was made.

time

Time the recording started.

filename

Name of the audio file (used to build media).

duration

Duration of the recording file (seconds).

object

Recorded object category (animal, none, ...).

class

Taxonomic class of the observed organism.

genus

Genus of the observed organism.

species

Species epithet of the observed organism.

individualCount

Number of observed individuals; NA here (not counted from audio).

frequencyLow

Lower bound of the call frequency (Hz); approximate values from the bioacoustics literature for each species.

frequencyHigh

Upper bound of the call frequency (Hz); approximate values from the bioacoustics literature for each species.

eventStart

Date and time at which the event started.

eventEnd

Date and time at which the event ended.

See Also

Adep

Example deployment data (multiple camera deployments with image records)

Description

A small example deployment table used in the package vignettes and examples. One row per camera deployment.

Usage

Idep

Format

A data frame with 10 rows and 14 variables:

deploymentID

Unique identifier of the deployment.

longitude

Longitude in decimal degrees (WGS84).

latitude

Latitude in decimal degrees (WGS84).

locationID

Identifier of the deployment location.

startDate

Deployment start date.

startTime

Deployment start time.

endDate

Deployment end date.

endTime

Deployment end time.

cameraID

Identifier of the camera.

cameraModel

Manufacturer and model of the camera.

Delay

Predefined duration after detection during which further activity is ignored (camera delay).

Height

Height at which the camera was deployed.

bait

Whether bait was used for the deployment.

setupBy

Name or identifier of the person/organization that deployed the camera.

See Also

Iobs

Example observation data (image records)

Description

A small example observation table used in the package vignettes and examples. One row per observation.

Usage

Iobs

Format

A data frame with 388 rows and 17 variables:

institutionCode

Institution code.

collectionCode

Collection code.

obsID

Observation identifier (within an event).

eventID

Identifier of the event the observation belongs to.

locationID

Identifier of the deployment location.

date

Date the media file was recorded.

time

Time the media file was recorded.

object

Recorded object category (raw label).

class

Taxonomic class of the observed organism.

genus

Genus of the observed organism.

species

Species epithet of the observed organism.

individualCount

Number of observed individuals.

SDcardID

Identifier of the SD card.

filename

Name of the media file.

deploymentID

Identifier of the deployment the observation belongs to.

eventStart

Date and time at which the event started.

eventEnd

Date and time at which the event ended.

See Also

Idep

R6 class representing a Camtrap DP package profile (metadata schema)

Description

Frictionless validates the package data against the table schemas, but it validates the metadata (the datapackage.json descriptor itself) against the package profile – a JSON Schema (e.g. camtrap-dp-profile.json). MetadataProfile reads that profile and extracts the machine-readable metadata requirements: the required top-level properties (contributors, project, spatial, temporal, taxonomic, ...), their types / minItems, and the nested required keys of object properties (e.g. project requires title, samplingDesign, ...).

This lets the package check / scaffold the required metadata structure on the R side, instead of only discovering metadata problems when Python Frictionless runs.

Public fields

Methods

Public methods

• MetadataProfile$new()

• MetadataProfile$property()

• MetadataProfile$property_type()

• MetadataProfile$property_min_items()

• MetadataProfile$property_required()

• MetadataProfile$item_required()

• MetadataProfile$clone()

MetadataProfile$new()

Create a MetadataProfile.

Usage

MetadataProfile$new(
  version = "1.0.1",
  url = NULL,
  url_template = NULL,
  local_path = NULL,
  json = NULL,
  cache_dir = file.path(tempdir(), "camtrapdp-schemas"),
  use_cache = TRUE
)

Arguments

MetadataProfile$property()

Definition of a top-level property.

Usage

MetadataProfile$property(name)

Arguments

MetadataProfile$property_type()

type of a property.

Usage

MetadataProfile$property_type(name)

Arguments

MetadataProfile$property_min_items()

minItems of a property (or NULL).

Usage

MetadataProfile$property_min_items(name)

Arguments

MetadataProfile$property_required()

Nested required keys of an object property (e.g. project).

Usage

MetadataProfile$property_required(name)

Arguments

MetadataProfile$item_required()

Required keys of each item of an array property (e.g. taxonomic items require scientificName).

Usage

MetadataProfile$item_required(name)

Arguments

MetadataProfile$clone()

The objects of this class are cloneable with this method.

Usage

MetadataProfile$clone(deep = FALSE)

Arguments

Examples

## Not run: 
# Fetches the package profile for a Camtrap DP version (needs internet):
prof <- MetadataProfile$new(version = "1.0.1")
prof

## End(Not run)

R6 class representing Camtrap DP (schema-driven)

Description

R6 class holding the Camtrap DP metadata, deployments, media and observations. This is the schema-driven successor of the original R6_CamtrapDP: the field names, types, constraints and relations used when adding tables are read from the Frictionless Table Schemas for the configured Camtrap DP version, so an arbitrary version and custom columns are handled automatically.

The public field names and the method names of the original class are preserved for backward compatibility (set_deployments(), set_media(), set_observations(), set_custom(), add_contributors(), add_sources(), add_license(), set_project(), set_st(), set_taxon(), add_relatedIdentifiers(), add_references(), out_camtrapdp(), import_metadata()). New, schema-driven capabilities are added as new methods (get_schema(), add_table(), check_relations(), validate(), validate_frictionless()).

Public fields

Methods

Public methods

• CamtrapDP$new()

• CamtrapDP$update_created()

• CamtrapDP$set_properties()

• CamtrapDP$get_schema()

• CamtrapDP$set_deployments()

• CamtrapDP$set_media()

• CamtrapDP$set_observations()

• CamtrapDP$add_table()

• CamtrapDP$set_custom()

• CamtrapDP$add_contributors()

• CamtrapDP$add_sources()

• CamtrapDP$add_license()

• CamtrapDP$set_project()

• CamtrapDP$set_st()

• CamtrapDP$set_taxon()

• CamtrapDP$add_relatedIdentifiers()

• CamtrapDP$add_references()

• CamtrapDP$get_profile()

• CamtrapDP$metadata_requirements()

• CamtrapDP$check_metadata()

• CamtrapDP$check_descriptor()

• CamtrapDP$check_camtrap_profile()

• CamtrapDP$check_relations()

• CamtrapDP$external_references()

• CamtrapDP$validate()

• CamtrapDP$validate_frictionless()

• CamtrapDP$out_camtrapdp()

• CamtrapDP$import_metadata()

• CamtrapDP$clone()

CamtrapDP$new()

Creates a new instance.

Usage

CamtrapDP$new(tz = "Asia/Tokyo", ...)

Arguments

CamtrapDP$update_created()

Updates the created timestamp.

Usage

CamtrapDP$update_created(tz = "Asia/Tokyo")

Arguments

CamtrapDP$set_properties()

Sets package properties.

Usage

CamtrapDP$set_properties(
  directory = getwd(),
  name = NULL,
  id = NULL,
  title = NULL,
  description = NULL,
  profile =
    "https://raw.githubusercontent.com/tdwg/camtrap-dp/<version>/camtrap-dp-profile.json",
  version = "1.0.1",
  keywords = NULL,
  image = NULL,
  homepage = NULL,
  bibliographicCitation = NULL,
  coordinatePrecision = NULL,
  schema_urls = NULL,
  cache_dir = NULL,
  use_cache = NULL
)

Arguments

CamtrapDP$get_schema()

Load (and cache) the TableSchema for a resource at the configured version.

Usage

CamtrapDP$get_schema(
  resource,
  schema_url = NULL,
  local_path = NULL,
  json = NULL,
  refresh = FALSE
)

Arguments

Returns

A TableSchema.

CamtrapDP$set_deployments()

Sets deployments. Backward-compatible signature; when the schema is reachable the data is coerced and validated against it.

Usage

CamtrapDP$set_deployments(
  data,
  path = "deployments.csv",
  profile = "tabular-data-resource",
  format = "csv",
  mediatype = "text/csv",
  encoding = "utf-8",
  schema = NULL,
  mapping = NULL,
  datetime_merges = NULL,
  validate = TRUE,
  local_schema = NULL,
  tz = "Asia/Tokyo"
)

Arguments

CamtrapDP$set_media()

Sets media. See set_deployments() for shared arguments.

Usage

CamtrapDP$set_media(
  data,
  path = "media.csv",
  profile = "tabular-data-resource",
  format = "csv",
  mediatype = "text/csv",
  encoding = "utf-8",
  schema = NULL,
  mapping = NULL,
  datetime_merges = NULL,
  validate = TRUE,
  local_schema = NULL,
  tz = "Asia/Tokyo"
)

Arguments

CamtrapDP$set_observations()

Sets observations. See set_deployments() for shared arguments.

Usage

CamtrapDP$set_observations(
  data,
  path = "observations.csv",
  profile = "tabular-data-resource",
  format = "csv",
  mediatype = "text/csv",
  encoding = "utf-8",
  schema = NULL,
  mapping = NULL,
  datetime_merges = NULL,
  validate = TRUE,
  local_schema = NULL,
  tz = "Asia/Tokyo"
)

Arguments

CamtrapDP$add_table()

Add an arbitrary (custom or standard) resource table, schema-driven. Unlike set_custom() this loads a Table Schema, applies mapping, coerces, validates, stores the table in ⁠$data[[name]]⁠ and appends a proper tabular-data resource.

Usage

CamtrapDP$add_table(
  name,
  data,
  mapping = NULL,
  datetime_merges = NULL,
  schema_url = NULL,
  local_schema = NULL,
  schema_json = NULL,
  path = NULL,
  description = NULL,
  profile = "tabular-data-resource",
  format = "csv",
  mediatype = "text/csv",
  encoding = "utf-8",
  validate = TRUE,
  tz = "Asia/Tokyo"
)

Arguments

CamtrapDP$set_custom()

Sets a custom data resource (original behaviour preserved).

Usage

CamtrapDP$set_custom(name, description, data)

Arguments

CamtrapDP$add_contributors()

Adds contributors.

Usage

CamtrapDP$add_contributors(contrib_table)

Arguments

CamtrapDP$add_sources()

Add a source.

Usage

CamtrapDP$add_sources(title, path = NULL, email = NULL, version = NULL)

Arguments

CamtrapDP$add_license()

Add a license.

Usage

CamtrapDP$add_license(name, scope, path = NULL, title = NULL)

Arguments

CamtrapDP$set_project()

Sets the project.

Usage

CamtrapDP$set_project(
  title,
  samplingDesign,
  captureMethod,
  individualAnimals,
  observationLevel,
  id = NULL,
  acronym = NULL,
  description = NULL,
  path = NULL
)

Arguments

CamtrapDP$set_st()

Sets spatial and temporal coverage from the deployments.

Usage

CamtrapDP$set_st()

CamtrapDP$set_taxon()

Sets taxonomic coverage from the observations. The Camtrap DP taxonomic block requires a taxonID (e.g. a GBIF / IUCN identifier or URI), which is looked up with taxadb; taxadb is therefore a required dependency of the package (loaded with it, as in previous versions). Names that cannot be matched get taxonID = NA (omitted from the output rather than a bogus ⁠<uri>NA⁠). A warning() is emitted for scientificName values with unnecessary whitespace and for names with no taxonID in the chosen database.

Usage

CamtrapDP$set_taxon(taxonDB = "gbif")

Arguments

CamtrapDP$add_relatedIdentifiers()

Adds a relatedIdentifier.

Usage

CamtrapDP$add_relatedIdentifiers(
  relationType,
  relatedIdentifier,
  relatedIdentifierType,
  resourceTypeGeneral = NULL
)

Arguments

CamtrapDP$add_references()

Adds references.

Usage

CamtrapDP$add_references(reference)

Arguments

CamtrapDP$get_profile()

Load (and cache) the MetadataProfile for the package profile (the JSON Schema that Frictionless validates datapackage.json against). Uses self$profile (set by set_properties()), so it follows the configured version / flavor.

Usage

CamtrapDP$get_profile(refresh = FALSE)

Arguments

Returns

A MetadataProfile.

CamtrapDP$metadata_requirements()

The metadata requirements derived from the package profile: which top-level properties are required, their type, nested required keys, the method that creates each, and whether it is currently set.

Usage

CamtrapDP$metadata_requirements()

Returns

A tibble (property, required, type, sub_required, item_required, set_with, currently_set).

CamtrapDP$check_metadata()

Validate the current metadata against the package profile's required structure (a fast R-side counterpart to the profile validation that Frictionless performs). Reports missing required top-level properties and missing nested/required item keys.

Usage

CamtrapDP$check_metadata(summarize = TRUE)

Arguments

Returns

An issue table (see ctdp_issues()).

CamtrapDP$check_descriptor()

Pre-check that the package descriptor and its table schemas conform to the Frictionless specification, before the authoritative Python Frictionless step. Checks the package structure (non-empty resources; each resource has name and path/data; unique names; profile set) and the well-formedness of every loaded / inline table schema (ctdp_check_schema()). Optionally runs a full JSON Schema validation of the written descriptor when jsonschema is given and the jsonvalidate package is installed.

Usage

CamtrapDP$check_descriptor(
  check_schemas = TRUE,
  jsonschema = NULL,
  summarize = TRUE
)

Arguments

Returns

An issue table (see ctdp_issues()).

CamtrapDP$check_camtrap_profile()

Warn if the package profile is not a Camtrap DP profile. A package can be a valid Frictionless data package yet not be Camtrap DP form unless its profile is the Camtrap DP profile.

Usage

CamtrapDP$check_camtrap_profile(summarize = TRUE)

Arguments

Returns

An issue table (see ctdp_issues()).

CamtrapDP$check_relations()

Check primary-key and foreign-key relations across the registered tables, driven by each table's Table Schema.

Usage

CamtrapDP$check_relations(summarize = TRUE)

Arguments

Returns

An issue table (see ctdp_issues()).

CamtrapDP$external_references()

List every external (URL) reference declared across the package: the package profile, each resource's schema URL (or the references inside an inline schema), and the semantic / description-URL references of every loaded table schema. Use this when adopting a new version or schema flavor so that no URL-specified requirement is missed.

Usage

CamtrapDP$external_references()

Returns

A tibble (resource, field, key, category, url).

CamtrapDP$validate()

Aggregate validation: per-table schema issues collected at build time plus cross-table relation checks. Optionally also runs the Python Frictionless validation.

Usage

CamtrapDP$validate(
  relations = TRUE,
  metadata = FALSE,
  conformance = FALSE,
  frictionless = FALSE,
  summarize = TRUE,
  ...
)

Arguments

Returns

An issue table.

CamtrapDP$validate_frictionless()

Run the Python Frictionless validation on the written data package and parse the report into an issue table.

Usage

CamtrapDP$validate_frictionless(
  directory = NULL,
  python = "python",
  script = NULL,
  write = TRUE,
  patch_profile = TRUE,
  summarize = TRUE
)

Arguments

Returns

An issue table (engine "frictionless").

CamtrapDP$out_camtrapdp()

Exports the camtrapdp object and (optionally) writes the data package to disk.

Usage

CamtrapDP$out_camtrapdp(write = FALSE, directory = NULL)

Arguments

Returns

A camtrapdp object (list).

CamtrapDP$import_metadata()

Imports metadata from a list.

Usage

CamtrapDP$import_metadata(metadata0)

Arguments

CamtrapDP$clone()

The objects of this class are cloneable with this method.

Usage

CamtrapDP$clone(deep = FALSE)

Arguments

Examples

# Create the builder (offline):
dp <- R6_CamtrapDP$new(version = "1.0.1", title = "Example", description = "...")
## Not run: 
# Registering tables fetches the schema for the chosen version (needs internet):
deployments <- create_deployments(
  deploymentID = "A01", latitude = 35.1, longitude = 139.5,
  deploymentStart_date = "2023-04-01", deploymentStart_time = "09:00:00",
  deploymentEnd_date = "2023-05-01", deploymentEnd_time = "09:00:00")
dp$set_deployments(deployments)
dp$check_relations()
dp$out_camtrapdp(write = TRUE, directory = tempfile())

## End(Not run)

R6 class representing a Frictionless Table Schema

Description

TableSchema loads a Frictionless Table Schema (such as the Camtrap DP deployments / media / observations table schemas) from a URL, a local file, or an in-memory list, and exposes everything needed to build and validate a data table against it: field names and types, the primary key, foreign keys, missing-value tokens, and per-field constraints (required, unique, enum, minimum, maximum, minLength, maxLength, pattern, type, format).

Because the structure is read from the schema itself, an arbitrary Camtrap DP version and any custom / extra columns are handled automatically: any field present in the supplied schema participates in validation.

Public fields

Methods

Public methods

• TableSchema$new()

• TableSchema$field_names()

• TableSchema$field()

• TableSchema$required_field_names()

• TableSchema$field_type()

• TableSchema$requirements()

• TableSchema$empty_table()

• TableSchema$coerce()

• TableSchema$external_references()

• TableSchema$semantic_only_fields()

• TableSchema$check_schema()

• TableSchema$validate()

• TableSchema$clone()

TableSchema$new()

Create a TableSchema.

Usage

TableSchema$new(
  resource = NULL,
  version = "1.0.1",
  url_template = NULL,
  local_path = NULL,
  json = NULL,
  cache_dir = file.path(tempdir(), "camtrapdp-schemas"),
  use_cache = TRUE
)

Arguments

TableSchema$field_names()

Field names in schema order.

Usage

TableSchema$field_names()

TableSchema$field()

Get a single field definition by name.

Usage

TableSchema$field(name)

Arguments

TableSchema$required_field_names()

Names of fields whose constraints$required is TRUE.

Usage

TableSchema$required_field_names()

TableSchema$field_type()

Type of a field ("string", "number", ...).

Usage

TableSchema$field_type(name)

Arguments

TableSchema$requirements()

A tidy summary of the schema's requirements: one row per field with its type, format, and constraints (required, unique, enum, minimum, maximum, pattern). Works for any version / flavor.

Usage

TableSchema$requirements()

Returns

A tibble.

TableSchema$empty_table()

Create an empty (0-row) tibble shell with one correctly typed column per schema field, in schema order.

Usage

TableSchema$empty_table()

Returns

A tibble with 0 rows.

TableSchema$coerce()

Coerce a data frame to the schema. The result contains every schema field, in schema order: present columns are cast to the schema type (date/datetime/time formatted as canonical strings) and fields absent from the input are added as typed NA columns (Camtrap DP CSVs are expected to carry all schema columns). Columns not present in the schema are kept after the schema columns (custom columns) and a warning is emitted listing them.

Usage

TableSchema$coerce(df, tz = "Asia/Tokyo", complete = TRUE)

Arguments

Returns

A tibble.

TableSchema$external_references()

List the external (URL) references this schema declares (semantic ⁠skos:*⁠ mappings, reference URLs in field descriptions, the schema URL itself). See ctdp_schema_references().

Usage

TableSchema$external_references()

TableSchema$semantic_only_fields()

List fields whose meaning is defined only by reference (a semantic mapping or a description URL) and which therefore cannot be fully validated against a controlled vocabulary. See ctdp_semantic_only_fields().

Usage

TableSchema$semantic_only_fields()

TableSchema$check_schema()

Check that this schema is a well-formed Frictionless Table Schema (supported types, constraints valid for each type, keys reference defined fields). See ctdp_check_schema().

Usage

TableSchema$check_schema()

TableSchema$validate()

Validate a data frame against the schema constraints.

Usage

TableSchema$validate(
  df,
  source = paste0(self$resource %||% self$name, ".csv"),
  raw = NULL
)

Arguments

Returns

An issue table (see ctdp_issues()).

TableSchema$clone()

The objects of this class are cloneable with this method.

Usage

TableSchema$clone(deep = FALSE)

Arguments

Examples

# Build from an in-memory schema (offline):
sch <- list(name = "deployments",
  fields = list(
    list(name = "deploymentID", type = "string", constraints = list(required = TRUE)),
    list(name = "latitude", type = "number")),
  primaryKey = "deploymentID")
schema <- TableSchema$new("deployments", json = sch)
schema$field_names()
schema$required_field_names()
## Not run: 
# Or fetch the official schema for a Camtrap DP version (needs internet):
TableSchema$new("deployments", version = "1.0.1")

## End(Not run)

Example single camera-trap deployment data (video)

Description

Example deployment data for a single camera trap (at NIES, Japan), used in the single-camera vignette. One row.

Usage

Vdep

Format

A data frame with 1 row and 14 variables:

deploymentID

Unique identifier of the deployment.

longitude

Longitude in decimal degrees (WGS84).

latitude

Latitude in decimal degrees (WGS84).

locationID

Identifier of the deployment location.

startDate

Deployment start date.

startTime

Deployment start time.

endDate

Deployment end date.

endTime

Deployment end time.

cameraID

Identifier of the camera.

cameraModel

Manufacturer and model of the camera.

Delay

Camera delay.

Height

Height at which the camera was deployed.

bait

Whether bait was used.

setupBy

Name or identifier of the person/organization that deployed the camera.

References

Originally data can be used from doi:10.34462/0002000233

See Also

Vobs

Example single camera-trap observation data (video)

Description

Example observation data for the Vdep single camera-trap deployment, used in the single-camera vignette. One row per observation; filename is the video file from which the media table is built.

Usage

Vobs

Format

A data frame with 38 rows and 13 variables:

institutionCode

Institution code.

collectionCode

Collection code.

videoID

Video identifier.

locationID

Identifier of the deployment location.

date

Date the video was recorded.

time

Time the video was recorded.

object

Recorded object category.

class

Taxonomic class of the observed organism.

genus

Genus of the observed organism.

species

Species epithet of the observed organism.

individualCount

Number of observed individuals.

SDcardID

Identifier of the SD card.

filename

Name of the video file (used to build media).

References

Originally data can be used from doi:10.34462/0002000233

See Also

Vdep

Create deployments

Description

create_deployments creates a table of deployments.

Usage

create_deployments(
  deploymentID,
  latitude,
  longitude,
  deploymentStart = NULL,
  deploymentStart_date = NULL,
  deploymentStart_time = NULL,
  deploymentEnd = NULL,
  deploymentEnd_date = NULL,
  deploymentEnd_time = NULL,
  locationID = NULL,
  locationName = NULL,
  coordinateUncertainty = NULL,
  setupBy = NULL,
  cameraID = NULL,
  cameraModel = NULL,
  cameraDelay = NULL,
  cameraHeight = NULL,
  cameraDepth = NULL,
  cameraTilt = NULL,
  cameraHeading = NULL,
  detectionDistance = NULL,
  timestampIssues = NULL,
  baitUse = NULL,
  featureType = NULL,
  habitat = NULL,
  deploymentGroups = NULL,
  deploymentTags = NULL,
  deploymentComments = NULL,
  tz = "Asia/Tokyo"
)

Arguments

Value

A tibble of deployments.

Examples

create_deployments(
  deploymentID = c("A01", "A02"),
  latitude = c(35.1, 36.2), longitude = c(139.5, 140.1),
  deploymentStart_date = c("2023-04-01", "2023-04-02"),
  deploymentStart_time = c("09:00:00", "10:30:00"),
  deploymentEnd_date = c("2023-05-01", "2023-05-02"),
  deploymentEnd_time = c("09:00:00", "10:30:00"))

Create media

Description

create_media creates a table of media.

Usage

create_media(
  mediaID,
  deploymentID,
  timestamp = NULL,
  timestamp_date = NULL,
  timestamp_time = NULL,
  filePath,
  filePublic,
  fileMediatype,
  fileName = NULL,
  captureMethod = NULL,
  exifData = NULL,
  favorite = NULL,
  mediaComments = NULL,
  tz = "Asia/Tokyo",
  omitduplicate = TRUE
)

Arguments

Value

A tibble of media.

Examples

create_media(
  mediaID = "m1", deploymentID = "A01",
  timestamp_date = "2023-04-01", timestamp_time = "09:05:00",
  filePath = "img/m1.jpg", filePublic = TRUE, fileMediatype = "image/jpeg")

Create observations

Description

create_media creates a table of observations.

Usage

create_observations(
  observationID,
  deploymentID,
  mediaID = NULL,
  eventID = NULL,
  eventStart = NULL,
  eventStart_date = NULL,
  eventStart_time = NULL,
  eventEnd = NULL,
  eventEnd_date = NULL,
  eventEnd_time = NULL,
  observationLevel,
  observationType,
  cameraSetupType = NULL,
  scientificName = NULL,
  count = NULL,
  lifeStage = NULL,
  sex = NULL,
  behavior = NULL,
  individualID = NULL,
  individualPositionRadius = NULL,
  individualPositionAngle = NULL,
  individualSpeed = NULL,
  bboxX = NULL,
  bboxY = NULL,
  bboxWidth = NULL,
  bboxHeight = NULL,
  classificationMethod = NULL,
  classifiedBy = NULL,
  classificationTimestamp = NULL,
  classificationProbability = NULL,
  observationTags = NULL,
  observationComments = NULL,
  tz = "Asia/Tokyo",
  omitduplicate = TRUE
)

Arguments

Value

A tibble of observations.

Examples

create_observations(
  observationID = "o1", deploymentID = "A01", mediaID = "m1",
  eventStart = "2023-04-01 09:05:00", eventEnd = "2023-04-01 09:05:00",
  observationLevel = "media", observationType = "animal",
  scientificName = "Vulpes vulpes", count = 1L)

Build a schema-conformant table from arbitrary input

Description

ctdp_build_table() is the generic, schema-driven path from an arbitrary input spreadsheet to a Camtrap DP table. It (1) applies an optional column mapping, (2) optionally merges separate date/time columns into datetime columns, (3) coerces columns to the schema types, and (4) validates the result against the schema constraints. It works for any Camtrap DP version and for custom columns, because everything is read from the supplied TableSchema.

Frictionless conformance pre-checks (R-side)

Description

The R-side validation in this package normally trusts that the supplied table schema is a well-formed Frictionless Table Schema. These helpers add an R-side pre-check of that assumption – catching, before the Python Frictionless step, the kinds of structural problems Frictionless itself rejects (unsupported field type, a constraint that is not valid for a field's type, primary/foreign keys that reference undefined fields, etc.). The authoritative check remains R6_CamtrapDP's validate_frictionless().

Python Frictionless validation (shared internals + validate-only API)

Description

Helpers to run the Python frictionless validator on a written data package and parse the report. ctdp_validate_frictionless() validates an existing data package directory without writing or overwriting anything (use this when you only want to validate a package that was created elsewhere). The R6_CamtrapDP method validate_frictionless() reuses the same internals but writes the package from the object first (its write argument).

Column mapping helpers

Description

Map an arbitrary input spreadsheet onto Camtrap DP field names, and combine separate date / time columns into a single datetime column.

Discover external references inside a schema

Description

Camtrap DP schemas specify some information not through machine-enforceable Frictionless constraints, but through URLs: semantic mappings (skos:exactMatch / skos:broadMatch / skos:narrowMatch to Darwin Core, Audubon Core, Dublin Core, ... terms), reference URLs embedded in field descriptions (e.g. the IANA media-type registry for fileMediatype, or method DOIs for individualSpeed), and the resource schema / package profile URLs themselves.

These functions surface every such URL so that, when you adopt a new version or a new schema flavor, you do not overlook a specification that is expressed only by reference.

Internal utilities for schema-driven Camtrap DP conversion

Description

Helper functions shared across the package: a null-coalescing operator, a Frictionless-type to R-type mapper, and small convenience helpers used by TableSchema and R6_CamtrapDP.

Validation issue representation and reporting

Description

A uniform structure for validation issues, whether they are produced by the R-side schema/relation checks or parsed from a Python Frictionless validation report. An "issue table" is a tibble::tibble with the columns described in ctdp_issues().

Apply a column mapping to a data frame

Description

Renames the columns of df from the source (spreadsheet) names to Camtrap DP field names. Columns of df that are not mentioned in mapping are kept unchanged, so columns that already use Camtrap DP field names pass through.

Usage

ctdp_apply_mapping(df, mapping, drop_unmapped = FALSE)

Arguments

Value

A tibble with renamed columns.

Examples

raw <- data.frame(station = c("A01", "A02"), lat = c(35.1, 36.2))
ctdp_apply_mapping(raw, c(station = "deploymentID", lat = "latitude"))

Row-bind several issue tables

Description

Row-bind several issue tables

Usage

ctdp_bind_issues(...)

Arguments

Value

A single combined issue tibble.

Examples

a <- ctdp_issues(source = "media", constraint = "required",
                 severity = "error", message = "missing mediaID")
ctdp_bind_issues(a, ctdp_no_issues())

Build and validate a table against a Table Schema

Description

Build and validate a table against a Table Schema

Usage

ctdp_build_table(
  schema,
  data,
  mapping = NULL,
  datetime_merges = NULL,
  tz = "Asia/Tokyo",
  source = NULL,
  coerce = TRUE,
  stop_on_error = FALSE
)

Arguments

Value

A list with elements data (the coerced tibble) and issues (an issue table from ctdp_issues()).

Examples

sch <- list(name = "deployments",
  fields = list(
    list(name = "deploymentID", type = "string", constraints = list(required = TRUE)),
    list(name = "latitude", type = "number")),
  primaryKey = "deploymentID")
schema <- TableSchema$new("deployments", json = sch)
built <- ctdp_build_table(schema, data.frame(deploymentID = "A01", latitude = 35.1))
built$data

Check that a Table Schema is well-formed per the Frictionless spec

Description

Verifies the schema structure that Frictionless requires of any Table Schema, independently of the data: non-empty fields, each field with a name and a supported type, constraints that are valid for the field's type, unique field names, and primary/foreign keys that reference defined fields.

Usage

ctdp_check_schema(x)

Arguments

Value

An issue table (see ctdp_issues()). Constraint codes: schema-structure, schema-type, schema-constraint, schema-key.

Examples

sch <- list(name = "deployments",
  fields = list(
    list(name = "deploymentID", type = "string", constraints = list(required = TRUE)),
    list(name = "latitude", type = "number", constraints = list(minimum = -90, maximum = 90))),
  primaryKey = "deploymentID")
ctdp_check_schema(sch)

Did a validation pass (no errors)?

Description

Did a validation pass (no errors)?

Usage

ctdp_is_valid(issues)

Arguments

Value

TRUE if there are no "error" severity rows.

Examples

ctdp_is_valid(ctdp_no_issues())   # TRUE
bad <- ctdp_issues(source = "deployments", constraint = "required",
                   severity = "error", message = "missing")
ctdp_is_valid(bad)                # FALSE

Create an issue table

Description

Constructs a tibble of validation issues. All arguments are recycled to a common length. Use ctdp_no_issues() for an empty table with the right columns.

Usage

ctdp_issues(
  source,
  location_type = NA_character_,
  field = NA_character_,
  row = NA_integer_,
  constraint = NA_character_,
  severity = "error",
  message = NA_character_,
  engine = "R",
  value = NA_character_
)

Arguments

Value

A tibble with one row per issue.

Examples

ctdp_issues(source = "deployments", field = "latitude",
            constraint = "required", severity = "error",
            message = "latitude is missing")

Combine a date column and a time column into a datetime column

Description

Generalises the original ⁠*_date⁠ / ⁠*_time⁠ merging behaviour. Produces a character column formatted in the Camtrap DP datetime format (⁠%Y-%m-%dT%H:%M:%S%z⁠) so it round-trips cleanly to CSV.

Usage

ctdp_merge_datetime(
  df,
  date_col,
  time_col,
  target,
  tz = "Asia/Tokyo",
  format = .ctdp_datetime_format(),
  remove = TRUE
)

Arguments

Value

A tibble with the target datetime column added.

Examples

raw <- data.frame(d = c("2023-04-01", "2023-04-02"), t = c("09:00:00", "10:30:00"))
ctdp_merge_datetime(raw, "d", "t", "deploymentStart")

An empty issue table

Description

An empty issue table

Usage

ctdp_no_issues()

Value

A 0-row issue tibble.

Examples

ctdp_no_issues()

Parse a Frictionless validation report into an issue table

Description

Accepts either a parsed list (from jsonlite::fromJSON) or a JSON string, supporting both Frictionless v4 and v5 report layouts.

Usage

ctdp_parse_frictionless(report, resource_paths = NULL, descriptor = NULL)

Arguments

Value

An issue table (includes a value column with the offending value(s) when known).

Examples

# A valid Frictionless report parses to an empty issue table:
ctdp_parse_frictionless(list(valid = TRUE, tasks = list()))
## Not run: 
# Typically the report comes from validate_frictionless() / the Python validator:
issues <- ctdp_validate_frictionless("path/to/package")

## End(Not run)

List the external (URL) references declared by a Table Schema

Description

List the external (URL) references declared by a Table Schema

Usage

ctdp_schema_references(x)

Arguments

Value

A tibble with columns resource, field (NA for schema-level), key (the JSON key carrying the URL), category and url. Categories: "semantic-mapping" (skos:*), "description-reference", "example", "schema-ref" (the table schema's own URL).

Examples

sch <- list(name = "deployments",
  fields = list(
    list(name = "captureMethod", type = "string",
         "skos:exactMatch" = "http://rs.tdwg.org/dwc/terms/samplingProtocol")))
ctdp_schema_references(sch)

Fields whose meaning is defined only by reference (not machine-validated)

Description

Reports fields that carry a semantic mapping (⁠skos:*⁠) or a reference URL in their description but have no enforceable enum or pattern constraint. For these fields Frictionless (and this package) can check the type/format but not the controlled vocabulary, so the values should be checked against the referenced authority manually.

Usage

ctdp_semantic_only_fields(x)

Arguments

Value

A tibble: resource, field, type, reason, urls.

Examples

sch <- list(name = "deployments",
  fields = list(
    list(name = "captureMethod", type = "string",
         "skos:exactMatch" = "http://rs.tdwg.org/dwc/terms/samplingProtocol")))
ctdp_semantic_only_fields(sch)

Summarise an issue table to the console

Description

Prints a grouped summary (errors / warnings per source) followed by a detailed listing showing the offending file, field, row and message.

Usage

ctdp_summarize_validation(issues, max_detail = 50L)

Arguments

Value

The issue table, invisibly.

Examples

issues <- ctdp_issues(source = "deployments", field = "latitude",
                      constraint = "minimum", severity = "error",
                      message = "latitude below -90", value = "-100")
ctdp_summarize_validation(issues)

Validate an existing Camtrap DP directory with Python Frictionless

Description

Validates a data package that already exists on disk (e.g. created by another tool or in a previous run) without writing or overwriting the datapackage.json or the CSV files. This is the validate-only counterpart of the R6_CamtrapDP$validate_frictionless() method, which (by default) rewrites the package from the R object before validating.

Usage

ctdp_validate_frictionless(
  directory,
  python = "python",
  script = NULL,
  patch_profile = TRUE,
  summarize = TRUE
)

Arguments

Value

An issue table (see ctdp_issues()); engine "frictionless".

Examples

## Not run: 
# Validate an existing Camtrap DP on disk (needs Python with 'frictionless'):
issues <- ctdp_validate_frictionless("path/to/camtrapdp", python = "python")
ctdp_is_valid(issues)

## End(Not run)

Example Camtrap DP data package (acoustic)

Description

A pre-built Camtrap DP object (class camtrapdp, bioacoustics flavor) created from Adep and Aobs, for trying out the acoustic workflow without rebuilding from scratch. media is derived from the audio file names.

Usage

datapackageAdata

Format

A camtrapdp object (a list with the package metadata and the deployments / media / observations tables under ⁠$data⁠).

See Also

datapackageVdata, datapackageIdata

Example Camtrap DP data package (multiple camera traps)

Description

A pre-built Camtrap DP object (class camtrapdp) created from Idep and Iobs, for trying out the package without rebuilding from scratch.

Usage

datapackageIdata

Format

A camtrapdp object (a list with the package metadata and the deployments / media / observations tables under ⁠$data⁠).

See Also

datapackageVdata

Example Camtrap DP data package (single camera trap)

Description

A pre-built Camtrap DP object (class camtrapdp) created from Vdep and Vobs, for trying out the package without rebuilding from scratch.

Usage

datapackageVdata

Format

A camtrapdp object (a list with the package metadata and the deployments / media / observations tables under ⁠$data⁠).

References

Originally data can be used from doi:10.34462/0002000233

See Also

datapackageIdata