Project Structure and Data Files

vizRd projects are ordinary folders. The app reads data and configuration from the folder you pass to vizRd::run_app().

Minimal layout

my-project/
  data/
    template_metrics.rds
    generic_sales.csv
  vizrd.yml
  www/
    notes.pdf
    logo.png

data/

The data/ directory contains source datasets. vizRd supports .csv and .rds files by default. A data frame with template columns opens as a template dashboard; any other data frame opens in the generic explorer.

vizrd.yml

vizrd.yml controls app metadata, dataset ordering, supported file formats, embedding defaults, optional basemap settings, export settings, and static assets. Simple projects can rely on auto-discovery, while release-quality projects usually add explicit dataset entries.

example_path <- system.file("extdata", "example_project", package = "vizRd")
cfg <- vizRd::read_config(example_path)
cfg$data$formats
#> [1] "rds" "csv"
cfg$data$auto_discover
#> [1] TRUE

www/

Configured dataset IDs need not match filenames. A configured file is not listed a second time by auto-discovery. Give distinct IDs to files with the same stem, and use load_dataset() with the configured ID; unknown IDs raise an error. Explicit YAML data.dir wins over data_dir, while data_dir overrides the default directory when YAML does not set it. Dataset and notes paths must be relative, without parent traversal, and stay inside the project root after symlink resolution.

Dataset reads are cached per R process with a 64 MiB / 64-file LRU bound. Size, modification time, and change time invalidate entries. Disable caching with options(vizrd.cache_max_bytes = 0) or set a different byte limit. Rewrites that preserve every filesystem signature require disabling the cache. The cache does not persist to disk or cache derived charts.

Each app serves its own project assets; opening another project in the same R process does not replace or inherit another app’s vizrd-project directory.

The optional www/ directory stores project-local assets such as logos, PDF technical notes, CSS, or images. These files are shipped with the project and do not require external downloads.

Inspect the shipped example

The package-local example project is a useful template for new projects:

list.files(example_path, recursive = TRUE)
#>  [1] "data/dummy_alt.rds"              "data/dummy_excise.rds"          
#>  [3] "data/excises.rds"                "data/generic_sales.csv"         
#>  [5] "data/marlboro.rds"               "data/world.gpkg"                
#>  [7] "vizrd.yml"                       "www/embed-host.html"            
#>  [9] "www/pdf/excises.pdf"             "www/pdf/marlboro.pdf"           
#> [11] "www/share-uat.html"              "www/wiiw-hepa-logo-only_RGB.png"

It demonstrates configured template datasets, the auto-discovered generic_sales.csv explorer dataset, PDF notes, and a project logo.