Skip to content

Latest commit

 

History

History
192 lines (133 loc) · 8.29 KB

CONTRIBUTING.md

File metadata and controls

192 lines (133 loc) · 8.29 KB

🤝 Contributing Guide

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.


🎯 What can you contribute?

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.


📋 Prerequisites

  1. 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.
  2. Conda environment: Install the required dependencies using the provided environment file:

    conda env create -f SSW_env.yml
    conda activate SSW_env
  3. Git installed and a GitHub account.


🚀 Steps to contribute

1. Fork and clone the repository

# Fork on GitHub and then clone your fork
git clone https://github.com/YOUR_USERNAME/SSWs-vortex-plot.git
cd SSWs-vortex-plot

2. Set up the environment

conda env create -f SSW_env.yml
conda activate SSW_env

3. Generate your visualization

Edit 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 title

Note: 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.py

4. Place the generated file

Move the resulting HTML file to the events/ folder:

mv 3d.ght.anon.animation.ssw.YYYY.YYYY.html events/

5. Add your entry in index.html

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 XY with your name and surname initials. The anchor #your-full-name must match the anchor of your entry in CONTRIBUTORS.md (see next step).

6. Add your entry in CONTRIBUTORS.md

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, write commons + levX, levY hPa. If you used fewer, write commons - levX, levY hPa.

See CONTRIBUTORS.md for the full template and examples.

7. Submit your Pull Request

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-YYYY

Then, 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)

✅ Pull Request Checklist

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.html before 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.md with your name, event(s), and technical parameters
  • The technical parameters are documented in your CONTRIBUTORS.md entry
  • The HTML file name follows the format: 3d.ght.anon.animation.ssw.YYYY.YYYY.html

📐 Conventions

  • HTML file name: 3d.ght.anon.animation.ssw.YYYY.YYYY.html (or sswm for 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 commons notation system described in README.md to reference the standard 26 pressure levels.

💡 Notes

  • 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! 🌍