Type: Package
Title: Estimating Lengths and Uncertainty from Photogrammetric Imagery
Version: 1.0.1
Date: 2024-10-25
Author: Joshua Hewitt [aut], K.C. Bierlich [aut, cre], Enrico Pirotta [aut]
Maintainer: K.C. Bierlich <bierlick@oregonstate.edu>
Description: Implementation of Bayesian models for estimating object lengths and morphological relationships between object lengths using photographic data collected from drones. The Bayesian model is described in "Bayesian approach for predicting photogrammetric uncertainty in morphometric measurements derived from drones" (Bierlich et al., 2021, <doi:10.3354/meps13814>).
URL: https://github.com/MMI-CODEX/Xcertainty
BugReports: https://github.com/MMI-CODEX/Xcertainty/issues
License: MIT + file LICENSE
Depends: R (≥ 3.0.2), nimble
Imports: tidyr, dplyr, coda
Suggests: testthat, knitr, rmarkdown, stringr, ggdist, tidyverse
VignetteBuilder: knitr, rmarkdown
LazyData: true
Encoding: UTF-8
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2024-10-25 23:06:05 UTC; k.bierlich
Repository: CRAN
Date/Publication: 2024-10-26 00:10:02 UTC

Compute body condition metrics for a set of measurements

Description

Function that post-processes posterior samples from a sampler, such as independent_length_sampler().

Usage

body_condition(
  data,
  output,
  length_name,
  width_names,
  width_increments,
  summary.burn = 0.5,
  height_ratios = rep(1, length(width_names)),
  metric = c("surface_area", "body_area_index", "body_volume", "standardized_widths")
)

Arguments

data

The output from parse_observations

output

The return object from a sampler

length_name

The name of the total-length measurement in the dataset

width_names

Character vector with the names of the width measurements in the dataset

width_increments

Numeric vector indicating which perpendicular width segment each width_names entry corresponds to, reported as a percentage along an animal's total length (i.e., 5 for "5%", etc.)

summary.burn

proportion of posterior samples to discard before computing posterior summary statistics

height_ratios

numeric vector used to compute 'body_volume' metric. the 'body_volume' metric assumes the animal's height at a width_increment is the measured width (estimate) times the corresponding entry in height_ratios. By default, all height_ratios are assumed to equal 1, which reflects a default assumption that an animal's vertical cross sections are circular rather than elliptical.

metric

Character vector of the body condition metrics to compute

Value

outputs a list with five elements:

surface_area

a list containing the surface area samples and summaries for each Subject

body_area_index

a list containing the body area index samples and summaries for each Subject

body_volume

a list containing the body volume samples and summaries for each Subject

standardized_widths

a list containing the standardized width samples and summaries for each Subject

summaries

a list for each body condition metric containing summaries for each Subject

Examples

library(stringr)
library(dplyr)

#
# parse data for Xcertainty
#

data("calibration2")
data("body_condition_measurements")

body_condition_measurements <- body_condition_measurements %>% 
  select(!c(TL.10.0..Width, TL.15.0..Width, TL.5.0..Width, TL.90.0..Width,
            TL.95.0..Width))

# parse calibration study
calibration_data = parse_observations(
  x = calibration2, 
  subject_col = 'L_train',
  meas_col = 'RRR.pix', 
  tlen_col = 'L_train', 
  image_col = 'Images', 
  barometer_col = 'Baro...Ht',
  laser_col = 'Laser_Alt', 
  flen_col = 'Focal.length', 
  iwidth_col = 'Iw', 
  swidth_col = 'Sw',
  uas_col = 'Aircraft'
)

# identify the width columns in the dataset
width_names = grep(
  pattern = 'TL\\..*', 
  x = colnames(body_condition_measurements),
  value = TRUE
)

# parse whale data
whale_data = parse_observations(
  x = body_condition_measurements, #[1:5,], 
  subject_col = 'Animal_ID', 
  meas_col = c('TL', width_names), 
  image_col = 'Image', 
  barometer_col = 'BaroAlt',
  laser_col = 'LaserAlt', 
  flen_col = 'Focal_Length', 
  iwidth_col = 'Iw', 
  swidth_col = 'Sw', 
  uas_col = 'Aircraft', 
  alt_conversion_col = 'BaroAlt'
)

#
# fit a basic model or load model output
# 

if(interactive()) {
  
  # build sampler
  sampler = independent_length_sampler(
    data = combine_observations(calibration_data, whale_data),
    priors = list(
      image_altitude = c(min = 0.1, max = 130),
      altimeter_bias = rbind(
        data.frame(altimeter = 'Barometer', mean = 0, sd = 1e2),
        data.frame(altimeter = 'Laser', mean = 0, sd = 1e2)
      ),
      altimeter_variance = rbind(
        data.frame(altimeter = 'Barometer', shape = .01, rate = .01),
        data.frame(altimeter = 'Laser', shape = .01, rate = .01)
      ),
      altimeter_scaling = rbind(
        data.frame(altimeter = 'Barometer', mean = 1, sd = 1e1),
        data.frame(altimeter = 'Laser', mean = 1, sd = 1e1)
      ),
      pixel_variance = c(shape = .01, rate = .01),
      object_lengths = c(min = .01, max = 20)
    )
  )
  
  # run sampler
  body_condition_measurement_estimates = sampler(niter = 1e4, thin = 100)
  
} else {
  data("body_condition_measurement_estimates")
}


#
# post-process data
#

# enumerate the width locations along the animal's length
width_increments = as.numeric(
  str_extract(
    string = width_names, 
    pattern = '[0-9]+'
  )
)

# compute body condition scores
body_condition_output = body_condition(
  data = whale_data, 
  output = body_condition_measurement_estimates,
  length_name = 'TL',
  width_names = width_names,
  width_increments = width_increments,
  summary.burn = .5
)


body_condition_output$summaries

Sample MCMC output

Description

Posterior estimates for lengths and widths of a whale. See help("body_condition") for computation details.

Usage

body_condition_measurement_estimates

Format

A list with 5 elements:

altimeters

Posterior samples and summaries for altimeters

images

Posterior samples and summaries for images

pixel_error

Posterior samples and summaries for pixel error component of measurement error model

objects

Posterior samples and summaries for unknown object lengths that were estimated

summaries

data.frames with posterior summaries, collated from all other list elements.

Humpback whale measurement data from Duke University's Marine Robotics and Remote Sensing (MaRRS) Lab

Description

Photogrammetric measurements of humpback whales to estimate total body length and body condition.

Usage

body_condition_measurements

Format

A data frame with 29 rows and 28 columns:

Animal_ID

unique ID for the individual whale

TL

total body length measurement (m)

TL.10.0..Width

Width of whale (m), pre-computed from pixels using the reported laser altimeter measurement. Width is taken at a cross-section perpendicular to the whale's center line, running from the middle of the rostrum (loosely, the whale's beak/nose) to the middle of the peduncle (the point where the tail connects to the rest of the body). The cross-section is taken 10 from the animal's rostrum to its peduncle.

TL.15.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 15 to its peduncle.

TL.20.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 20 to its peduncle.

TL.25.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 25 to its peduncle.

TL.30.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 30 to its peduncle.

TL.35.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 35 to its peduncle.

TL.40.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 40 to its peduncle.

TL.45.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 45 to its peduncle.

TL.50.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 50 to its peduncle.

TL.55.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 55 to its peduncle.

TL.60.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 60 to its peduncle.

TL.65.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 65 to its peduncle.

TL.70.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 70 to its peduncle.

TL.75.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 75 to its peduncle.

TL.80.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 80 to its peduncle.

TL.85.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 85 to its peduncle.

TL.90.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 90 to its peduncle.

TL.95.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 95 to its peduncle.

TL.5.0..Width

Same as TL.10.0..Width, but taken at a cross-section that is 5 to its peduncle.

Image

image name

BaroAlt

the barometer altitude adjusted for the launch height of the drone

LaserAlt

the altitude recorded by the laser (LiDAR) altimeter

Focal_Length

focal length of the camera (mm)

Iw

image width (px)

Sw

sensor width (mm)

Aircraft

the unoccupied aircraft system (UAS), or drone, used in data collection

Source

<https://doi.org/10.3389/fmars.2021.749943>

Break function (required in models)

Description

Implements Heaviside step function for use in nimble models, H(B) = 1 if B <= delta. For internal use only. Not intended to be called directly by users.

Usage

breakFun(B, delta)

Arguments

B

argument to evaluate function at

delta

breakpoint location

Value

1 if B <= delta, and 0 otherwise

Examples

breakFun(B = 1, delta = 0)

Calibration (training) data

Description

Photogrammetric measurements of known-sized calibration objects to be used as training data.

Usage

calibration

Format

A data frame with 657 rows and 10 columns:

CO.ID

the calibration object ID in training data

Lpix

length measurement (px)

CO.L

the true length of the calibration object (m)

image

image name

Baro_Alt

the barometer altitude adjusted for the launch height of the drone: Baro_raw + Launch_Ht

Laser_Alt

the altitude recorded by the laser (LiDAR) altimeter

Focal_Length

focal length of the camera (mm)

Iw

image width (px)

Sw

sensor width (mm)

uas

the unoccupied aircraft system (UAS), or drone, used in data collection

Source

<https://doi.org/10.1111/gcb.17366>

Calibration (training) data from Duke University's Marine Robotics and Remote Sensing (MaRRS) Lab

Description

Photogrammetric measurements of known-sized calibration objects to be used as training data.

Usage

calibration2

Format

A data frame with 46 rows and 9 columns:

L_train

the true length of the calibration object (m)

RRR.pix

length measurement (px)

Images

image name

Baro...Ht

the barometer altitude adjusted for the launch height of the dronet

Laser_Alt

the altitude recorded by the laser (LiDAR) altimeter

Focal.length

focal length of the camera (mm)

Iw

image width (px)

Sw

sensor width (mm)

Aircraft

the unoccupied aircraft system (UAS), or drone, used in data collection

Source

<https://doi.org/10.3389/fmars.2021.749943>

MCMC sampler for calibration data

Description

Build an MCMC sampler that only uses calibration data to estimate measurement error parameters

Usage

calibration_sampler(data, priors, package_only = FALSE)

Arguments

data

Photogrammetric data formatted for Xcertainty models, required to be an object with class obs.parsed, which can be obtained by running parse_observations()

priors

list with components that define the model's prior distribution. See help("flatten_data") for more details.

package_only

TRUE to return the formatted data used to build the sampler, otherwise FALSE to return the sampler

Value

outputs a function to run a sampler, the function arguments are:

niter

set the number of iterations

burn

set the number samples to discard

thin

set the thinning rate

Examples

# load example wide-format data
data("calibration")

# parse calibration study
calibration_data = parse_observations(
  x = calibration, 
  subject_col = 'CO.ID',
  meas_col = 'Lpix', 
  tlen_col = 'CO.L', 
  image_col = 'image', 
  barometer_col = 'Baro_Alt',
  laser_col = 'Laser_Alt', 
  flen_col = 'Focal_Length', 
  iwidth_col = 'Iw', 
  swidth_col = 'Sw',
  uas_col = 'uas'
)

# build sampler
sampler_data = calibration_sampler(
  data = calibration_data,
  priors = list(
    image_altitude = c(min = 0.1, max = 130),
    altimeter_bias = rbind(
      data.frame(altimeter = 'Barometer', mean = 0, sd = 1e2),
      data.frame(altimeter = 'Laser', mean = 0, sd = 1e2)
    ),
    altimeter_variance = rbind(
      data.frame(altimeter = 'Barometer', shape = .01, rate = .01),
      data.frame(altimeter = 'Laser', shape = .01, rate = .01)
    ),
    altimeter_scaling = rbind(
      data.frame(altimeter = 'Barometer', mean = 1, sd = 1e1),
      data.frame(altimeter = 'Laser', mean = 1, sd = 1e1)
    ),
    pixel_variance = c(shape = .01, rate = .01)
  ),
  # set to false to return sampler function
  package_only = TRUE
)

Calibration (training) data for gray whale example

Description

Photogrammetric measurements of known-sized calibration objects to be used as training data.

Usage

co_data

Format

A data frame with 118 rows and 15 columns:

uas

the unoccupied aircraft system (UAS), or drone, used in data collection

CO.ID

the calibration object ID in training data

CO.L

the true length of the calibration object (m)

year

Year

image

image name

date

Date

Sw

sensor width (mm)

Iw

image width (px)

Focal_Length

focal length of the camera (mm)

Focal_Length_adj

the adjusted focal length (mm) to account for internal processing that corrects for barrel distortion

Baro_raw

raw altitude recorded by the barometer altimeter

Launch_Ht

the launch height of the drone

Baro_Alt

the barometer altitude adjusted for the launch height of the drone: Baro_raw + Launch_Ht

Laser_Alt

the altitude recorded by the laser (LiDAR) altimeter

Lpix

length measurement (px)

Source

<https://doi.org/10.1139/dsa-2023-0051>

Combine parsed observations into a single parsed object

Description

Combine parsed observations, such as calibration and observation (whale) data into a single parsed object. This combined, single parsed object can then be used as the data input for one of the samplers.

Usage

combine_observations(...)

Arguments

...

Parsed datasets to combine (i.e., outputs from Xcertainty::parsed_observations)

Value

outputs a list with four elements:

pixel_counts

a tibble containing the measurements in pixels linked with Subject, Measurement description, Image, and the Timepoint

training_objects

a tibble containing the Subject, Measurement, Length, and Timepoint. NULL if no training objects were included

prediction_objects

a tibble containing the Subject, Measurement, and Timepoint. NULL if no prediction data included

image_info

a tibble containing the Image, Barometer, Laser, FocalLength, ImageWidth, SensorWidth, and UAS

Examples

# load example wide-format data
data("calibration")
data("whales")

# parse calibration study
calibration_data = parse_observations(
  x = calibration, 
  subject_col = 'CO.ID',
  meas_col = 'Lpix', 
  tlen_col = 'CO.L', 
  image_col = 'image', 
  barometer_col = 'Baro_Alt',
  laser_col = 'Laser_Alt', 
  flen_col = 'Focal_Length', 
  iwidth_col = 'Iw', 
  swidth_col = 'Sw',
  uas_col = 'uas'
)

# parse field study
whale_data = parse_observations(
  x = whales, 
  subject_col = 'whale_ID',
  meas_col = 'TL.pix', 
  image_col = 'Image', 
  barometer_col = 'AltitudeBarometer',
  laser_col = 'AltitudeLaser', 
  flen_col = 'FocalLength', 
  iwidth_col = 'ImageWidth', 
  swidth_col = 'SensorWidth', 
  uas_col = 'UAS',
  timepoint_col = 'year'
)

# combine parsed calibration and observation (whale) data
combined_data = combine_observations(calibration_data, whale_data)

Reformat photogrammetric data for model-based analysis

Description

For internal use only. Not intended to be called directly by users.

Usage

flatten_data(
  data = NULL,
  priors,
  pixel_counts = data$pixel_counts,
  training_objects = data$training_objects,
  image_info = data$image_info,
  prediction_objects = data$prediction_objects
)

Arguments

data

A list object, or similar that includes components that describe observations to analyze. Components are automatically extracted into this function's other arguments. See the remaining documentation for details about required components.

priors

list with elements altitude, lengths, bias, and sigma that parameterize the prior distributions for the Bayesian model. The bias components may specify separate priors for each UAS/altimeter type combination, or for all barometers at once based on the information provided for joining.

pixel_counts

data.frame with columns Subject, Measurement, Image, and PixelCount that describe the length measurements taken from images

training_objects

data.frame with columns Subject, Measurement, and Length that describe the known lengths of the objects used to calibrate the photogrammetric model

image_info

data.frame with columns Image, Barometer, Laser, FocalLength, ImageWidth, and SensorWidth that describe the images used in the photogrammetric study

prediction_objects

data.frame with elements Subject, Measurement, and Timepoint that describe the unknown lengths of objects that should be estimated

Details

Assemble data.frame objects into a format that can be analyzed using numerical methods. This function is analagous to stats::model.matrix, which generates design matrices for models that are specified via formulas.

Examples

# load example wide-format data
data("calibration")
data("whales")

# parse calibration study
calibration_data = parse_observations(
  x = calibration, 
  subject_col = 'CO.ID',
  meas_col = 'Lpix', 
  tlen_col = 'CO.L', 
  image_col = 'image', 
  barometer_col = 'Baro_Alt',
  laser_col = 'Laser_Alt', 
  flen_col = 'Focal_Length', 
  iwidth_col = 'Iw', 
  swidth_col = 'Sw',
  uas_col = 'uas'
)

# parse field study
whale_data = parse_observations(
  x = whales, 
  subject_col = 'whale_ID',
  meas_col = 'TL.pix', 
  image_col = 'Image', 
  barometer_col = 'AltitudeBarometer',
  laser_col = 'AltitudeLaser', 
  flen_col = 'FocalLength', 
  iwidth_col = 'ImageWidth', 
  swidth_col = 'SensorWidth', 
  uas_col = 'UAS',
  timepoint_col = 'year'
)

# combine parsed calibration and observation (whale) data
combined_data = combine_observations(calibration_data, whale_data)

MCMC sampler for measurements of individuals with replicates and age information to generate growth curve

Description

Build an MCMC sampler that uses calibration data to estimate the total length of animals. The total lengths are assumed to follow a growth curve model, so replicates across time points that include age information are required to fit the model. The length model is a von-Bertalanffy-Putter growth model, following Pirotta & Bierlich et al., (in revision).

Usage

growth_curve_sampler(data, priors, subject_info, package_only = FALSE)

Arguments

data

Photogrammetric data formatted for Xcertainty models, required to be an object with class obs.parsed, which can be obtained by running parse_observations()

priors

list with components that define the model's prior distribution. See help("flatten_data") for more details.

subject_info

data.frame with elements Year, Subject, Group, ObservedAge, and AgeType. See help("whale_info") for descriptions of data.frame columns.

package_only

TRUE to return the formatted data used to build the sampler, otherwise FALSE to return the sampler

Value

outputs a function to run a sampler, the function arguments are:

niter

set the number of iterations

burn

set the number samples to discard

thin

set the thinning rate

Examples

# load example wide-format data
data("calibration")
data("whales")
data("whale_info")

# parse calibration study
calibration_data = parse_observations(
  x = calibration, 
  subject_col = 'CO.ID',
  meas_col = 'Lpix', 
  tlen_col = 'CO.L', 
  image_col = 'image', 
  barometer_col = 'Baro_Alt',
  laser_col = 'Laser_Alt', 
  flen_col = 'Focal_Length', 
  iwidth_col = 'Iw', 
  swidth_col = 'Sw',
  uas_col = 'uas'
)

# parse field study
whale_data = parse_observations(
  x = whales, 
  subject_col = 'whale_ID',
  meas_col = 'TL.pix', 
  image_col = 'Image', 
  barometer_col = 'AltitudeBarometer',
  laser_col = 'AltitudeLaser', 
  flen_col = 'FocalLength', 
  iwidth_col = 'ImageWidth', 
  swidth_col = 'SensorWidth', 
  uas_col = 'UAS',
  timepoint_col = 'year'
)

# build sampler
sampler_data = growth_curve_sampler(
  data = combine_observations(calibration_data, whale_data),
  priors = list(
    image_altitude = c(min = 0.1, max = 130),
    altimeter_bias = rbind(
      data.frame(altimeter = 'Barometer', mean = 0, sd = 1e2),
      data.frame(altimeter = 'Laser', mean = 0, sd = 1e2)
    ),
    altimeter_variance = rbind(
      data.frame(altimeter = 'Barometer', shape = .01, rate = .01),
      data.frame(altimeter = 'Laser', shape = .01, rate = .01)
    ),
    altimeter_scaling = rbind(
      data.frame(altimeter = 'Barometer', mean = 1, sd = 1e1),
      data.frame(altimeter = 'Laser', mean = 1, sd = 1e1)
    ),
    pixel_variance = c(shape = .01, rate = .01),
    # priors from Agbayani et al. 
    zero_length_age = c(mean = -5.09, sd = 0.4),
    growth_rate = c(mean = .18, sd = .01),
    # additional priors
    group_asymptotic_size = rbind(
      Female = c(mean = 12, sd = .5),
      Male = c(mean = 12, sd = .5)
    ),
    group_asymptotic_size_trend = rbind(
      Female = c(mean = 0, sd = 1),
      Male = c(mean = 0, sd = 1)
    ),
    subject_group_distribution = c(Female = .5, Male = .5),
    asymptotic_size_sd = c(min = 0, max = 10),
    min_calf_length = 3.5,
    # To model break points between 1990 and 2015
    group_size_shift_start_year = c(min = 1990, max = 2015)
  ),
  subject_info = whale_info,
  # set to false to return sampler function
  package_only = TRUE
)

Gray whale measurement data

Description

An example dataset of gray whale measurements from drone-based photogrammetry.

Usage

gw_data

Format

A tibble with 15 rows and 34 columns:

whale_ID

unique individual

image

image name

year

Year

DOY

Day of Year

uas

the unoccupied aircraft system (UAS), or drone, used in data collection

Focal_Length

focal length of the camera (mm)

Focal_Length_adj

the adjusted focal length (mm) to account for internal processing that corrects for barrel distortion

Sw

sensor width (mm)

Iw

image width (px)

Baro_raw

raw altitude recorded by the barometer altimeter

Launch_Ht

the launch height of the drone

Baro_Alt

the barometer altitude adjusted for the launch height of the drone: Baro_raw + Launch_Ht

Laser_Alt

the altitude recorded by the laser (LiDAR) altimeter

CO.ID

the calibration object ID in training data

TL_px

total body length measurement (px)

TL_w05.00_px

Body width measurement (px) at 5% of total length

TL_w10.00_px

Body width measurement (px) at 10% of total length

TL_w15.00_px

Body width measurement (px) at 15% of total length

TL_w20.00_px

Body width measurement (px) at 20% of total length

TL_w25.00_px

Body width measurement (px) at 25% of total length

TL_w30.00_px

Body width measurement (px) at 30% of total length

TL_w35.00_px

Body width measurement (px) at 35% of total length

TL_w40.00_px

Body width measurement (px) at 40% of total length

TL_w45.00_px

Body width measurement (px) at 45% of total length

TL_w50.00_px

Body width measurement (px) at 50% of total length

TL_w55.00_px

Body width measurement (px) at 55% of total length

TL_w60.00_px

Body width measurement (px) at 60% of total length

TL_w65.00_px

Body width measurement (px) at 65% of total length

TL_w70.00_px

Body width measurement (px) at 70% of total length

TL_w75.00_px

Body width measurement (px) at 75% of total length

TL_w80.00_px

Body width measurement (px) at 80% of total length

TL_w85.00_px

Body width measurement (px) at 85% of total length

TL_w90.00_px

Body width measurement (px) at 90% of total length

TL_w95.00_px

Body width measurement (px) at 95% of total length

Source

<https://mmi.oregonstate.edu/gemm-lab>

MCMC sampler for individuals with independent measurements.

Description

Build an MCMC sampler that uses calibration data to estimate independent, unknown measurements. This model assumes all Subject/Measurement/Timepoint combinations are independent. So, this sample is well suited for data containing individuals that either have no replicate samples or have replicate samples that are independent over time, such as body condition which can increase or decrease over time, as opposed to length which should be stable or increase over time. It can also be used to estimate lengths when there are replicate measurements. However, since the model assumes all Subject/Measurement/Timepoint combinations are independent, no strength will be borrowed across temporal replication of a subject's measurements, for example.

Usage

independent_length_sampler(data, priors, package_only = FALSE)

Arguments

data

Photogrammetric data formatted for Xcertainty models, required to be an object with class obs.parsed, which can be obtained by running parse_observations()

priors

list with components that define the model's prior distribution. See help("flatten_data") for more details.

package_only

TRUE to return the formatted data used to build the sampler, otherwise FALSE to return the sampler

Value

outputs a function to run a sampler, the function arguments are:

niter

set the number of iterations

burn

set the number samples to discard

thin

set the thinning rate

Examples

# load example wide-format data
data("calibration")
data("whales")
data("whale_info")

# parse calibration study
calibration_data = parse_observations(
  x = calibration, 
  subject_col = 'CO.ID',
  meas_col = 'Lpix', 
  tlen_col = 'CO.L', 
  image_col = 'image', 
  barometer_col = 'Baro_Alt',
  laser_col = 'Laser_Alt', 
  flen_col = 'Focal_Length', 
  iwidth_col = 'Iw', 
  swidth_col = 'Sw',
  uas_col = 'uas'
)

# parse field study
whale_data = parse_observations(
  x = whales, 
  subject_col = 'whale_ID',
  meas_col = 'TL.pix', 
  image_col = 'Image', 
  barometer_col = 'AltitudeBarometer',
  laser_col = 'AltitudeLaser', 
  flen_col = 'FocalLength', 
  iwidth_col = 'ImageWidth', 
  swidth_col = 'SensorWidth', 
  uas_col = 'UAS',
  timepoint_col = 'year'
)

# build sampler
sampler_data = independent_length_sampler(
  data = combine_observations(calibration_data, whale_data),
  priors = list(
    image_altitude = c(min = 0.1, max = 130),
    altimeter_bias = rbind(
      data.frame(altimeter = 'Barometer', mean = 0, sd = 1e2),
      data.frame(altimeter = 'Laser', mean = 0, sd = 1e2)
    ),
    altimeter_variance = rbind(
      data.frame(altimeter = 'Barometer', shape = .01, rate = .01),
      data.frame(altimeter = 'Laser', shape = .01, rate = .01)
    ),
    altimeter_scaling = rbind(
      data.frame(altimeter = 'Barometer', mean = 1, sd = 1e1),
      data.frame(altimeter = 'Laser', mean = 1, sd = 1e1)
    ),
    pixel_variance = c(shape = .01, rate = .01),
    object_lengths = c(min = .01, max = 20)
  ),
  # set to false to return sampler function
  package_only = TRUE
)

MCMC sampler for measurements of individuals with replicates but no age information.

Description

Build an MCMC sampler that uses calibration data to estimate measurements that are assumed to be non-decreasing in time. This sampler is well suited for when individuals have replicate measurements across time points but do not have age information. The model estimates changes in unique combinations of Subject/Measurement pairs over Timepoints.

Usage

nondecreasing_length_sampler(data, priors, package_only = FALSE)

Arguments

data

Photogrammetric data formatted for Xcertainty models, required to be an object with class obs.parsed, which can be obtained by running parse_observations()

priors

list with components that define the model's prior distribution. See help("flatten_data") for more details.

package_only

TRUE to return the formatted data used to build the sampler, otherwise FALSE to return the sampler

Value

outputs a function to run a sampler, the function arguments are:

niter

set the number of iterations

burn

set the number samples to discard

thin

set the thinning rate

Examples

# load example wide-format data
data("calibration")
data("whales")
data("whale_info")

# parse calibration study
calibration_data = parse_observations(
  x = calibration, 
  subject_col = 'CO.ID',
  meas_col = 'Lpix', 
  tlen_col = 'CO.L', 
  image_col = 'image', 
  barometer_col = 'Baro_Alt',
  laser_col = 'Laser_Alt', 
  flen_col = 'Focal_Length', 
  iwidth_col = 'Iw', 
  swidth_col = 'Sw',
  uas_col = 'uas'
)

# parse field study
whale_data = parse_observations(
  x = whales, 
  subject_col = 'whale_ID',
  meas_col = 'TL.pix', 
  image_col = 'Image', 
  barometer_col = 'AltitudeBarometer',
  laser_col = 'AltitudeLaser', 
  flen_col = 'FocalLength', 
  iwidth_col = 'ImageWidth', 
  swidth_col = 'SensorWidth', 
  uas_col = 'UAS',
  timepoint_col = 'year'
)

# build sampler
sampler_data = nondecreasing_length_sampler(
  data = combine_observations(calibration_data, whale_data),
  priors = list(
    image_altitude = c(min = 0.1, max = 130),
    altimeter_bias = rbind(
      data.frame(altimeter = 'Barometer', mean = 0, sd = 1e2),
      data.frame(altimeter = 'Laser', mean = 0, sd = 1e2)
    ),
    altimeter_variance = rbind(
      data.frame(altimeter = 'Barometer', shape = .01, rate = .01),
      data.frame(altimeter = 'Laser', shape = .01, rate = .01)
    ),
    altimeter_scaling = rbind(
      data.frame(altimeter = 'Barometer', mean = 1, sd = 1e1),
      data.frame(altimeter = 'Laser', mean = 1, sd = 1e1)
    ),
    pixel_variance = c(shape = .01, rate = .01),
    object_lengths = c(min = .01, max = 20)
  ),
  # set to false to return sampler function
  package_only = TRUE
)

Pre-process training and experimental data from wide-format to long-format

Description

Photogrammetric data are often recorded in a wide-format data.frame, in which each row contains all measurement information for a single animal. The row contains the image information (i.e., observed altitude and sensor information) as well as all measurements for a given subject. This function parses the wide-format data into a normalized list of data.frame objects that separately describe the image and measurement data. This function can process observations of calibration data as well as experimental data.

Usage

parse_observations(
  x,
  subject_col,
  meas_col,
  tlen_col = NULL,
  image_col,
  barometer_col = NULL,
  laser_col = NULL,
  flen_col,
  iwidth_col,
  swidth_col,
  uas_col,
  timepoint_col = NULL,
  alt_conversion_col = NULL
)

Arguments

x

Wide-format data.frame describing images and measurements

subject_col

column name in x for subject IDs

meas_col

character vector of column names in x with pixel-counts for each measurement of a subject

tlen_col

column name in x with the true length value (i.e., in meters) of a measurement; primarily used to specify the true length value for an observation of a calibration object. If NULL, then no true length will be associated with the measurement.

image_col

column name in x containing names of images from which measurements are taken

barometer_col

column name in x with Barometer altimeter values

laser_col

column name in x with Laser altimeter values

flen_col

column name in x with camera focal lengths (mm)

iwidth_col

column name in x with image widths (pixels)

swidth_col

column name in x with camera sensor widths (mm)

uas_col

column names in x with UAS name or ID

timepoint_col

column name in x with a timepoint value of a measurement. If NULL, then all measurements are assumed to be at the same timepoint, or equivalently, that time does not matter for the analysis

alt_conversion_col

if not NULL, column name in x with an altitude used to convert measurement columns from lengths to pixels

Value

outputs a list with four elements:

pixel_counts

a tibble containing the measurements in pixels linked with Subject, Measurement description, Image, and the Timepoint

training_objects

a tibble containing the Subject, Measurement, Length, and Timepoint. NULL if no training objects were included

prediction_objects

a tibble containing the Subject, Measurement, and Timepoint. NULL if no prediction data included

image_info

a tibble containing the Image, Barometer, Laser, FocalLength, ImageWidth, SensorWidth, and UAS

Examples

# load example wide-format data
data("calibration")
data("whales")

# parse calibration study
calibration_data = parse_observations(
  x = calibration, 
  subject_col = 'CO.ID',
  meas_col = 'Lpix', 
  tlen_col = 'CO.L', 
  image_col = 'image', 
  barometer_col = 'Baro_Alt',
  laser_col = 'Laser_Alt', 
  flen_col = 'Focal_Length', 
  iwidth_col = 'Iw', 
  swidth_col = 'Sw',
  uas_col = 'uas'
)

# parse field study
whale_data = parse_observations(
  x = whales, 
  subject_col = 'whale_ID',
  meas_col = 'TL.pix', 
  image_col = 'Image', 
  barometer_col = 'AltitudeBarometer',
  laser_col = 'AltitudeLaser', 
  flen_col = 'FocalLength', 
  iwidth_col = 'ImageWidth', 
  swidth_col = 'SensorWidth', 
  uas_col = 'UAS',
  timepoint_col = 'year'
)

# combine parsed calibration and observation (whale) data
combined_data = combine_observations(calibration_data, whale_data)

Gray whale metadata

Description

Gray whale information and metadata that pairs with 'whales' data by "Subject"

Usage

whale_info

Format

A data frame with 293 rows and 5 columns:

Year

year

Subject

unique ID for individuals

Group

sex; Male, Female (F), or NA

ObservedAge

age in years

AgeType

either 'known age' if individual was seen as a calf, or 'min age' from the date of date sighting

Source

<https://doi.org/10.1111/gcb.17366>

Gray whale metadata

Description

Gray whale information and metadata that pairs with 'whales' data by "Subject"

Usage

whales

Format

A data frame with 826 rows and 14 columns:

whale_ID

unique individual

sex

Female, Male, or NA

Age

age in years

AgeType

either 'known age' if individual was seen as a calf, or 'min age' from the date of date sighting

year

Year

date

Date

Image

image name

AltitudeBarometer

the barometer altitude adjusted for the launch height of the drone

AltitudeLaser

the altitude recorded by the laser (LiDAR) altimeter

FocalLength

focal length of the camera (mm)

ImageWidth

image width (px)

SensorWidth

sensor width (mm)

UAS

the unoccupied aircraft system (UAS), or drone, used in data collection

TL.pix

the total body length measurement in pixels

Source

<https://doi.org/10.1111/gcb.17366>