Skip to contents

File Naming Conventions

naming_conventions.Rmd

Overview

This document describes the standardised naming conventions for input and output datasets used in ELSA analyses. Consistent naming improves file organisation, makes datasets easier to identify, and ensures reproducibility across different countries and analysis tiers.

General Rules

  • All lowercase — file names should use only lowercase letters.
  • Underscores for spaces — use underscores (_) to separate words.
  • No special characters — avoid hyphens, periods (except before the file extension), or other special characters.
  • Be descriptive — the file name should convey the content, geographic scope, and analysis tier at a glance.

Analysis Tiers

ELSA analyses are organised into three tiers based on the source and resolution of input data:

Tier Code Description
Tier 1 t1 Global analysis using globally available standard datasets
Tier 2 t2 National analysis incorporating national-level data
Tier 3 t3 Subnational analysis using locally specific data

The tier code is appended to filenames produced by the elsar pipeline to indicate which level of analysis generated the output.

File Name Structure

Pipeline outputs

Outputs from elsar functions follow this pattern:

<description>_<iso3>_<tier>.<ext>
Component Description Example
<description> Brief description of the dataset protect_zone, restore_zone
<iso3> ISO 3166-1 alpha-3 country code (or global) hti, zaf, kaz
<tier> Analysis tier (t1, t2, t3) t2
<ext> File extension .tif, .gpkg, .png

Examples:

protect_zone_hti_t2.tif
restore_zone_zaf_t1.tif
planning_units_kaz_t3.tif
protected_areas_dom_t2.tif

Temporal datasets

Datasets that vary over time (e.g., land use/land cover) include the year:

<description>_<year>_<iso3>_<tier>.<ext>

Examples:

esri_10m_proportion_2023_gha_t2.tif
deforestation_risk_2020_dom_t2.tif

LULC class layers

LULC proportion layers additionally include the land cover class:

<product>_proportion_<year>_<iso3>_<class>.<ext>

Examples:

esri_10m_proportion_2023_gha_agriculture.tif
dynamic_world_proportion_2023_ken_built_area.tif

Figures

Plot outputs follow the same convention with a .png extension:

<description>_<iso3>.png

Examples:

protect_zone_hti.png
forest_integrity_zaf.png

Preferred File Formats

Type Format Extension Notes
Raster Cloud-Optimized GeoTIFF .tif ZSTD compression, used by all elsar raster outputs
Vector GeoPackage .gpkg Preferred over Shapefiles — no file size limits, single file
Plots PNG .png Raster images for figures
Tabular CSV .csv Plain text, widely compatible

Folder Structure

A recommended layout for organising ELSA analysis outputs:

elsa_<iso3>/
├── inputs/
│   ├── rasters/
│   └── vectors/
├── outputs/
│   ├── rasters/
│   ├── vectors/
│   └── figures/
└── reports/
  • inputs/ — raw and preprocessed input datasets.
  • outputs/ — all outputs generated by the elsar pipeline.
  • reports/ — final reports, summaries, and documentation.

Versioning and Date Stamps

  • Versioning — if multiple versions of a dataset exist, append a version number to the description, or a specific term for the project, e.g., restoring_hope: protect_zone_v2_dom_t2.tif, protect_zone_restoring_hope_dom_t1.tif
  • Date stamps — if needed, append a date in YYYYMMDD format: protect_zone_20240601_dom_t2.tif.