Generate ecological and data-status reports

Generate reports from a camReport object. report() creates an ecological report, while status() creates a data-status report. A named profile can select an ordered set of modules immediately before rendering.

Usage

report(object, filename, view, test, profile, format, overwrite = FALSE)

status(object, filename, view, profile, format, overwrite = FALSE)

Arguments

object: A camReport object created by camData().
filename: An optional output filename or path. A .html or .pdf extension selects the format when format is omitted. Without an extension, the defaults are "report" and "data_status".
view: A logical value (default FALSE) specifying whether to open the generated report.
test: A logical value (default FALSE). If TRUE, ecological report modules are tested when HTML rendering fails.
profile: An optional profile name or reportProfile object. When omitted, the sections currently attached to object are rendered.
format: Output format, either "html" or "pdf". The default is inferred from filename, falling back to "html".
overwrite: A logical value (default FALSE). Set to TRUE explicitly to replace existing output and .Rmd files with the selected stem.

Value

Invisibly returns the generated report path.

Details

HTML is the default output. PDF output first renders the existing HTML report and then prints it through a headless Chrome or Edge browser using the optional pagedown package. This route preserves modules that contain HTML widgets or HTML-formatted tables. Interactive controls are naturally static in the resulting PDF. PDF output omits the table of contents and excludes modules whose registry entry does not support PDF. The formats column shown by list_Modules() records module compatibility.

Output includes the rendered .html or .pdf file and an .Rmd source file with the same stem. The resolved paths are displayed before rendering. A filename without a directory uses the object's existing dataset directory; otherwise supply a filename including an existing output directory. Invalid directories cause an error rather than falling back to a different location. Existing report or .Rmd files are protected unless overwrite = TRUE. Supply a new filename for each retained report; use tempfile() for a preview.

Selected module packages are checked with requireNamespace() without automatically attaching them. Bundled modules qualify external functions; custom modules that relied on automatic attachment must use package::fun() or otherwise manage their own dependencies explicitly. Module code can still change the search path or other process-wide state. The rendering environment is not a separate R process or a sandbox. Run only modules from sources you trust.

view = TRUE opens the completed file after rendering; it does not select different modules or dependencies. To inspect a file that was already generated, call utils::browseURL(report_file) instead of rendering it again. A failure in the R Markdown setup chunk commonly reports a missing package required by the selected modules. Read that original error before using test = TRUE: recovery tests only the attached selection, preserves its order, and keeps passing modules whose parent sections also pass. Descendants of failing parents are excluded. A shorter report is an expected diagnostic outcome, not an equivalent successful full report.

Use profile = "default" or profile = "EOW" to select a known report structure explicitly. section_names() without a profile lists the complete available module pool, including alternative modules; it is not the same as a profile's selection. Reread corrected source files with camData(..., update = TRUE) before rerunning status() or report().

Apart from the destination notice, rendering is quiet by default. Set options(camtrapReport.progress = TRUE) to show console progress for module construction, individual chunks, HTML rendering, PDF conversion, and opening the completed file. Timings include elapsed time and CPU time in the current R process; Pandoc and browser CPU time is not included in the latter. The last started chunk identifies where a long-running computation is executing. PDF page loading and printing use a 60-second timeout after browser startup; analytical computations are not interrupted by that timeout.

Examples

# \donttest{
if (rmarkdown::pandoc_available()) {
# A small import example; see the vignettes for full analytical reports.
source_dataset <- system.file(
  "external", "example-small", package = "camtrapReport"
)
example_dataset <- tempfile("camtrapReport-example-")
dir.create(example_dataset)
invisible(file.copy(
  list.files(source_dataset, full.names = TRUE),
  example_dataset,
  recursive = TRUE
))
cm <- camData(example_dataset)
cm <- sections(cm, "introduction")
report_file <- report(
  cm,
  filename = tempfile("camtrapReport-report-"),
  view = FALSE
)
file.exists(report_file)
unlink(c(report_file, sub("\\.html$", ".Rmd", report_file)), force = TRUE)
unlink(example_dataset, recursive = TRUE, force = TRUE)
}
#> The camReport object is being created...
#> Dataset size: 164.4 KB.
#> File size looks modest, but full object creation may still take several minutes depending on the number of records.
#> Taxonomic class is unavailable for 10 recorded taxa. Class-dependent groups and mammal counts may be incomplete; missing classification does not indicate ecological absence. Supply source classifications or explicitly enable GBIF enrichment and rebuild with update = TRUE.
#> Setup is done!
#> Data loaded successfully in 7 sec.
#> camReport object is ready for GMU8 LEUVEN.
#> 
#> The report sections are updated.
#> Report output: C:/Users/ebrah010/AppData/Local/Temp/Rtmpu4DeAb/camtrapReport-report-8b7877facb7.html
#> R Markdown source: C:/Users/ebrah010/AppData/Local/Temp/Rtmpu4DeAb/camtrapReport-report-8b7877facb7.Rmd
# }