Thank you for your interest in contributing to 3D Polar Vortex! This project aims to build a collaborative gallery of 3D visualizations of Sudden Stratospheric Warming (SSW) events.
Anyone can generate a new 3D visualization of an SSW event using the script included in this repository and submit it as a Pull Request.
-
ERA5 data: You will need to download daily ERA5 data from the Copernicus Climate Data Store:
- Zonal wind (
u) at 10 hPa. - Geopotential (
z) at multiple pressure levels.
- Zonal wind (
-
Conda environment: Install the required dependencies using the provided environment file:
conda env create -f SSW_env.yml conda activate SSW_env
-
Git installed and a GitHub account.
# Fork on GitHub and then clone your fork
git clone https://github.com/YOUR_USERNAME/SSWs-vortex-plot.git
cd SSWs-vortex-plotconda env create -f SSW_env.yml
conda activate SSW_envEdit the configuration parameters in 3d_SSWvortex_plev_ght_anom_1yr.py:
# ============================================================
# CONFIGURATION — modify these parameters for your event
# ============================================================
U_NC_FILE = "path/to/your/era5.u.10hPa.day.nc"
Z_NC_FILE = "path/to/your/era5.z.allhPa.day.lev.nc"
OUTPUT_HTML = "3d.ght.anon.animation.ssw.YYYY.YYYY.html"
DATE_START = "YYYY-MM-DD" # Start of the Day 0 search period
DATE_END = "YYYY-MM-DD" # End of the Day 0 search period
DAYS_BEFORE = 10 # Days before Day 0
DAYS_AFTER = 20 # Days after Day 0
PERCENTIL = 0.8 # Percentile threshold (0.8 = show only the 20% most extreme)
LAT_REF = 60.0 # Reference latitude for wind reversal detection
EVENTO = "SSW YYYY-YYYY" # Event titleNote: The script detects Day 0 by finding the first day where the zonal wind (
u) at the reference latitude is negative for a minimum number of consecutive days (default: 10). If you modify this threshold, make sure to document it (see step 6).
Run the script to generate the .html file:
python 3d_SSWvortex_plev_ght_anom_1yr.pyMove the resulting HTML file to the events/ folder:
mv 3d.ght.anon.animation.ssw.YYYY.YYYY.html events/Open index.html and locate the comment <!-- Add future events here -->. Insert your new <li> block in chronological order (newest first). The page displays events in a two-column grid (on wide screens), reading left-to-right, top-to-bottom — so the most recent event should be at the top-left and the oldest at the bottom-right.
If your event is more recent than existing entries, place it before them. If it is older, place it after the existing entries but before the <!-- Add future events here --> comment.
Include your initials in the description, linked to your entry in CONTRIBUTORS.md:
<li class="event-card" onclick="window.location.href='events/3d.ght.anon.animation.ssw.YYYY.YYYY.html'">
<div class="event-link">
<h2 class="event-title">SSW YYYY-YYYY</h2>
<p class="event-desc">Evolution of the YYYY-YYYY Sudden Stratospheric Warming event.
Explore the 3D geopotential height anomalies through an interactive timeline.
By <a href="CONTRIBUTORS.md#your-full-name" class="contributor-link" onclick="event.stopPropagation()">XY</a>.
</p>
<span class="event-meta">Interactive 3D Plot</span>
</div>
</li>Important: Replace
XYwith your name and surname initials. The anchor#your-full-namemust match the anchor of your entry inCONTRIBUTORS.md(see next step).
Open CONTRIBUTORS.md and add your entry following the template. You must include:
- Your full name (as header)
- Your social/contact links (only the ones you want to share)
- The event(s) you contributed
- A technical parameters table for each event, so other users can understand how the visualization was produced:
| Parameter | Description |
|---|---|
| Variable | Variable used: GHT (Geopotential Height), T (Temperature in °C), etc. |
| Field type | Type of field plotted: anomalies, real field, climatology, etc. |
DATE_START |
Start date of the Day 0 search period |
DATE_END |
End date of the Day 0 search period |
DAYS_BEFORE |
Days before Day 0 in the animation |
DAYS_AFTER |
Days after Day 0 in the animation |
PERCENTIL |
Percentile threshold used |
LAT_REF |
Reference latitude (typically 60°N) |
| Min. consecutive days | Minimum consecutive days of u < 0 used for Day 0 detection |
| Pressure levels | commons / commons + levX, levY hPa / commons - levX, levY hPa |
| Temporal averaging | Type of averaging used (daily, running mean, etc.) |
| Data source | Dataset and version (e.g., ERA5 daily, 2.5° resolution) |
| Day 0 detected | Exact Day 0 date detected by the script |
Pressure levels notation: The common levels used in this project are defined in README.md. If you used the same 26 levels, write
commons. If you added extra levels, writecommons + levX, levY hPa. If you used fewer, writecommons - levX, levY hPa.
See CONTRIBUTORS.md for the full template and examples.
git checkout -b add-ssw-YYYY-YYYY
git add events/3d.ght.anon.animation.ssw.YYYY.YYYY.html
git add index.html
git add CONTRIBUTORS.md
git commit -m "Add SSW YYYY-YYYY event visualization"
git push origin add-ssw-YYYY-YYYYThen, open a Pull Request on GitHub with:
- A descriptive title:
Add SSW YYYY-YYYY visualization - The technical parameters in the PR description (see table in step 6)
Before submitting your PR, verify that:
- The HTML file has been generated correctly and opens without errors
- The file is in the
events/folder - You have added your entry in
index.htmlbefore the<!-- Add future events here -->comment - Your initials appear in the event description and link to
CONTRIBUTORS.md - You have added your entry in
CONTRIBUTORS.mdwith your name, event(s), and technical parameters - The technical parameters are documented in your
CONTRIBUTORS.mdentry - The HTML file name follows the format:
3d.ght.anon.animation.ssw.YYYY.YYYY.html
- HTML file name:
3d.ght.anon.animation.ssw.YYYY.YYYY.html(orsswmfor minor events). - Event ordering: Events are displayed in a two-column grid, ordered newest first (top-left → bottom-right). Place your entry in the correct chronological position.
- Initials: Use the initials of your first name and surname (e.g., Óscar Mata-Romero → OMR).
- Anchor in CONTRIBUTORS.md: Your name in lowercase, without accents, separated by hyphens (e.g.,
#oscar-mata-romero). - Variable: Specify the variable used (GHT, T in °C, etc.). Temperature must always be reported in °C.
- Pressure levels: Use the
commonsnotation system described in README.md to reference the standard 26 pressure levels.
- Do not upload NetCDF data files to the repository; they are too large. Only the generated HTML.
- If you have questions, open an Issue before starting.
- Contributions are subject to the same project licenses: CC BY-NC-SA 4.0 for content and GNU AGPLv3 for source code.
We look forward to your contribution! 🌍