Skip to contents

Query plots from database

query_plots.Rd

This function queries a PostgreSQL inventory database to return a list of forest plots or individuals, with options to include associated traits and metadata, and to generate interactive maps.

Usage

query_plots(
  plot_name = NULL,
  tag = NULL,
  country = NULL,
  locality_name = NULL,
  method = NULL,
  feature_filters = NULL,
  extract_individuals = FALSE,
  map = FALSE,
  id_individual = NULL,
  id_plot = NULL,
  id_tax = NULL,
  id_specimen = NULL,
  interactive = TRUE,
  show_multiple_census = FALSE,
  extract_coordinates = FALSE,
  show_all_coordinates = lifecycle::deprecated(),
  remove_ids = TRUE,
  extract_traits = TRUE,
  extract_individual_features = TRUE,
  traits_to_genera = FALSE,
  wd_fam_level = FALSE,
  include_liana = FALSE,
  extract_subplot_features = TRUE,
  concatenate_stem = FALSE,
  issues = c("remove", "include", "ignore"),
  include_measurement_ids = FALSE,
  exact_match = FALSE,
  census_strategy = c("last", "first", "mean"),
  individual_features_format = c("wide", "long", "census_pairs"),
  output_style = "auto",
  backbone = c("internal", "wcvp"),
  con = NULL,
  con.taxa = NULL,
  verbose = NULL
)

Arguments

plot_name

Optional. A single string specifying plot name.

tag

Optional. Tag identifier.

country

Optional. A single string specifying country.

locality_name

Optional. A single string specifying locality name.

method

Optional. Method identifier.

feature_filters

Optional. Named list for filtering on plot features – the values stored as rows of `data_liste_sub_plots` rather than as columns of `data_liste_plots`. Names are feature types (see [plot_feature_filters()]), values are character vectors, e.g. `list(data_provider = "IRD", principal_investigator = c("Dauby", "Sonke"))`. Values of one feature are combined with OR, different features with AND, so a plot must satisfy every named feature but may do so through different subplot records. Only features whose value reads as text can be used: `character` features and lookup features such as the `table_colnam` people features, whose names are resolved for you. Matching follows `exact_match`. Use [plot_feature_values()] to see what a feature holds.

extract_individuals

Logical. Whether to extract individuals. Optional.

map

Logical. Whether to generate map. Optional.

id_individual

Optional. Individual identifiers.

id_plot

Optional. Plot identifiers.

id_tax

Optional. Taxonomic identifiers.

id_specimen

Optional. Specimen identifiers.

interactive

Logical. Whether the query should be interactive. TRUE by default.

show_multiple_census

Logical. Whether to show multiple census data. Optional.

extract_coordinates

Logical. Whether to extract subplot coordinates as separate tables. When TRUE, returns `coordinates` (raw coordinate data) and `coordinates_sf` (spatial features) in the output list. Default is FALSE.

show_all_coordinates

`r lifecycle::badge("deprecated")` Use `extract_coordinates` instead.

remove_ids

Logical. Whether to remove ID columns from output. Optional.

extract_traits

Logical. Whether to extract taxonomic traits. Optional.

extract_individual_features

Logical. Whether to extract individual-level features. Optional.

traits_to_genera

Logical. Whether to aggregate traits to genus level. Optional.

wd_fam_level

Logical. Whether to use family-level wood density. Optional.

include_liana

Logical. Whether to include lianas. Optional.

extract_subplot_features

Logical. Whether to extract subplot features. Optional.

concatenate_stem

Logical. Whether to concatenate multiple stems. Optional.

issues

Character. How to handle flagged measurements. Options:

  • "remove" (default): Drop flagged measurements before aggregation.

  • "include": Keep flagged measurements and add an issue column in output.

  • "ignore": Keep flagged measurements but do not show the issue column.

include_measurement_ids

Logical. Whether to include measurement IDs in aggregated output. Optional.

census_strategy

Character. Strategy for selecting census when `show_multiple_census = FALSE`. Options: "last" (default, most recent census), "first" (earliest census), or "mean" (average across all censuses). When "first" or "last" is selected, individuals recruited after the first census or dead before the last census will have NA values, reflecting biological reality.

The census is chosen per plot, not per trait: one census is selected from all of the plot's measurements, and every census-linked trait is then filtered to it. A trait never measured at that census therefore disappears from the output entirely - it returns no column at all, not a column of NAs, because the wide pivot only creates columns for trait/census combinations that carry data. This is common for tree height, which is often measured at the first census or two and not re-measured afterwards. Every dropped trait is named in a warning listing the censuses where it does exist. To keep it, use `show_multiple_census = TRUE` (one `<trait>_census_N` column per census) or `census_strategy = "mean"`. With `output_style = "full"`, height and diameter are also returned unfiltered in the `height_diameter` table, which always spans every census.

individual_features_format

Character. Format for individual-level feature measurements. `"wide"` (default) returns one row per individual with one column per trait (aggregated). `"long"` returns one row per individual per measurement: if an individual has two diameter measurements, it will appear in two rows. Adds columns `trait`, `traitvalue`, `traitvalue_char`, `valuetype`, `census_name`, and `census_date` (NA when not census-linked). Census filtering via `show_multiple_census` / `census_strategy` is still applied. Incompatible with `concatenate_stem = TRUE`. `"census_pairs"` returns one row per consecutive pair of censuses per individual. Census pairing is plot-level: every individual is crossed against all consecutive census pairs of its plot, receiving `NA` at any census where it has no measurement (e.g. recruited at census_2 → `stem_diameter_0 = NA`; dead at census_2 → `stem_diameter_1 = NA`). All individual-level traits appear as `<trait>_0` and `<trait>_1` columns. Additional columns: `census_name_0`, `census_name_1`, `date_census0`, `date_census1`, `time` (days between the two censuses). All available censuses are used regardless of `show_multiple_census`. Incompatible with `concatenate_stem = TRUE`.

output_style

Either a character scalar – one of `"auto"`, `"minimal"`, `"standard"`, `"permanent_plot"`, `"permanent_plot_multi_census"`, `"transect"`, `"full"`, `"census_pairs"` – or a `plot_output_style` object built with [output_style()]. Defaults to `"auto"`, which picks a style from the `method` field of the queried plots. When `individual_features_format = "census_pairs"`, character values (other than `"full"`) are overridden to `"census_pairs"`; a custom `plot_output_style` object is respected as-is. Use [list_output_styles()] for an overview of available built-in styles, [get_output_style()] to inspect what a style does, and [output_style()] to build a custom one (typically with `based_on` to inherit from a built-in and override a few fields). The configuration schema is documented in [output_style()].

con

Optional database connection to main database. If NULL, will call call.mydb() to establish connection. If you've already connected with `mydb <- call.mydb()`, pass `con = mydb` to avoid re-prompting.

con.taxa

Optional database connection to taxa database. If NULL, will check for `mydb.taxa` in calling environment, otherwise will call call.mydb.taxa() to establish connection. Pass explicitly to avoid credential prompts.

verbose

Console verbosity. `"normal"` (the default) reports only what was found, what was excluded on the way, and which tables came back; `"quiet"` reports nothing but warnings; `"debug"` prints the full step-by-step log of every internal query, which is what earlier versions always printed. `TRUE` and `FALSE` are accepted as `"debug"` and `"quiet"`. Set a session default with `options(CafriplotsR.verbose = "debug")`. Interactive matching prompts are never muted.

Value

A list or data frame containing plot data and associated information. When multiple components are requested, returns a list with elements like `extract`, `census_features`, `coordinates`, and `coordinates_sf`. If only one component is available, returns that component directly. Returns `NA` if no plots are found matching the criteria.

Examples

if (FALSE) { # \dontrun{
  query_plots(country = "Gabon", extract_individuals = FALSE)
  
  query_plots(country = "Cameroon")
  
  query_plots(plot_name = "mbalmayo001")

  # Filter on plot features rather than on columns of data_liste_plots
  plot_feature_filters()          # what can be filtered
  plot_feature_values("data_provider")

  query_plots(
    feature_filters = list(
      data_provider          = "IRD",
      principal_investigator = c("Dauby", "Sonke")
    )
  )
} # }