
Workflow for GeoPressureR
Source:R/geopressuretemplate.R, R/geopressuretemplate_config.R, R/geopressuretemplate_graph.R, and 2 more
geopressuretemplate.RdThe geopressuretemplate() function manages the complete workflow for modelling bird
trajectories using geolocator data. It includes the creation of the tag object, the construction of
the likelihood maps (pressure and/or light), the construction of the graph model, and,
finally, the estimation of the trajectory products and the pressure path computation. Read the
Workflow chapter in the GeoPressureManual for more
information.
Usage
geopressuretemplate(
id,
config = config::get(config = id),
quiet = FALSE,
file = glue::glue("./data/interim/{id}.RData"),
...
)
geopressuretemplate_config(
id,
config = config::get(config = id),
assert_tag = TRUE,
assert_graph = FALSE,
...
)
geopressuretemplate_graph(
id,
config = config::get(config = id),
quiet = FALSE,
file = glue::glue("./data/interim/{id}.RData"),
...
)
geopressuretemplate_pressurepath(
id,
config = config::get(config = id),
quiet = FALSE,
file = glue::glue("./data/interim/{id}.RData"),
...
)
geopressuretemplate_tag(
id,
config = config::get(config = id),
quiet = FALSE,
file = glue::glue("./data/interim/{id}.RData"),
...
)Arguments
- id
unique identifier of a tag.
- config
configuration object specifying workflow parameters, which is loaded by default using
config::get(config = id).- quiet
Logical. If
TRUE, suppresses informational messages during execution. The default value isFALSE.- file
A file path to save the intermediate results (e.g., tag, graph, and pressure paths). Default is
./data/interim/{id}.RData.- ...
Additional parameters to overwrite default or config values. Always prefer to modify
config.ymlif possible.- assert_tag
Logical. If
TRUE, check that the config is compatible for the creation of a tag. The default value isTRUE.- assert_graph
Logical. If
TRUE, check that the config is compatible for the creation of a graph. Only used bygeopressuretemplate_config(), where the default value isFALSE(geopressuretemplate_graph()always sets it toTRUE).
Value
geopressuretemplate(), geopressuretemplate_graph() and geopressuretemplate_pressurepath()
return file invisibly and save the processed outputs (tag, paths, pressure paths, etc.) to the
specified file. If the movement model or the outputs fail, geopressuretemplate_graph()
warns with the error and returns the graph computed so far instead, without saving (and
geopressuretemplate() stops before the pressurepath). Use options(warn = 2) to turn this
warning into an error, e.g. in batch runs. geopressuretemplate_tag() returns
the tag invisibly and geopressuretemplate_config() returns the merged configuration list.
Details
The geopressuretemplate function is a high-level entry point that coordinates multiple
steps for processing the geolocator data and producing trajectories. It relies on underlying child
functions for each step:
Tag Creation
geopressuretemplate_tag(): Initializes and labels thetagobject. It also generates light and pressure likelihood maps:
tag_create(): Initializes the tag object.tag_label(): Adds labels.tag_set_map(): Sets the spatial and temporal parameters.If
"map_pressure"is in theconfig$geopressuretemplate$likelihood:geopressure_map(): Computes the pressure likelihood.
If
"map_light"is in theconfig$geopressuretemplate$likelihood:twilight_create() |> twilight_label_read() |> geolight_map(): Computes the light likelihood.
save(): Savestagandparamindata/interim/{id}.RData, replacing the content of the file.
Graph Creation
geopressuretemplate_graph(): Builds a movement model graph based ontagdata, and can include wind effects if specified. Outputs such as marginal distributions, most likely paths, and simulation paths can be computed.
graph_create(): Creates the graph based on tag.If
config$graph_set_movement$type == "gs"(i.e., no wind):graph_set_movement(): Sets the movement model without wind.
If
config$graph_set_movement$type == "as"(i.e., with wind):graph_add_wind(): Adds wind data to the graph.graph_set_movement(): Sets the movement model with wind.
If
"marginal"is inconfig$geopressuretemplate$outputs:graph_marginal(): Computes the marginal distribution map.
If
"most_likely"is inconfig$geopressuretemplate$outputs:graph_most_likely(): Computes the most likely path based on the movement model.
If
"simulation"is inconfig$geopressuretemplate$outputs:graph_simulation(): Runs simulations to model multiple possible paths.
save(): Saves thetag,paramand computed outputs indata/interim/{id}.RData. Other objects already in the file and not derived from the graph (e.g.path_geopressureviz) are kept; outputs derived from a previous graph (paths, edges, marginal and their pressurepaths) are replaced or removed.
Pressure Path Processing
geopressuretemplate_pressurepath(): Computes pressurepaths (pressurepath_create()) using the content of the.RDatafile and appending the pressurepath data.frames to the same file.
For each of "most_likely" and "simulation" listed in
config$geopressuretemplate$pressurepath, computes pressurepath_{type} from path_{type}
and saves it in the same file. A warning is given when a path is missing. For any other path
(e.g. exported from GeoPressureViz), call pressurepath_create() directly.
Each of these child functions can be called individually or automatically as part of
the geopressuretemplate workflow.
Examples
if (FALSE) {
# Run the complete geopressuretemplate workflow
geopressuretemplate("18LX")
# Overwrite parameters passed through ...
geopressuretemplate("18LX",
tag_set_map = list(scale = 2),
geopressure_map = list(max_sample = 100, margin = 20)
)
# Or run step-by-step
# you can check that all the parameters are correctly set in the config file
geopressuretemplate_config("18LX")
# 1. creation of the tag
tag <- geopressuretemplate_tag("18LX")
# 2. creation of the graph
geopressuretemplate_graph("18LX")
# 3. Computation of the pressurepath
geopressuretemplate_pressurepath("18LX")
}