Module Management

Elham Ebrahimi

Customise and extend report modules

camtrapReport builds ecological reports from reusable modules containing narrative text, analyses, tables, and figures. This guide shows how to inspect, create, register, test, and manage modules. Explore the Module Catalog before developing a new one.

Important: Work with a copy of the module registry in a writable project directory, not the installed package. Modules execute R code, so use only trusted sources.

Figure 1. Modular workflow for defining, registering, selecting, and running report modules in camtrapReport.

1. Explore available modules

# List all available modules
list_Modules()

# Show all section names used in the report
section_names()

2. Create a YAML module

A YAML module specifies its identifier, title, parent section, narrative, and code. Figure 2 illustrates how these elements appear in the report.

Figure 2. Relationship between the main components of a YAML report module and its output in the Ecological Report.

Save the following example as species_table.yml in your project directory. It uses the species table stored in cm$data_status; inspect that object before adapting the example to another dataset.

name: species_table
title: "Species summary table"
parent: "results"
text: "This section provides a summary of the species detected in the camera-trap dataset, including their taxonomy and total number of captures."

code: |
  #| echo: false
  #| message: false
  #| warning: false

  species_table <- object$data_status$Species$Table

  if (!is.null(species_table) && nrow(species_table) > 0) {
    knitr::kable(
      species_table,
      caption = "Species detected in the camera-trap dataset."
    )
  } else {
    cat("No species table is available for this dataset.")
  }

3. Register the module

Copy the bundled registry to a writable location and register the YAML file there. The example inserts the module before richness.

# Create a writable project-level module registry once
bundled_modules <- system.file(
  "reportSections",
  package = "camtrapReport"
)
module_dir <- here::here("reportSections")

if (!dir.exists(module_dir)) {
  dir.create(module_dir)
  file.copy(
    list.files(bundled_modules, full.names = TRUE),
    module_dir,
    recursive = TRUE
  )
}

# Add a new module from a YAML file
added <- add_Module(
  x = "species_table.yml",
  before = "richness",
  test = FALSE,
  object = cm,
  dir = module_dir
)

# Check whether the module has been added
list_Modules(dir = module_dir)

4. Add and test the module

Add the registered module to the active camReport object, test it independently, then generate the complete report.

cm$addReportObject(added$module)
listReportSections(cm)

# Test the new module only
testSection(
  added$module,
  object = cm,
  view = TRUE
)

# Generate the full report
report(cm, view = TRUE)

Check the output for errors, missing figures, duplicated headings, and scientific accuracy. Module-specific dependencies should be declared in the YAML; install_all() can install missing optional packages when needed.

Edit, reorder, or remove modules

To customise an existing module, edit a project-level copy of its YAML file and test the revised version. Report narratives can combine module templates, dataset metadata, and computed results; review them before publication.

# Validate active module definitions and inspect the hierarchy
list_Modules(validate = TRUE, dir = module_dir)

# Move a module within the report hierarchy
move_Module(
  "species_table",
  after = "captures",
  parent = "results",
  dir = module_dir
)

# Move a module and its children to the module trash
remove_Module("species_table", recursive = TRUE, dir = module_dir)

# Inspect active and deleted modules
list_Modules(include_trash = TRUE, dir = module_dir)

# Restore a removed module
restore_Module("species_table", test = TRUE, dir = module_dir)

Removed modules can be restored from the registry’s trash. empty_trash() permanently deletes them, so retain backups before using it. After changes, refresh the report object’s configuration and verify its sections and rendered output.

Reproducibility and further guidance

Keep the input data, customised YAML files, relevant dependencies, analytical settings, and package versions together. Test modules against missing or empty data and check method-specific assumptions before sharing results.

For reusable module selections, see Analytical Profiles. For end-to-end report configuration, see the Ecological Report guide.