camtrapR (version 0.98.0)

recordDatabaseIndividual: Generate a single-species record database from camera trap images with custom metadata tags

Description

The function generates a single-species record database containing individual IDs for (spatial) capture-recapture analyses. It prepares input for the function spatialDetectionHistory.

Usage

recordDatabaseIndividual(inDir,
  hasStationFolders,
  hasIndividualFolders,
  cameraID,
  camerasIndependent,
  minDeltaTime = 0,
  timeZone,
  stationCol,
  writecsv = FALSE,
  outDir,
  customMetadataTags,
  metadataHierarchyDelimitor = "|",
  metadataIDTag,
  additionalMetadataTags
)

Arguments

inDir

character. Directory containing station directories with renamed and identified images in species subdirectories (e.g. inDir/StationA/SpeciesA).

hasStationFolders

logical. Do station directories have camera subdirectories?

hasIndividualFolders

logical. Are species images sorted into species directories? If not, species identification will be derived from metadata tags.

cameraID

character. Where should the function look for camera IDs: 'filename', 'directory'. 'filename' requires images renames with imageRename. 'directory' requires a camera subdirectory within station director

camerasIndependent

logical. If TRUE, camera IDs are taken from image file names (requires images renames with function link{imageRename}) or from the directory structure (assumes directory structure such as: Station/Camera/Species).

minDeltaTime

numeric. time difference between observation of the same species at the same station to be considered independent (in minutes)

timeZone

character. timeZone must be an argument of OlsonNames

stationCol

character. Name of the camera trap station column. "Station" by default.

writecsv

logical. Should the record database be saved as a .csv?

outDir

character. Directory to save csv to. If NULL and writecsv = TRUE, recordTable will be written to inDir.

customMetadataTags

logical. Should function try to extract custom metadata tags from images (from metadata tag "HierarchicalSubject").

metadataHierarchyDelimitor

character. The character delimiting hierarchy levels in image metadata tags in field "HierarchicalSubject". Either "|" or ":".

metadataIDTag

character. In custom image metadata, the individual ID tag name.

additionalMetadataTags

character. additional camera model-specific metadata tags to be extracted.

Value

• A data frame containing species records and individual IDs and additional information about stations, date, time and (optionally) further metadata.

Warning

Custom image metadata tags must be written to the images. The function cannot read tags from .xmp sidecar files. Make sure you set the preferences accordingly. In DigiKam, go to Settings/Configure digiKam/Metadata. There, make sure "Write from sidecar files" is unchecked.

Details

The function can handle a number of different ways of storing images, and supports individual identification by moving images into individual-specific directories as well as metadata tagging. In every case, images need to be stored into a species directory first (e.g. using function getSpeciesImages). Station subdirectories are optional. Individuals can then be identified from images by moving them into individual directories ("Species/Station/Individual/XY.JPG" or "Species/Individual/XY.JPG"). Alternatively, individuals can be identified from images using metadata tagging without the need for directories for individuals: "Species/XY.JPG" or "Species/Station/XY.JPG". In that case, metadataIDTag specifies the metadata tag group name that contains individual identification tags. minDeltaTime is a criterion for temporal independence of records of a species at the same station/location. Setting it to 0 will make the function return all records. camerasIndependent defines if the cameras at a station are to be considered independent (e.g. FALSE if both cameras face each other and possibly TRUE if they face different trails). exclude can be used to exclude "species" directories containing irrelevant images (e.g. "team", "blank", "unidentified"). stationCol can be set to match the station column name in the camera trap station table (see camtraps). Many digital images contain Exif metadata tags such as "AmbientTemperature" or "MoonPhase" that can be extracted if specified in metadataTags. Because these are manufacturer-specific and not standardized, function exifTagNames provides a vector of all available tag names. Multiple names can be specified as a character vector as: c(Tag1, Tag2, ...). The metadata tags thus extracted may be used as covariates in occupancy modelling. metadataHierarchyDelimitor is "|" for images tagged in DigiKam and images tagged in Adobe Bridge / Lightroom with the default settings.

References

Phil Harvey's Exiftool http://www.sno.phy.queensu.ca/~phil/exiftool/

Examples

wd_images_ID <- system.file("pictures/sample_images_tagged/LeopardCat", package = "camtrapR")
 # missing space in species = "LeopardCat" is because of CRAN package policies

 if (Sys.which("exiftool") != ""){        # only run these examples if Exiftool is available

 rec.db.pbe <- recordDatabaseIndividual(inDir                  = wd_images_ID,
                                        minDeltaTime           = 60,
                                        hasStationFolders      = FALSE,
                                        hasIndividualFolders   = FALSE,
                                        camerasIndependent     = FALSE,
                                        writecsv               = FALSE,
                                        customMetadataTags     = TRUE,
                                        metadataIDTag          = "individual",
                                        additionalMetadataTags = c("Model", "Make"),
                                        timeZone               = "Asia/Kuala_Lumpur"
 )

 } else {                                # show function output if Exiftool is not available
 print("Exiftool is not available. Cannot test function")
 data(recordDatabaseIndividualSample)
 }