Package 'sdmEvalToolCore'

Title: SDM Evaluation Tool Core Functions
Description: The goal of sdmEvalToolCore is to implement the data model and common non-interactive functionality for the SDM Evaluation Tool packages.
Authors: Peter Solymos [aut, cre] (ORCID: <https://orcid.org/0000-0001-7337-1740>), Steffi LaZerte [aut] (ORCID: <https://orcid.org/0000-0002-7690-8360>), Analythium Solutions Inc. [cph], His Majesty the King in Right of Canada as represented by the Minister of the Environment [cph] (Copyright holder for default evaluation/drill down questions.), Biodiversity Pathways [cph] (Copyright holder for glossary.csv, and default evaluation/drill down questions.), Alberta Biodiversity Monitoring Institute [cph] (Copyright holder for glossary.csv, and default evaluation/drill down questions.)
Maintainer: Peter Solymos <[email protected]>
License: Apache License 2.0
Version: 0.0.1
Built: 2026-10-01 07:39:48 UTC
Source: https://github.com/LandSciTech/sdmEvaluationTool

Help Index

Check Table

Description

Check Table

Usage

check_table(x, table_name, dryrun = FALSE)

Arguments

x

A data frame.
table_name

Table name.
dryrun

Logical, if checks fail and error is produced, unless it is a dry run.

Value

Invisible TRUE if all check passed.

Examples

users <- data.frame(
    user_id = c("holden", "draper", "okoye"),
    user_name = c("James Holden", "Bobbie Draper", "Elvi Okoye"),
    user_email = c(
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ),
    user_affiliation = c("Rocinante", "MCRN", "RCE"),
    admin = c(TRUE, FALSE, FALSE),
    password = c("pass1", "pass2", "pass3")
)
check_table(users, "users")

models <- data.frame(
    model_id = "bam_v5_can71",
    model_name = "BAM v5 Can 71",
    model_description = "BAM version 5 Canada model in BCR 71"
)
check_table(models, "models")

check_table(models, "users", dryrun = TRUE)

Join questions and follow-ups

Description

Join questions and follow-ups

Usage

combine_questions(q)

Arguments

q

A data frame with questions.

Examples

q <- sdmEvalToolCore::default_questions
q$followup_level[5] <- 3
combine_questions(q)

Components

Description

Components

Usage

components

Format

A data frame with component configuration (some columns are lists).

Connect to Database

Description

Connect to Database

Usage

db_connect(dbname = NULL, ...)

Arguments

dbname

DB name.
...

Arguments passed to DBI::dbConnect().

Value

A database connection.

Create DB tables

Description

Create DB tables

Usage

db_create_tables(con, tables = NULL, force = FALSE)

Arguments

con

DB connection.
tables

Character, table name.
force

Logical, force (create even if not exists).

Examples

con <- db_connect(":memory:")
db_create_tables(con, "models")
db_create_tables(con)
db_disconnect(con)

Disconnect from Database

Description

Disconnect from Database

Usage

db_disconnect(con, ...)

Arguments

con

DB connection.
...

Arguments passed to DBI::dbDisconnect().

Path to Database

Description

Path to Database

Usage

db_path()

Value

Path to default database

Get Comments from DB

Description

Get Comments from DB

Usage

db_read_comments(con, deployment_id)

Arguments

con

DB connection.
deployment_id

Deployment ID.

Value

A data frame with comments for the deployment.

Get Deployment Materials from DB

Description

Get Deployment Materials from DB

Usage

db_read_deployment_materials(con, deployment_id = NULL, user_id = NULL)

Arguments

con

DB connection.
deployment_id

Deployment IDs (multiple permitted).
user_id

User ID.

Value

A data frame with joined deployment materials.

Get Evaluations from DB

Description

Get Evaluations from DB

Usage

db_read_evaluations(con, deployment_id = NULL, user_id = NULL)

Arguments

con

DB connection.
deployment_id

Deployment ID.
user_id

Evaluation create user IDs (multiple allowed).

Value

A data frame with evaluations for the deployment.

Get models from DB

Description

Get models from DB

Usage

db_read_models(con, model_id = NULL)

Arguments

con

DB connection.
model_id

Model ID (optional).

Value

A data frame with models. Optionally filtered to model_id.

Get species from DB

Description

Get species from DB

Usage

db_read_species(con, species_id = NULL)

Arguments

con

DB connection.
species_id

Species ID (optional).

Value

A data frame with species and display names. Optionally filtered to species_id.

Get Table from DB

Description

Get Table from DB

Usage

db_read_table(con, table_name)

Arguments

con

DB connection.
table_name

Table name.

Value

A data frame with the table data.

Get User Info from DB

Description

Get User Info from DB

Usage

db_read_user_info(con, user_id, deployment_id)

Arguments

con

DB connection.
user_id

User ID.
deployment_id

Deployment ID.

Value

A data frame with user info and access roles. The "user_roles" attribute gives the user roles as a vector.

Write Data to an Existing Table

Description

Data will be inserted/updated/upserted in an existing DB table.

Usage

db_write_table(
  con,
  table,
  data,
  mode = c("insert", "update", "upsert"),
  check = TRUE,
  dryrun = FALSE
)

Arguments

con

A database connection.
table

Table name.
data

Data frame to append to the DB table.
mode

How to execute the write operation: insert (append) new record, update existing record, or upsert (update existing or insert if not).
check

Logical, should data be validated?
dryrun

Logical, write to a text file when TRUE and to the database when FALSE.

Value

Invisible TRUE.

Examples

con <- db_connect(":memory:")
db_create_tables(con, "models")
models <- data.frame(
    model_id = "bam_v5_can71",
    model_name = "BAM v5 Can 71",
    model_description = "BAM version 5 Canada model in BCR 71"
)
db_write_table(con, "models", models, mode = "insert")
db_disconnect(con)

Default Questions

Description

Default Questions

Usage

default_questions

Format

A data frame with default questions.

Default Species Table

Description

Default Species Table

Usage

default_species_table_canada()

Value

Data frame.

Examples

str(default_species_table_canada())

Fake DB Entries

Description

Fake DB Entries

Usage

fake_comment(deployment_id, model_id, species_id, user_id, time = NULL)

fake_evaluation(
  deployment_id,
  material_id,
  component_id,
  user_id,
  questions = NULL,
  time = NULL
)

fake_response(question)

Arguments

deployment_id

Deployment ID.
model_id

Model ID.
species_id

Species ID.
user_id

User ID.
time

Date-time.
material_id

Material ID.
component_id

Component ID.
questions

A questions data frame.
question

A questions data frame with a single row.

Examples

fake_comment(
    deployment_id = "deployment1",
    model_id = "model1",
    species_id = "MOTR",
    user_id = "draper")

str(fake_response(sdmEvalToolCore::default_questions[1,]))

fake_evaluation(
    deployment_id = "deployment1",
    material_id = "material1",
    component_id = "model_fit",
    user_id = "draper")

Fields

Description

Fields

Usage

fields

Format

A data frame.

Follow-up Questions

Description

Follow-up Questions

Usage

followup_questions

Format

A data frame with follow-up questions.

Handling Boolean

Description

Handling Boolean

Usage

fromBoolean(x)

Arguments

x

An R vector.

Generate password

Description

Generate password

Usage

generate_password(length = 12, start_with_letter = TRUE)

Arguments

length

Length of the password. Default is 12.
start_with_letter

Logical indicating if the password should start with a letter. Default is TRUE.

Value

A randomly generated password.

Examples

generate_password()

Which Components Are Ready

Description

Which Components Are Ready

Usage

get_comp_ready(ready = character(0L))

Arguments

ready

Character, component names that are ready.

Value

A data frame with components and a column telling which ones are ready. The "percent_ready" attribute gives a percentage value of the mandatory components that are ready.

Examples

r <- get_comp_ready(c("observations", "model_metadata"))
r
attr(r, "percent_ready")

Get Rule for a Component

Description

Get Rule for a Component

Usage

get_comp_rule(component_id, rule_type = c("upload", "display", "evaluation"))

Arguments

component_id

Character, component name (length 1).
rule_type

CHaracter, the type of rule.

Value

A list with the rules, or NULL.

Examples

str(get_comp_rule("observations", "upload"))
str(get_comp_rule("observations", "evaluation"))

Get Table Fields

Description

Get Table Fields

Usage

get_fields(table_name)

Arguments

table_name

Table name.

Value

A data frame.

Examples

get_fields("users")
get_fields("components")

Get File Extension

Description

Get File Extension

Usage

get_file_ext(path)

Arguments

path

Character, a file path.

Value

Lower case file extension as string.

Examples

get_file_ext("bam_v5/oven/observations.parquet")

Get User Roles

Description

Get User Roles

Usage

get_user_roles(role)

Arguments

role

Character, 1 or multiple user roles.

Value

A data frame with the permissible user actions (TRUE/FALSE).

Examples

str(get_user_roles(c("modeler")))
str(get_user_roles(c("evaluator")))
str(get_user_roles(c("evaluator", "modeler")))

Make Directory

Description

Make Directory

Usage

make_dir(path, ...)

Arguments

path

Character, a file path.
...

Arguments passed to dir.create().

Value

Create a directory recursively as a side effect, returning logical indicating the result ().

Make Material ID

Description

Make Material ID

Usage

make_material_id(model_id, species_id, component_id, sep = "_")

Arguments

model_id

Model ID.
species_id

Species ID.
component_id

Component ID.
sep

Character. Separator.

Examples

make_material_id("model1", NA, "predictor_metadata")
make_material_id("model1", "CAWA", "predictor_raster")

Make Target Path

Description

Make Target Path

Usage

make_target_path(path, data = list(), base = NULL)

Arguments

path

Character, a file path.
data

List with name value pairs, the values are substituted into the path according to glue rules (with curly braces).
base

Character, base path, defaults to sdmevaltool_options()$base when NULL.

Value

The path string with data values substituted.

Examples

make_target_path("bam_v5/oven/observations.parquet")
make_target_path("{model}/{species}/observations.parquet",
  list(model = "bam_v5", species = "oven"))
make_target_path("{model}/{species}/observations.parquet",
  list(model = "bam_v5", species = "oven"), ".")

Make user database suitable for shinymanager

Description

Make user database suitable for shinymanager

Usage

make_user_db()

Value

A data frame with user credentials.

Prepare Material Entry

Description

Prepare Material Entry

Usage

prepare_material_entry(
  model_id,
  species_id,
  component_id,
  user_id,
  material_settings = "[]"
)

Arguments

model_id

Model ID.
species_id

Species ID.
component_id

Component ID.
user_id

User ID.
material_settings

Material settings.

Examples

prepare_material_entry("model1", "CAWA", "predictor_raster", "testuser")

Read File

Description

Read File

Usage

read_file(path, ...)

Arguments

path

Character, a file path.
...

Arguments passed to the reader functions.

Value

Return the result from the file.

Scaffold Table

Description

Scaffold Table

Usage

scaffold_table(table_name)

Arguments

table_name

Table name.

Value

A data frame returned invisibly, called for the printed side effects.

Examples

scaffold_table("users")
scaffold_table("materials")

Package Options

Description

Package Options

Usage

sdmevaltool_options(...)

Arguments

...

Names list of options.

Examples

(sdmevaltool_options())

Tables

Description

Tables

Usage

tables

Format

A data frame.

Handling Timestamps

Description

Handling Timestamps

Usage

timestamp_from(ms, tz = NULL, ...)

timestamp_to(dt)

now()

Arguments

ms

Unix time in seconds.
tz

Time zone, when NULL it defaults to sdmevaltool_options()$tz.
...

Other optional arguments passed to as.POSIXct().
dt

POSIXct coercible date/time value.

Value

timestamp_from returns POSIXct().

timestamp_to returns Unix time as character .

See Also

sdmevaltool_options() to set tz globally.

Examples

dt1 <- now()
timestamp_to(dt1)
timestamp_from(timestamp_to(dt1))

Write File and Insert/Update Material DB Entry

Description

Write File and Insert/Update Material DB Entry

Usage

upload_material(
  component_id,
  x,
  model_id,
  species_id,
  user_id,
  deployment_id = NULL,
  material_settings = NULL,
  con = NULL,
  update = FALSE,
  ...
)

Arguments

component_id

Component ID.
x

Object.
model_id

Model ID.
species_id

Species ID.
user_id

User ID.
deployment_id

Deployment ID.
material_settings

List with the material settings.
con

Database connection (use NULL to avoid inserting a record).
update

Logical. Is this a new entry (FALSE, default) or an update (TRUE) to an existing material entry.
...

Arguments passed to the write function.

Prepare Deployment Materials

Description

Prepare Deployment Materials

Usage

prep_deployment_questions(deployment_id, x = NULL, ...)

prep_deployment_settings(deployment_id, x, ...)

prep_deployment_subunits(
  deployment_id,
  x = NULL,
  reference_raster,
  reference_points,
  n = c(20, 20),
  square = TRUE,
  ...
)

Arguments

deployment_id

Deployment ID.
x

An object to upload.
...

Arguments passed to the write function.
reference_raster

Reference raster layer.
reference_points

Reference spatial points object.
n

Number of grid cells in x and y direction.
square

Logical. If 'FALSE“, create hexagonal grid.

Prepare Upload Materials

Description

Prepare Upload Materials

Usage

prep_predictor_raster(
  x,
  resolution = 5,
  model_id,
  user_id,
  material_settings = NULL,
  con = NULL,
  update = FALSE,
  ...
)

prep_predictor_metadata(
  x,
  model_id,
  user_id,
  material_settings = NULL,
  con = NULL,
  update = FALSE,
  ...
)

prep_model_metadata(
  x,
  model_id,
  user_id,
  material_settings = NULL,
  con = NULL,
  update = FALSE,
  ...
)

prep_spatial_prediction(
  x,
  model_id,
  species_id,
  user_id,
  material_settings = NULL,
  con = NULL,
  update = FALSE,
  ...
)

prep_observations(
  x,
  species,
  model_id,
  user_id,
  material_settings = NULL,
  con = NULL,
  update = FALSE,
  ...
)

prep_model_summary(
  x,
  species,
  model_id,
  user_id,
  material_settings = NULL,
  con = NULL,
  update = FALSE,
  ...
)

prep_model_fit(
  x,
  species,
  model_id,
  user_id,
  material_settings = NULL,
  con = NULL,
  update = FALSE,
  ...
)

Arguments

x

An object to upload.
resolution

Raster resampling resolution
model_id

Model ID.
user_id

User ID.
material_settings

Material settings.
con

Database connection (use NULL to avoid inserting new record).
update

Logical. Is this a new entry or an update to an existing one.
...

Arguments passed to the write function.
species_id

Species ID.
species

Reference species table.

User Roles

Description

User Roles

Usage

user_roles

Format

A data frame.

Write File

Description

Write File

Usage

write_file(x, path, ...)

Arguments

x

Object to write.
path

Character, a file path.
...

Arguments passed to the writer functions.

Value

Writes file as a side effect.