Setting Up shinyplanr for Your Region • shinyplanr

This chapter guides deployers through the process of setting up a new shinyplanr instance for a specific region. We cover the template creation function, data preparation, configuration options, and the feature dictionary. For instructions on deploying the finished app to Posit Connect, see the Deployment vignette.

Note

The setup process creates a standalone deployment project — a separate R project that holds your region-specific data and configuration. You do not need to modify or fork the shinyplanr package source code.

Overview of the Setup Process

Setting up shinyplanr for a new region involves the following steps:

Create a deployment project using create_shinyplanr_template()
Prepare spatial data by editing setup-data.R
Configure app options by editing setup-app.R
Define features by editing Dict_Feature.csv
Customise help text by editing markdown files
Test locally before deployment

Prerequisites

Before starting, ensure you have:

R and RStudio installed
The shinyplanr package installed from GitHub
Other supporting packages installed (e.g. oceandatr and spatialgridr)
A geographic boundary for your region of interest
Spatial data for features you wish to include

Step 1: Create a Deployment Project

The create_shinyplanr_template() function generates a complete, standalone deployment project for your region.

Basic Usage

library(shinyplanr)

create_shinyplanr_template(
  country = "Fiji",
  crs = "+proj=cea +lon_0=178 +lat_ts=-17 +datum=WGS84 +units=m +no_defs",
  oceandatr = TRUE
)

This creates the project in a sibling directory to your current working directory (e.g. ../Fiji/). Open the resulting .Rproj file to work inside the new project.

Function Parameters

Parameter	Description	Default
`country`	Name of your country/region. Used for folder and file naming.	Required
`crs`	Coordinate reference system. Use an equal-area projection for your region.	`"ESRI:54009"`
`oceandatr`	If `TRUE`, includes code to download data from oceandatr.	`TRUE`
`resolution`	Planning unit size in metres.	`20000`
`include_climate`	Include climate-smart planning options.	`TRUE`
`include_cost`	Include cost layer setup.	`TRUE`
`include_mpas`	Include code to fetch MPAs from WDPA.	`TRUE`
`output_dir`	Path where the deployment project will be created.	`"../country"`
`use_renv`	Initialise renv to lock package versions for reproducible deployment.	`TRUE`
`create_rproj`	Create an RStudio `.Rproj` file.	`TRUE`

Finding an Appropriate CRS

For spatial planning, you should use an equal-area projection centred on your region. This ensures that planning unit areas are correctly calculated.

To find an appropriate CRS:

Visit Projection Wizard
Enter the bounding box coordinates of your region
Select “Equal Area” as the distortion property
Copy the PROJ string or EPSG code

Alternatively, search EPSG.io for standard projections used in your country.

CRS Examples

Global (default): "ESRI:54009" (Mollweide)

Fiji: "+proj=cea +lon_0=178 +lat_ts=-17 +datum=WGS84 +units=m +no_defs"

Kosrae: "+proj=cea +lon_0=163 +lat_ts=2.8 +datum=WGS84 +units=m +no_defs"

Generated Project Structure

After running create_shinyplanr_template(), you will have a self-contained project (using Fiji as an example):

Fiji/                              ← Your deployment project root
├── app.R                          ← App entry point (do not edit)
├── deploy.R                       ← Deployment to Posit Connect
├── Fiji.Rproj                     ← Open this in RStudio
├── config/                        ← AUTO-GENERATED by setup-app.R
├── www/                           ← AUTO-GENERATED by setup-app.R
└── setup/                         ← Everything you edit lives here
    ├── setup-data.R               ← Step 1: prepare spatial data
    ├── setup-app.R                ← Step 2: configure the app
    ├── Dict_Feature.csv           ← Feature definitions
    ├── data/                      ← Place raw spatial data files here
    ├── logos/                     ← Place logo image files here
    └── content/                   ← Edit markdown and other content here
        ├── shinyplanr_1welcome1.md
        ├── shinyplanr_6faq.md
        └── ...

Tip

Open Fiji/Fiji.Rproj in RStudio to work inside the deployment project. All subsequent scripts should be run from within the project, not from the shinyplanr package directory.

The config/ and www/ folders are auto-generated when you run setup/setup-app.R — do not edit them directly. Everything you need to customise lives inside setup/.

Step 2: Prepare Spatial Data

The setup/setup-data.R script processes your raw spatial data into the format required by shinyplanr.

Understanding setup-data.R

Open setup/setup-data.R in RStudio (from within the deployment project). The script contains several sections:

Basic Parameters

country    <- "Fiji"
crs        <- "+proj=cea +lon_0=178 +lat_ts=-17 +datum=WGS84 +units=m +no_defs"
resolution <- 20000L  # Planning unit size in metres

setup_dir <- "setup"                           # Location of the setup folder
data_path <- file.path(setup_dir, "data")      # Raw spatial data files

Boundaries

If you set oceandatr = TRUE, the template includes code to download your EEZ boundary:

# Get EEZ boundary from Marine Regions database
eez <- spatialgridr::get_boundary(name = country, type = "eez") %>%
  sf::st_transform(crs = crs) %>%
  sf::st_geometry() %>%
  sf::st_sf()

For custom boundaries, replace this with:

bndry <- sf::st_read(file.path(data_path, "my_boundary.gpkg")) %>%
  sf::st_transform(crs = crs)

Planning Unit Grid

PUs <- spatialgridr::get_grid(
  boundary = eez,
  crs = crs,
  output = "sf_hex",
  resolution = resolution
)

This creates a hexagonal grid of planning units. Options for output include:

"sf_hex": Hexagonal sf polygons
"sf_square": Square sf polygons
"raster": Raster (SpatRaster) format

Feature Data

If using oceandatr, the template downloads several data layers:

# Bathymetry / Depth zones
bathymetry <- oceandatr::get_bathymetry(
  spatial_grid = PUs,
  classify_bathymetry = TRUE
) %>%
  sf::st_drop_geometry()

# Geomorphology
geomorphology <- oceandatr::get_geomorphology(
  spatial_grid = PUs
) %>%
  sf::st_drop_geometry()

# Seamounts (with buffer)
seamounts <- oceandatr::get_seamounts(
  spatial_grid = PUs,
  buffer = 30000
) %>%
  sf::st_drop_geometry()

Adding Custom Data

To add your own spatial data layers:

# Example: Load habitat data from shapefile
habitat <- sf::st_read(file.path(data_path, "habitat.gpkg")) %>%
  spatialgridr::get_data_in_grid(
    spatial_grid = PUs,
    dat = .,
    feature_names = "habitat_type",
    meth = "average",
    cutoff = 0.1
  )

# Example: Load raster data
my_raster <- terra::rast(file.path(data_path, "my_data.tif")) %>%
  spatialgridr::get_data_in_grid(
    spatial_grid = PUs,
    dat = .,
    meth = "average"
  )

Cost Layers

# Calculate distance to coast
cost <- dat_sf %>%
  dplyr::select(geometry) %>%
  spatialplanr::splnr_get_distCoast(custom_coast = coast) %>%
  dplyr::mutate(
    Cost_Area = PU_Area,          # Equal area cost
    Cost_Distance = coastDistance_km
  )

Locked-In Areas (MPAs)

mpas <- spatialplanr::splnr_get_MPAs(
  PlanUnits = PUs, 
  Countries = country
) %>%
  sf::st_transform(crs = crs) %>%
  spatialgridr::get_data_in_grid(
    spatial_grid = PUs, 
    dat = ., 
    name = "mpas", 
    cutoff = 0.5
  )

Saving the Data

The final step combines all data and saves it:

# Combine all features
dat_sf <- dplyr::bind_cols(
  PUs,
  bathymetry,
  geomorphology,
  seamounts,
  cost,
  mpas
)

# Save to setup/data/
save(dat_sf, bndry, coast,
     file = file.path(data_path, paste0(country, "_RawData.rda")))

Running setup-data.R

Open setup/setup-data.R in RStudio (with the .Rproj open)
Review and modify as needed for your data
Run the entire script (Ctrl/Cmd + Shift + Enter)
Check for any warnings or errors
Verify the .rda file was created

Data Download Time

The first run of oceandatr functions may download large datasets. Ensure you have a stable internet connection and sufficient disk space.

Step 3: Configure App Options

The setup/setup-app.R script configures how the shinyplanr application behaves and generates the config file loaded at runtime.

The Options List

The options list controls application settings, allowing you to define text, switch modules on/off and decide on display options:

options <- list(
  
  ## General Options
  app_title = "Fiji: shinyplanr",
  nav_title = "Fiji Spatial Planning",
  navbar = list(theme = "dark"),
  
  ## Funder link (opens when funder logo is clicked)
  funder_url = "https://spatialplanning.github.io",

  ## Logo and data file locations (relative to setup/)
  file_logo        = file.path(setup_dir, "logos", "logo.png"),
  file_logo2       = file.path(setup_dir, "logos", "logo2.png"),
  file_logo3       = file.path(setup_dir, "logos", "logo3.png"),
  file_logo_funder = file.path(setup_dir, "logos", "logo_funder.png"),
  file_data        = file.path(data_path, paste0(country, "_RawData.rda")),
  
  ## Module switches
  mod_1welcome  = TRUE,
  mod_2scenario = TRUE,
  mod_3compare  = TRUE,
  mod_4features = TRUE,
  mod_5coverage = TRUE,
  mod_6help     = TRUE,
  
  ## UQ logo in welcome footer
  show_uq_logo = TRUE,   # Set FALSE to hide the UQ logo

  ## Features
  include_report = TRUE,
  include_bioregion = FALSE,
  include_climateChange = FALSE,
  include_lockedArea = TRUE,
  
  ## Target grouping
  targetsBy = "individual",  # "individual", "category", or "master"
  
  ## Objective function
  obj_func = "min_shortfall",  # "min_set" or "min_shortfall"
  
  ## Geographic options
  cCRS = "+proj=cea +lon_0=178 +lat_ts=-17 +datum=WGS84"
)

Key Options Explained

Module Switches

Enable or disable application modules:

Option	Description
`mod_1welcome`	Welcome/introduction page
`mod_2scenario`	Main scenario builder (always needed)
`mod_3compare`	Side-by-side scenario comparison
`mod_4features`	Feature exploration and mapping
`mod_5coverage`	Upload and evaluate spatial files
`mod_6help`	FAQ and technical help

Target Grouping

How targets are presented to users:

"individual": Separate slider for each feature
"category": One slider per category (e.g., all habitats together)
"master": Single slider for all features

Objective Function

"min_shortfall": Minimise shortfall within a budget (shows budget input)
"min_set": Find minimum cost solution meeting all targets

Climate Options

If climate data is available:

include_climateChange = TRUE,
climate_change = 1,    # 1 = CPA method
percentile = 5,        # For percentile approach
direction = -1,        # -1 = low values are refugia
refugiaTarget = 1

Running setup-app.R

After configuring options:

Ensure setup-data.R has been run successfully
Run setup/setup-app.R in RStudio (from inside the deployment project)
The script will:
- Copy logos from setup/logos/ to www/
- Load and validate the feature dictionary
- Process spatial data
- Save all configuration to config/shinyplanr_config.rds

Note

The old approach wrote data into the package source via usethis::use_data(). The new approach saves a single .rds config file that load_config() reads at app startup — no package rebuild required.

Step 4: The Feature Dictionary

The setup/Dict_Feature.csv file defines all data layers and their properties. This is the central configuration for what features, costs, and constraints appear in the application.

Dictionary Columns

Column	Description	Example
`nameCommon`	Human-readable name shown in the app	`"Coral Reef"`
`nameVariable`	Variable name in the spatial data (must match exactly)	`"coral_reef"`
`category`	Grouping category for display	`"Habitat"`
`categoryID`	Category identifier for sorting	`"Hab"`
`type`	Feature type (see below)	`"Feature"`
`targetInitial`	Default target value (%)	`30`
`targetMin`	Minimum target (slider min)	`0`
`targetMax`	Maximum target (slider max)	`85`
`includeApp`	Include in the app (TRUE/FALSE)	`TRUE`
`includeJust`	Include justification text	`TRUE`
`units`	Units for display	`"km²"`
`justification`	Description text shown in app	`"Important habitat..."`

Feature Types

Type	Description
`Feature`	Conservation feature with targets
`Cost`	Cost layer for optimisation
`LockIn`	Constraint: must be selected
`LockOut`	Constraint: cannot be selected
`Climate`	Climate layer for climate-smart planning
`Bioregion`	Bioregion stratification layer
`EcosystemServices`	Ecosystem service layer

Example Dictionary Entries

nameCommon,nameVariable,category,categoryID,type,targetInitial,targetMin,targetMax,includeApp,includeJust,units,justification
Coral Reef,coral_reef,Habitat,Habitat,Feature,30,0,85,TRUE,TRUE,km²,"Coral reefs provide habitat for many species..."
Seagrass,seagrass,Habitat,Habitat,Feature,30,0,85,TRUE,TRUE,km²,"Seagrass meadows are important nursery areas..."
Equal Area Cost,Cost_Area,Cost,Cost,Cost,NA,NA,NA,TRUE,TRUE,,"All planning units have equal cost."
Fishing Effort,fishing_cost,Cost,Cost,Cost,NA,NA,NA,TRUE,TRUE,hours,"Higher values indicate more fishing activity."
Marine Protected Areas,mpas,Protected Areas,MPAs,LockIn,NA,NA,NA,TRUE,TRUE,,"Existing MPAs to be included in solutions."
Shipping Lanes,shipping,Exclusions,Exclusions,LockOut,NA,NA,NA,TRUE,TRUE,,"Areas excluded due to shipping."

Common Issues

Variable Name Matching

The nameVariable column must exactly match column names in your spatial data (dat_sf). Check for:

Spelling differences

Case sensitivity

Spaces vs underscores

Step 5: Customise Content

The setup/content/ folder contains text and other content files that appear in the application. Markdown (.md) files are the primary format, but you can also store PDFs, images, or other reference material here.

Welcome Pages

Multiple welcome page tabs can be configured:

File	Tab title
`shinyplanr_1welcome1.md`	Welcome
`shinyplanr_1welcome2.md`	Terminology
`shinyplanr_1welcome3.md`	Instructions
`shinyplanr_1welcome4.md`	CARE
`shinyplanr_1welcome5.md`	References
`shinyplanr_1footer.md`	Footer text (contact info)

Module help text

File	Where it appears
`shinyplanr_2solution.md`	Solution panel
`shinyplanr_2targets.md`	Targets panel
`shinyplanr_2cost.md`	Cost panel
`shinyplanr_2climate.md`	Climate panel
`shinyplanr_2ecosystemServices.md`	Ecosystem services panel

Help tab pages

File	Where it appears
`shinyplanr_6faq.md`	FAQ tab
`shinyplanr_6technical.md`	Technical notes tab
`shinyplanr_6changelog.md`	Changelog tab

Edit these files with region-specific information before deployment. You can also place additional files (PDFs, images) in setup/content/ and reference them from markdown.

Step 6: Test Locally

Before deploying, test the application locally from within the deployment project:

# app.R does this automatically when you call shiny::runApp()
shiny::runApp()

This reads app.R in the project root, which calls:

shinyplanr::load_config("config/shinyplanr_config.rds")
shinyplanr::run_app()

Important

Run shiny::runApp() from inside the deployment project (i.e. with Fiji.Rproj open), not from the shinyplanr package directory.

Testing Checklist

Application loads without errors
All modules are visible (if enabled)
Features appear correctly in dropdowns
Cost layers are available
Constraints can be selected
Analysis runs and produces results
Maps display correctly
Download buttons work
Help text displays properly

Summary

Setting up shinyplanr for a new region involves:

Creating a deployment project with create_shinyplanr_template()
Preparing data in setup-data.R
Configuring options in setup-app.R (outputs config/shinyplanr_config.rds)
Defining features in Dict_Feature.csv
Customising text in markdown files
Testing the application locally with shiny::runApp()

Once testing is complete, proceed to the Deployment vignette for instructions on locking package versions and deploying to Posit Connect.

Quick Reference

Minimum Required Files

After running setup/setup-app.R, your deployment project should contain:

{Country}/
├── app.R                         # Auto-generated — do not edit
├── deploy.R                      # Deployment script
├── config/
│   └── shinyplanr_config.rds     # ← key file, generated by setup-app.R
├── www/
│   ├── logo.png
│   └── logo_funder.png
└── setup/
    ├── setup-data.R
    ├── setup-app.R
    ├── Dict_Feature.csv
    ├── data/
    │   └── {Country}_RawData.rda # Generated by setup-data.R
    ├── logos/
    └── content/

Common Commands

# Create deployment project (run from any R session with shinyplanr loaded)
create_shinyplanr_template(country = "MyRegion", crs = "EPSG:32601")

# Check boundary data availability (oceandatr)
oceandatr::get_boundary(name = "MyCountry", type = "eez")

# Run setup scripts (from inside the deployment project)
source("setup/setup-data.R")
source("setup/setup-app.R")

# Test the app locally
shiny::runApp()

# Lock package versions before deploying
renv::snapshot()

# Deploy to Posit Connect
source("deploy.R")