File Naming Conventions • elsar

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.