スキーマ内の外部（URL）参照

Camtrap DP の情報の一部は、機械検証可能な制約ではなく URL で指定されます。 具体的には意味マッピング（skos:exactMatch / broadMatch / narrowMatch による Darwin Core, Audubon Core 等の用語への対応）や、フィールドの description 内の参照 URL（例: fileMediatype の IANA メディアタイプ登録簿、individualSpeed の手法 DOI） です。本パッケージが強制するのは構造化された制約のみで、URL で参照される意味は 検証されません。バージョンや新フレーバーを採用する際にこうした指定を見落とさない よう、次で一覧化できます。

dep_schema$external_references()   # スキーマが宣言する全 URL（skos・description・schema URL）
dep_schema$semantic_only_fields()  # 意味が URL でのみ定義され、値域を機械検証できない列

external_references() は整形済みの表（resource, field, key, category, url）を返します。semantic_only_fields() は、参照先の権威に照らして手動確認が 必要な列を示します。パッケージ全体は datapackage$external_references() で一括 スキャンできます。

デプロイメントの作成

デプロイメントデータ（Idep）を用い、従来どおりに作成します。 create_deployments() は結合済みの日時、または日付列・時刻列の別指定の両方を 受け付けます。

deployments <- create_deployments(
  deploymentID         = Idep$deploymentID,
  longitude            = Idep$longitude,
  latitude             = Idep$latitude,
  locationID           = Idep$locationID,
  deploymentStart_date = Idep$startDate,
  deploymentStart_time = Idep$startTime,
  deploymentEnd_date   = Idep$endDate,
  deploymentEnd_time   = Idep$endTime,
  cameraID             = Idep$cameraID,
  cameraModel          = Idep$cameraModel,
  cameraDelay          = Idep$Delay,
  cameraHeight         = Idep$Height,
  baitUse              = Idep$bait,
  setupBy              = Idep$setupBy)

create_deployments() は上記以外に次の引数も受け付けます: deploymentStart / deploymentEnd（結合済み日時。*_date / *_time の組の代わりに使用）、 locationName、coordinateUncertainty、cameraDepth（cameraHeight と同時指定 不可）、cameraTilt、cameraHeading、detectionDistance、timestampIssues、 featureType、habitat、deploymentGroups、deploymentTags、 deploymentComments、tz（タイムゾーン、既定 "Asia/Tokyo"）。

メディアの作成

# メディア ID
mediaIDi <- paste(Iobs$institutionCode,
                  Iobs$collectionCode,
                  Iobs$locationID,
                  as.numeric(factor(Iobs$filename)),
                  sep = "_")

# ファイル情報
fileName      <- Iobs$filename
filetype      <- tolower(unlist(lapply(strsplit(fileName, "\\."), "[", 2)))
fileMediatype <- paste("image", filetype, sep = "/")
filePublic    <- !grepl("ヒト", fileName)   # ヒト画像は非公開にする

media <- create_media(
  mediaID        = mediaIDi,
  deploymentID   = Iobs$deploymentID,
  timestamp_date = Iobs$date,
  timestamp_time = Iobs$time,
  filePath       = "Image",
  filePublic     = filePublic,
  fileMediatype  = fileMediatype,
  captureMethod  = "activityDetection",
  fileName       = fileName)

create_media() は上記以外に次の引数も受け付けます: timestamp（結合済み日時。 timestamp_date / timestamp_time の代わり）、exifData、favorite、 mediaComments、tz、omitduplicate（重複 mediaID を除外。既定 TRUE）。

observationの作成

# イベント単位の観察
observationLevel <- "event"

# observationType はスキーマの enum 値のいずれか
observationType <- ifelse(Iobs$object == "hito", "human",
                   ifelse(Iobs$object == "none", "blank",
                   ifelse(Iobs$object == "unidentifiable", "unknown", "animal")))

# 学名
scientificName <- ifelse(is.na(Iobs$genus), Iobs$class, paste(Iobs$genus, Iobs$species))

# 一意の観察 ID
observationID <- paste(mediaIDi, Iobs$obsID, sep = "_")

observations <- create_observations(
  observationID             = observationID,
  deploymentID              = Iobs$deploymentID,
  eventID                   = Iobs$eventID,
  eventStart                = Iobs$eventStart,
  eventEnd                  = Iobs$eventEnd,
  observationLevel          = observationLevel,
  observationType           = observationType,
  scientificName            = scientificName,
  count                     = Iobs$individualCount,
  classificationMethod      = "human",
  classificationProbability = 1)

create_observations() は上記以外に次の引数も受け付けます: mediaID、 eventStart_date / eventStart_time と eventEnd_date / eventEnd_time の組 （結合済み eventStart / eventEnd の代わり）、cameraSetupType、lifeStage、 sex、behavior、individualID、individualPositionRadius、 individualPositionAngle、individualSpeed、bboxX、bboxY、bboxWidth、 bboxHeight、classifiedBy、classificationTimestamp、observationTags、 observationComments、tz、omitduplicate。

R6 オブジェクトの作成（バージョン指定）

datapackage <- R6_CamtrapDP$new(version = "1.0.1")

ここで与える version が、検証および datapackage.json に使われるスキーマを 選択します。別の Camtrap DP リリースを対象にする場合は変更してください。

テーブルの登録（スキーマ検証付き）

set_deployments(), set_media(), set_observations() は名前を維持しつつ、 各々がスキーマ型への変換と、選択バージョンのスキーマに対する検証を行います。 問題は要約として表示され、validate = FALSE で表示を抑制できます。

datapackage$set_deployments(deployments)
datapackage$set_media(media)
datapackage$set_observations(observations)

（スキーマの取得、ファイル書き出し、分類検索、Python 呼び出しを伴うチャンクは、 本 vignette のビルド時には表示のみで実行されません。そのため出力は表示されません。）

検証の要約は、各問題について、ファイル・列・行・違反した規則・メッセージを示します。 例えば enum に反する値、minimum/maximum の範囲外の数値、必要な書式に一致しない 日時などです。列の型にすら適合しない値（例: number 列の非数値文字列）は、無言で NA に変換されるのではなく type エラーとして報告されます。

テーブル間リレーションの検査

外部キー（例: media.deploymentID は deployments に、observations.mediaID は media に存在する必要がある）と主キーの一意性は、各テーブルのスキーマから読み取られ、 登録済みのテーブル間で検査されます。

datapackage$check_relations()

主キーまたは必須の外部キー列が、格納後のテーブルでまるごと欠損している場合 （多くは列名不一致で型変換が NA 補完したケース）、check_relations() は警告を出し データを指し示します（例: datapackage$data$observations has 'deploymentID' entirely missing ...）。 datapackage$data$<resource> を直接確認できます。

どのメタデータが必須かを profile で確認する

必須メタデータ自体は、パッケージ profile（JSON Schema）から読み取られます。 metadata_requirements() は必須トップレベルプロパティ・それを設定するメソッド・ 現在の設定状況を一覧化し、check_metadata() は現在のオブジェクトを profile に 照合して不足（project.samplingDesign のようなネストしたキーを含む）を報告します。

datapackage$metadata_requirements()   # チェックリスト: property, required, set_with, currently_set
datapackage$check_metadata()          # 不足している必須メタデータを報告

これは Frictionless が行うメタデータ（profile）検証（§6）に相当する R 側の事前 チェックで、パッケージを書き出して Python を呼ぶ前に必須構造を確認できます。

必須メタデータ

cd <- data.frame(
  title        = c("Keita Fukasawa", "Kana Terayama"),
  email        = c("fukasawa@nies.go.jp", "terayama.kana@nies.go.jp"),
  path         = c("https://orcid.org/0000-0003-0272-9180",
                   "https://orcid.org/0000-0001-6935-7233"),
  role         = c("contact", "principalInvestigator"),
  organization = c("National Institute for Environmental Studies (NIES)",
                   "National Institute for Environmental Studies (NIES)"))
datapackage$add_contributors(cd)

datapackage$set_project(
  title            = "DummyData",
  samplingDesign   = "simpleRandom",
  captureMethod    = "activityDetection",
  individualAnimals = FALSE,
  observationLevel = "event")

datapackage$set_st()

datapackage$set_taxon()

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

任意メタデータ

datapackage$add_license(name = "CC-BY-4.0",
                        path = "http://creativecommons.org/licenses/by/4.0/",
                        scope = "data")
datapackage$add_license(name = "CC-BY-4.0",
                        path = "http://creativecommons.org/licenses/by/4.0/",
                        scope = "media")

datapackage$add_relatedIdentifiers(
  relationType          = "IsSupplementTo",
  relatedIdentifier     = "https://doi.org/xxxx",
  relatedIdentifierType = "DOI",
  resourceTypeGeneral   = "JournalArticle")

datapackage$set_properties(
  name     = "dummy-nies",
  homepage = "https://www.nies.go.jp/biology/snapshot_japan/index.html")
datapackage$add_sources(title = "DummyData")
datapackage$add_references(reference = "DummyNIES https://doi.org/xxxxx")

RD <- data.frame(id = seq_len(388), Time = sample(1:29, 388, replace = TRUE))

datapackage$set_custom(name = "rest",
                       description = "data for the REST method",
                       data = RD)

適合の事前チェック（Python を呼ぶ前に）

Python を実行する前に、パッケージがそもそも well-formed な Frictionless データ パッケージか、また CamtrapDP 形式かを R 側で確認できます。Frictionless が行う構造 チェックを R で再現するもので、新規・特殊なスキーマの問題を早期に発見できます。

datapackage$check_descriptor()        # 記述子＋各 table schema の構造（Frictionless 仕様）
datapackage$check_camtrap_profile()   # profile が CamtrapDP でなければ警告

パッケージは Frictionless として妥当でも、CamtrapDP 形式とは限りません。 それは profile が CamtrapDP プロファイル（既定）かどうかで決まります。GeoJSON 妥当性や物理ファイル構造を含む権威ある判定は、下記の Frictionless 実行が担います。

Frictionless の実行

書き出したパッケージを公式スキーマに照らして、Python の Frictionless で確認できます。frictionless を導入した Python が必要です （pip install frictionless）。

issues <- datapackage$validate_frictionless(directory = path, python = "python")
ctdp_is_valid(issues)   # error が無ければ TRUE

注意 — path を上書きします。 validate_frictionless() は既定で write = TRUE のため、検証前に out_camtrapdp() を呼んで directory 内の datapackage.json と CSV を現在のオブジェクトの内容で上書きします。すでに ディスク上にある datapackage を上書きせず検証だけしたい場合は write = FALSE、 または R6 オブジェクト不要の検証専用関数を使ってください:

ctdp_validate_frictionless("path/to/existing/package", python = "python")

issues は問題 1 件につき 1 行の整形済み表で、source（ファイル）、field（列／ プロパティパス）、row（行）、違反した constraint、問題の value（実値）、 message を与えるため、エラー箇所を正確に把握できます。セルエラーの value は不正な セル値、メタデータ（profile）エラーの value は note 内のプロパティパス（例 contributors[].email）で datapackage.json を辿って解決した実値です。R 側のスキーマ検査・リレーション検査・メタデータ（profile）検査・ 適合事前チェック・（任意で）Frictionless レポートは、1 回の呼び出しで集約する こともできます。

datapackage$validate(relations = TRUE, metadata = TRUE, conformance = TRUE,
                     frictionless = TRUE, directory = path, python = "python")

カメラトラップの列を音響フレーバーへ対応づける

マッピングが必要なのは、名前が音響フィールドと異なる列だけです。すでに音響 フィールド名と同じ列（deploymentID, latitude, deploymentStart など）は自動的に 対応づけられ、マッピングは不要です。deployments では、カメラトラップの camera* 列が device* に改名され、カメラ専用列は音響に対応が無いため除外し、音響固有の列は データがあれば設定します。

library(dplyr)

# カメラトラップ deployments -> 音響 deployments（改名が必要な列だけ）
mapping <- c(
  cameraID      = "deviceID",
  cameraModel   = "deviceModel",
  cameraDelay   = "deviceDelay",
  cameraHeight  = "deviceHeight",
  cameraDepth   = "deviceDepth",
  cameraTilt    = "deviceTilt",
  cameraHeading = "deviceHeading")

dep_acoustic <- camtrap_deployments %>%
  select(-any_of(c("featureType", "timestampIssues")))   # カメラ専用: 音響に対応列なし

dp$set_deployments(dep_acoustic, mapping = mapping)

列の対応 — deployments:

observations で改名が必要なのは cameraSetupType → deviceSetupType のみです （音響は frequencyLow / frequencyHigh / classificationConfirmation も追加）。 media に改名はなく、追加フィールド（duration, bitDepth, samplingFrequency, gain, channels）のみです。

フレーバーのスキーマも、他のスキーマと同様に確認できます。なお TableSchema$new("deployments", version = "1.0.2") を url_template なしで 呼ぶとカメラトラップ用の deployments スキーマが読み込まれます。音響の要件を確認 するには音響 URL を渡してください。requirements() は各フィールドの型・書式・制約を 表で返します。

acoustic_dep <- TableSchema$new(
  "deployments", version = "1.0.2",
  url_template = sprintf(ba, "deployments-table-schema-acoustic.json"))
acoustic_dep$field_names()
acoustic_dep$required_field_names()
acoustic_dep$requirements()        # field / type / format / required / enum / min / max / pattern
acoustic_dep$external_references()

create_deployments(), create_media(), create_observations() はカメラ トラップのスキーマに合わせて作られています。別フレーバー（または将来版の新規列） では、create_*() ではなくスキーマ駆動の経路（ctdp_build_table() か、カスタム schema = を渡した set_*() メソッド）でテーブルを構築してください。