Environment Setup and Project Folder Structure¶

This lesson is the prerequisite step for all sessions in Module 1 — Observational climate pipeline.
You will install VS Code, create and activate a Python virtual environment, install all required packages, and build the canonical folder structure used throughout the workshop.

Overview¶

flowchart LR
  A[Install VS Code] --> B[Create virtual environment]
  B --> C[Activate environment]
  C --> D[Install core packages]
  D --> E[Create folder structure]
  E --> F[Ready for Session 1.1 →]

1. Install VS Code¶

Visual Studio Code is the recommended IDE for this workshop.

Steps¶

1. Go to https://code.visualstudio.com/download and download the Windows installer (.exe).
2. Run the installer and accept the defaults.
3. Launch VS Code and install the following extensions from the Extensions panel (Ctrl+Shift+X):

Tip: Press Ctrl+Shift+P → "Python: Select Interpreter" to point VS Code to the virtual environment you create below.

2. Create the Virtual Environment¶

Open a terminal in the repository root (the folder containing mkdocs.yml).

python -m venv .venv

python3 -m venv .venv

This creates .venv/ in the repository root — that folder is already listed in .gitignore.

3. Activate the Virtual Environment¶

.\.venv\Scripts\Activate.ps1

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

.venv\Scripts\activate.bat

source .venv/bin/activate

Your prompt should now show (.venv) to confirm the environment is active.
All subsequent pip install commands install only into this isolated environment.

4. Install Core Packages¶

With the environment active, install the full set of packages used across the workshop:

pip install --upgrade pip
pip install numpy pandas matplotlib cftime cf_xarray openpyxl shapely scipy requests cartopy geopandas rioxarray rasterio regionmask salem netCDF4 xarray cdsapi

Xarray note: If Xarray is not installed.

pip install xarray[complete]

Windows note: cartopy and rasterio sometimes need pre-built wheels.
If pip install cartopy fails, try:

pip install --find-links https://girder.github.io/large_image_wheels cartopy rasterio

Package roles¶

Verify the installation¶

import numpy, pandas, matplotlib, xarray, cartopy, geopandas, rasterio
print("All core packages imported successfully ✓")

Run this in a terminal (python -c "...") or in the companion notebook.

5. Create the Project Folder Structure¶

The pipeline expects the following layout under the repository root.
Run the block below once to create every required folder:

from pathlib import Path

folders = [
    # Raw observations (one sub-directory per source)
    "data/raw/chirps",
    # Preprocessed, QC-passed data
    "data/processed/chirps",
    # Static ancillary files — Ethiopia grid, land mask, shapefiles
    "data/ancillary/grid_mask",
    # QC diagnostic plots and reports
    "reports/qc_chirps",
    # Processing logs (download logs, run logs)
    "reports/logs",
]

for f in folders:
    Path(f).mkdir(parents=True, exist_ok=True)
    print(f"Created  {f}/")

print("\nFolder structure ready ✓")

$dirs = @(
    "data\raw\chirps",
    "data\processed\chirps",
    "data\ancillary\grid_mask",
    "reports\qc_chirps",
    "reports\logs"
)
foreach ($d in $dirs) { New-Item -ItemType Directory -Force -Path $d | Out-Null; Write-Host "Created $d" }

mkdir -p data/raw/chirps data/processed/chirps data/ancillary/grid_mask reports/qc_chirps reports/logs

Expected layout¶

vectri-seasonal/          ← repository root
│
├── data/
│   ├── raw/
│   │   └── chirps/           ← yearly CHIRPS NetCDF files (downloaded)
│   ├── processed/
│   │   └── chirps/           ← QC-passed, clipped, merged files
│   └── ancillary/
│       └── grid_mask/        ← Ethiopia land mask, target-grid definition
│
├── reports/
│   ├── qc_chirps/            ← QC diagnostic plots (PNG / HTML)
│   └── logs/                 ← download & processing logs (TXT / JSON)
│
├── docs/
├── notebooks/
└── ...

Convention: Never write processed outputs back into raw/.
This keeps raw data pristine and makes the pipeline fully reproducible.

Notebook walk-through¶

Open the companion notebook for an interactive, cell-by-cell version of steps 2–5:

00_environment_setup_folder_structure.ipynb

Next steps¶

Once your environment is active and the folder structure is in place, continue with:

1. Session 1.1 — Observational data access and downloading
2. Module 1 overview