Skip to content

DOCS.md

Latest commit

 

History

History
343 lines (246 loc) · 16.1 KB

DOCS.md

File metadata and controls

343 lines (246 loc) · 16.1 KB

bycatch — Interface Reference

Entry points (exported CLI wrappers)

render_potential_kba(options)

Reads a pre-computed GeoPackage file containing potential KBA polygons and saves the resulting map as a PNG file.

  • Parameters:
    • options: named list
      • gpkg-path (character) — path to the input GeoPackage file with KBA polygons.
      • output-path (character) — path where the output PNG plot is saved.
  • Returns: None. Side effect: writes a PNG file to output-path.
  • Notes: The input .gpkg file is produced by create_potential_kba. This function never calls compute_* — it reads the pre-computed artifact, plots, and saves.

render_representative_assessment(options)

Reads a cached RDS file and saves a diagnostic scatterplot with confidence bands and fitted curve as a PNG file.

  • Parameters:
    • options: named list
      • rds-path (character) — path to the cached RDS file with assessment_summary and assessment_detail.
      • output-path (character) — path where the output PNG plot is saved.
  • Returns: None. Side effect: writes a PNG file to output-path.
  • Notes: The input .rds file is produced by create_representative_assessment. The output plot shows inclusion rate vs sample size with a confidence band (meanPred ± est_asym × sdInclude), fitted regression curve, scatter points for individual replicates, and representativeness percentage label. This function never calls compute_* — it reads the pre-computed artifact, plots, and saves.

render_individual_kde(options)

Reads a pre-computed RDS file containing UDPolygons and saves the resulting KDE map as a PNG file.

  • Parameters:
    • options: named list
      • rds-path (character) — path to the input RDS file with UDPolygons.
      • output-path (character) — path where the output PNG plot is saved.
  • Returns: None. Side effect: writes a PNG file to output-path.
  • Notes: The input .rds file is produced by create_individual_kde. This function never calls compute_* — it reads the pre-computed artifact, plots, and saves.

create_trips_summary(options)

Generates a summary of trips from GPS data and configuration, and writes it to a CSV file.

  • Parameters:
    • options: named list
      • config-path (character) — path to the configuration file (JSON).
      • data-path (character) — path to the input GPS data file (CSV).
      • output-path (character) — path where the output CSV summary is saved.
  • Returns: None. Side effect: writes a CSV file to output-path.
  • Notes: The output CSV contains columns tripID, n_locs, departure, return, duration, total_dist.

create_trips(options)

Extracts individual foraging trips from GPS data and writes the result to a CSV file.

  • Parameters:
    • options: named list
      • config-path (character) — path to the configuration file (JSON).
      • data-path (character) — path to the input GPS data file (CSV).
      • output-path (character) — path where the output CSV file is saved.
  • Returns: None. Side effect: writes a CSV file to output-path.
  • Notes: The output CSV contains columns tripID, Latitude, Longitude.

create_filtered_fisheries(options)

Filters raw fisheries GPS data by date range and geographic bounding box, then writes the filtered data to a CSV file.

  • Parameters:
    • options: named list
      • data-path (character) — path to the input fisheries GPS data file (CSV).
      • output-path (character) — path where the filtered output CSV file is saved.
      • start (character) — start date for filtering (inclusive, format YYYY-MM-DD).
      • end (character) — end date for filtering (inclusive, format YYYY-MM-DD).
      • lat-min (numeric) — minimum latitude for filtering.
      • lat-max (numeric) — maximum latitude for filtering.
      • lon-min (numeric) — minimum longitude for filtering.
      • lon-max (numeric) — maximum longitude for filtering.
  • Returns: None. Side effect: writes a CSV file to output-path.

create_filtered_gps_between_dates(options)

Filters GPS data between two inclusive dates and writes the result to a CSV file.

  • Parameters:
    • options: named list
      • data-path (character) — path to the input GPS data file (CSV).
      • output-path (character) — path where the filtered output CSV file is saved.
      • start (character) — start date for filtering (inclusive).
      • end (character) — end date for filtering (inclusive).
      • date-column-name (character) — name of the date column in the input data.
  • Returns: None. Side effect: writes a CSV file to output-path.

create_individual_kde(options)

Reads GPS data, projects tracks, estimates smoothing scale, computes kernel density estimates (KDEs) for each tracked individual, and caches the full result (KDE_surface, UDPolygons, tracks) as an RDS file.

  • Parameters:
    • options: named list
      • config-path (character) — path to the configuration file (JSON).
      • data-path (character) — path to the input GPS data file (CSV).
      • trips-summary-path (character) — path to the trips summary CSV.
      • output-path (character) — path where the output RDS file (*.rds) is saved.
      • percentage-distribution (integer) — percentage contour level for KDE polygons.
  • Returns: None. Side effect: writes an RDS file to output-path containing KDE_surface, UDPolygons, and tracks.

create_potential_kba(options)

Reads a cached RDS file (containing KDE_surface and assessment_summary), identifies potential Key Biodiversity Areas (KBAs), and saves the result as a GeoPackage file. No raw data re-computation is needed.

  • Parameters:
    • options: named list
      • rds-path (character) — path to the cached RDS file with KDE_surface and assessment_summary (must contain out column).
      • output-path (character) — path where the output GeoPackage file (*.gpkg) is saved.
      • percentage-distribution (integer) — percentage contour level for KDE.
      • population-size (integer) — population size for the KBA criterion.
  • Returns: None. Side effect: writes a GeoPackage file to output-path.

create_representative_assessment(options)

Reads a cached RDS file (individual KDE), runs the bootstrap assessment (repAssess), and caches the assessment_summary and assessment_detail as an RDS file.

  • Parameters:
    • options: named list
      • rds-path (character) — path to the cached RDS file with KDE_surface and tracks.
      • percentage-distribution (integer) — percentage contour level for the assessment.
      • n-iterations (integer) — number of bootstrap iterations for the representative assessment.
      • output-path (character) — path where the output RDS file is saved.
  • Returns: None. Side effect: writes an RDS file to output-path containing assessment_summary (data.frame: out, asym, Rep70, Rep95), assessment_detail (data.frame: full iteration table), and KDE_surface.
  • Notes: This is the only function that runs the expensive repAssess bootstrap. Downstream functions read the cached output instead of re-running it.

get_domain_specific_options()

Defines and returns a named list of command-line options for use in CLI tools.

  • Parameters: None.
  • Returns: A named list of command-line options. Names: data-path, config-path, output-path, gpkg-path, rds-path, percentage-distribution, n-iterations, start, end, lat-min, lat-max, lon-min, lon-max, population-size, date-column-name, trips-summary-path.

Plot layer (Level 1 Pure — internal)

plot_representative_assessment(assessment_detail)

Returns a ggplot2 scatterplot of inclusion rate vs sample size from the representative assessment bootstrap iterations.

  • Parameters:
    • assessment_detail (data.frame) — full iteration table with columns SampleSize, InclusionRate, iteration, pred, rep_est, is_rep. Typically loaded from a cached .rds file.
  • Returns: A ggplot2 object.
  • Notes: Level 1 Pure — no I/O, no side effects. Called by render_representative_assessment.

plot_potential_kba(site)

Returns a ggplot2 map of potential Key Biodiversity Area (KBA) polygons.

  • Parameters:
    • site (sf) — polygons object with KBA site data, as returned by compute_potential_kba(). Typically loaded from a .gpkg file.
  • Returns: A ggplot2 object.
  • Notes: Level 1 Pure — no I/O, no side effects. Replaces track2KBA::mapSite — no colony parameter. Called by render_potential_kba.

plot_individual_kde(UDPolygons)

Returns a ggplot2 map of individual kernel density estimate (KDE) polygons.

  • Parameters:
    • UDPolygons (sf) — utilization distribution polygons, as returned by compute_individual_kde(). Typically loaded from a .rds file.
  • Returns: A ggplot2 object.
  • Notes: Level 1 Pure — no I/O, no side effects. Replaces track2KBA::mapKDE — no colony parameter. Called by render_individual_kde.

Compute layer (all functions in R/compute.R)

compute_individual_kde(tracks, levelUD, scale)

Computes kernel density estimates (KDE) for each tracked individual. Wraps track2KBA::estSpaceUse with polyOut=TRUE.

  • Parameters:
    • tracks (SpatialPointsDataFrame) — projected tracking data (from compute_project_returning_tracks).
    • levelUD (numeric) — percentage contour level for KDE polygons.
    • scale (numeric) — smoothing parameter value (Area-Restricted Search scale from compute_scale_parameters).
  • Returns: A list with elements KDE_surface (estUDm), UDPolygons (sf), and tracks (SpatialPointsDataFrame).

compute_representative_assessment(KDE_surface, tracks, levelUD, n_iterations)

Bootstraps across individuals to assess how representative the sample is. Wraps track2KBA::repAssess with bootTable=TRUE. Suppresses the inline base R plot.

  • Parameters:
    • KDE_surface (estUDm) — kernel density estimates from compute_individual_kde.
    • tracks (SpatialPointsDataFrame) — projected tracking data.
    • levelUD (numeric) — percentage contour level.
    • n_iterations (integer) — number of bootstrap iterations.
  • Returns: A list with elements assessment_summary (data.frame, single row with columns out, asym, Rep70, Rep95) and assessment_detail (data.frame, full iteration table).

compute_potential_kba(KDE_surface, represent, popSize, levelUD)

Identifies potential Key Biodiversity Areas (KBAs) based on the representative assessment. Wraps track2KBA::findSite.

  • Parameters:
    • KDE_surface (estUDm) — kernel density estimates.
    • represent (numeric) — representativity value (from assessment_summary$out).
    • popSize (numeric) — population size for the KBA criterion.
    • levelUD (numeric) — percentage contour level.
  • Returns: An sf object with polygon data (columns N_IND, N_animals, potentialSite).
  • Notes: Returns valid geometries — sf::st_make_valid is applied after findSite. This prevents TopologyException crashes downstream in render_potential_kba.

compute_project_returning_tracks(data)

Projects returning-trips GPS data into a spatial data frame. Wraps track2KBA::projectTracks with projType = "azim" and custom = TRUE.

  • Parameters:
    • data (data.frame) — GPS tracking data with a Returns column (returning trips only).
  • Returns: A SpatialPointsDataFrame with projected coordinates.

I/O layer

import_trips(path, filter_returning)

Reads a GPS tracking CSV and optionally filters to returning trips only.

  • Parameters:
    • path (character) — path to the GPS data CSV.
    • filter_returning (logical) — if TRUE (default), only rows with Returns == "Yes" are returned.
  • Returns: A data.frame with GPS tracking data.

import_trips_summary(path)

Reads a trips summary CSV as-is.

  • Parameters:
    • path (character) — path to the trips summary CSV.
  • Returns: A data.frame with trip-level summary columns (tripID, n_locs, departure, return, duration, total_dist, max_dist, direction, complete).

Configuration

import_config(config_path)

Reads a JSON configuration file and returns its content as a list with a parsed colony tibble. Used by create_* and render_* functions.

  • Parameters:
    • config_path (character) — path to the JSON configuration file.
  • Returns: A list with keys: inner_buff (numeric), return_buff (numeric), duration (numeric), lat_colony (numeric), lon_colony (numeric), colony (tibble with columns Longitude, Latitude).
  • Errors: File not found or invalid JSON (delegated to rjson::fromJSON).

Track processing

compute_trips(data, config_content)

Converts raw GPS data into a spatial data frame of individual foraging trips.

  • Parameters:
    • data (data.frame) — raw GPS data with columns name, date, time, longitude, latitude.
    • config_content (list) — configuration list with elements colony (tibble), inner_buff (numeric, km), return_buff (numeric, km), duration (numeric, hours).
  • Returns: A SpatialPointsDataFrame with trip assignments. Each row is a GPS fix annotated with trip ID.
  • Notes: Filters out non-returning trips (rmNonTrip = TRUE). Date-time format is ymd_HMS.

compute_trips_summary(trips, config_content)

Generates a summary table of trip characteristics from a tripSplit output.

  • Parameters:
    • trips (data.frame) — trip data from compute_trips.
    • config_content (list) — configuration list with element colony (tibble).
  • Returns: A data.frame with one row per trip and columns including trip ID, completeness status, and derived metrics.

compute_scale_parameters(tracks, trips_summary)

Computes candidate smoothing parameter values for kernel density estimation. Wraps track2KBA::findScale.

  • Parameters:
    • tracks (SpatialPointsDataFrame) — projected tracking data.
    • trips_summary (data.frame) — trip summary from tripSummary.
  • Returns: A data.frame with candidate smoothing parameter values including scaleARS (Area-Restricted Search scale from First Passage Time analysis), mag (log of median foraging range), href (reference bandwidth), and movement summary columns.

Fisheries data processing

compute_filtered_fisheries_by_date(fisheries_data, start, end)

Filters fisheries data rows within an inclusive date range.

  • Parameters:
    • fisheries_data (data.frame) — fisheries GPS data with column FechaRecepcionUnitrac.
    • start (character) — start date (YYYY-MM-DD, inclusive).
    • end (character) — end date (YYYY-MM-DD, inclusive).
  • Returns: A filtered data.frame with rows whose FechaRecepcionUnitrac falls within [start, end].

compute_filtered_fisheries_by_lat_lon(fisheries_data, lat_min, lat_max, lon_min, lon_max)

Filters fisheries data rows within a geographic bounding box.

  • Parameters:
    • fisheries_data (data.frame) — fisheries GPS data with columns Latitude, Longitude.
    • lat_min (numeric) — minimum latitude.
    • lat_max (numeric) — maximum latitude.
    • lon_min (numeric) — minimum longitude.
    • lon_max (numeric) — maximum longitude.
  • Returns: A filtered data.frame with rows whose coordinates fall within the bounding box.

compute_filtered_fisheries_by_date_and_lat_lon(fisheries_data, start, end, lat_min, lat_max, lon_min, lon_max)

Composes date-range and bounding-box filters on fisheries data.

  • Parameters:
    • fisheries_data (data.frame) — fisheries GPS data.
    • start (character) — start date (YYYY-MM-DD, inclusive).
    • end (character) — end date (YYYY-MM-DD, inclusive).
    • lat_min (numeric) — minimum latitude.
    • lat_max (numeric) — maximum latitude.
    • lon_min (numeric) — minimum longitude.
    • lon_max (numeric) — maximum longitude.
  • Returns: A filtered data.frame satisfying all criteria.

Removed: Track2KBA_Wrapper (R6 class)

The R6 class is replaced by standalone compute_* functions in R/compute.R. State is passed explicitly through parameters rather than stored in an object.