🎈 SounderPy

VERTICAL PROFILE DATA RETRIEVAL & ANALYSIS FOR PYTHON

Retrieve, analyze, visualize, and export atmospheric vertical profiles from observations, forecasts, reanalyses, and numerical models.

🚀 Get Started 👨‍🍳 Tutorials 📊 Plot Gallery 📚 Reference

pip install sounderpy

conda install sounderpy

Start Here

🚀 Getting Started

Install SounderPy, retrieve a profile, and create your first sounding.

Start learning →

👨‍🍳 Tutorials

Step-by-step guides for plots, radar, parcels, hodographs, data sources, exports, and command-line workflows.

Browse tutorials →

📊 Plot Gallery

Explore sounding, hodograph, composite, radar, parcel, and data-source examples.

View gallery →

🌎 Data Sources

Work with RAOB, ACARS, RAP/RUC, BUFKIT, ERA5, NCEP, WRF, CM1, and custom vertical profiles.

Explore data sources →

📚 Reference

Find detailed retrieval, plotting, calculation, and helper-function documentation.

Open reference →

💻 Command Line Interface

Retrieve, plot, export, and automate SounderPy directly from a terminal.

Use the CLI →

Get a Sounding in Seconds

SounderPy provides the same core workflow through both Python and the command line.

Python

import sounderpy as spy

data = spy.get_obs_data(
    "OAX",
    "2014", "06", "16", "18")

spy.build_sounding(data)

Command Line

sounderpy obs OAX 2014-06-16 18 \
    --plot sounding

One Workflow, Many Data Sources, Several Plotting Options

Observations

RAOB, IRGAv2, ACARS

Forecasts

BUFKIT: HRRR, RAP, GFS, etc

Reanalysis

RAP, RUC, ERA5, NCEP-FNL

Modeling Systems

CM1, WRF, MPAS

Custom Sources

SHARPPY + more

Soundings

Full Skew-T, Log-P diagram and hodograph figure.

Hodographs

Simple hodograph figure.

Composite Soundings

Several profiles on one sounding.

Learn how SounderPy handles data →

What’s New in SounderPy 3.2.0

SounderPy 3.2.0 expands both how data are retrieved and how SounderPy can be used.

• 💻 New command line interface for retrieval, plotting, JSON, and export.

• 🌦️ Updated RAP/RUC reanalysis data access with modern GRIB2 archives.

• 📈 New and improved sounding plot features (such as storm-relative wind barbs and DPI settings)

• 🎈 Restored access to UW RAOB database.

• 📁 New file-io workflow for saving data to a file and for opening SHARPPY files.

• 📚 Expanded task-oriented tutorials and visual plot gallery.

• 🧰 Improved packaging, testing, and release infrastructure.

Try the CLI →

Using SounderPy in Research?

SounderPy is open-source scientific software developed for atmospheric vertical profile retrieval, analysis, and visualization.

About SounderPy GitHub PyPI Operational SounderPy Site

☕ SounderPy is a open-source package developed on my own time. Would you like to support continued SounderPy development? Consider “Buying me a coffee”! ☕

Directory

General:

• 🚀 Getting Started
  • Step 1: Install SounderPy
  • Step 2: Import SounderPy
  • Step 3: Create Your First Sounding
  • Step 4: Examining the Data
  • Step 5: Where to Go Next
  • A Complete First Example
  • Ready for More?
• 📖 About
  • About SounderPy: An Atmospheric Sounding Visualization and Analysis Tool for Python
  • Community and Use
  • Citing SounderPy
  • Authors and Contributors
  • About the Author
  • Useful Links
  • Getting Started
  • References
  • Publications Using SounderPy
• ❓ Troubleshooting
  • Testing SounderPy
  • Funky Plot Scaling
    • The Fix: saving the plot to a file
  • Goofy ACARS Profiles
  • ERA5 data access not working
  • RAP data won’t load
  • SounderPy can’t find a RAOB sounding you know exists
• 🌍 Community
  • Submitting Issues, Ideas, & Suggestions
  • Contributing to SounderPy

API Reference:

• 🌐 Tools for Getting Data
  • Available Data Sources
  • Model Reanalysis Data | RAP/RUC, ERA5, NCEP
    • spy.get_model_data()
    • Model key names
    • Dataset key names
    • Latitude-Longitude pairs
    • Example
  • Model Forecast Data | BUFKIT Profiles
    • spy.get_bufkit_data()
    • Available BUFKIT Sites:
    • Available Models:
    • Model key names
    • Example
    • Latest Available Forecast
  • Observed Data | RAOB & IGRAv2 Profiles
    • spy.get_obs_data()
    • Station Identifiers
    • Available RAOB Sites:
    • Example
  • Observed Data | ACARS Aircraft Profiles
    • acars_data
      • acars_data.list_profiles()
      • acars_data.get_profile()
    • ACARS Data Retrieval Example
  • What Does SounderPy Return?
• ✏️ Custom Data Sources
  • Built-in Custom Data Ingestion Tools
    • Ingesting WRF Output Data
      • spy.make_wrf_profile()
    • Ingesting CM1 input_sounding Data
      • spy.make_cm1_profile()
    • Ingesting SHARPPY Files
      • spy.from_sharppy()
    • Creating Custom clean_data
• 🧼 The clean_data Schema
  • Core Schema
  • Profile Array Requirements
  • Units
  • site_info Metadata
  • Plot Titles
  • Optional Profile Variables
  • Example clean_data Dictionary
  • Inspecting a Profile
  • Why the Schema Matters
• 📈 Tools for Plotting Data
  • Building Soundings
    • spy.build_sounding()
    • Example
  • Building Hodographs
    • spy.build_hodograph()
    • Example
  • Building Composite Soundings
    • spy.build_composite()
    • Examples
  • Building VAD Hodographs
    • spy.build_vad_hodograph()
    • Examples
  • Surface Modification Logic
    • The modify_sfc dict
  • Storm Motion Logic
    • Storm Motion Keys
    • Custom Storm Motions
  • Parcel Logic
    • How to use this feature
    • Parcel Keys
  • Radar Logic
    • Using the Map
    • Using Radar
  • About These Plots
• 🛠️ Helper Tools
  • Returning a dictionary of profile parameters
    • sounding_params
      • sounding_params..calc()
  • Saving data to a file
    • spy.to_file()
  • Merging two profiles via weighted averaging
    • spy.merge_profiles()
  • Smooth a profile
    • spy.smooth_profile()
  • Finding a station latitude/longitude
    • spy.get_latlon()
  • Interpolating a vertical profile
    • spy.interp_data()
  • Finding a ‘nearest’ value
    • spy.find_nearest()
  • Printing data to the console
    • spy.print_variables()
• 💻 Command Line Interface (CLI)
  • Checking the Installed Version
  • Gettings Data With The CLI
    • Observed Soundings
    • Model Reanalysis Data
    • BUFKIT Forecast Profiles
    • ACARS Aircraft Observations
  • Saving Data to a File
    • Saving to JSON
    • Saving to CSV, SHARPPY, CM1
  • Plotting from the CLI
    • Sounding Plot
    • Hodograph
    • Plot Options
  • Combining Retrieval, Export, and Plotting
  • Verbose Output
  • Input Validation and Errors
    • Dates
    • Hours
    • Latitude and Longitude
    • Forecast Hours
    • Box Size
  • Additional Examples
  • Using the Python Module Entry Point

Tutorials:

• 👨‍🍳 SounderPy Beginner’s Cookbook
  • Before We Get Started
    • Helpful resources
  • Recipe 1 — Set Up SounderPy
  • Recipe 2 — Retrieve Your First Observed Sounding
  • Recipe 3 — Understand clean_data
  • Recipe 4 — Customize a SounderPy Sounding
  • Recipe 5 — Build and Modify a Hodograph
  • Recipe 6 — Retrieve Other Data Sources
  • Recipe 7 — Calculate Sounding Parameters
  • Recipe 8 — Compare Multiple Profiles
  • Recipe 9 — Export a Profile
  • Recipe 10 — Use the SounderPy Command Line
  • Troubleshooting Tips
  • 🎉 You Finished the SounderPy Beginner’s Cookbook!
  • Where to go next
• 📊 Plot Gallery
  • Light and Dark Themes
  • Color-Deficiency-Friendly Settings
  • Map and Radar Settings
    • Map Zoom
  • Parcel Settings
    • Custom Parcel Configuration
  • Additional Plot Options
    • Theta and Theta-e
    • Ground-Relative vs Storm-Relative Hodographs
    • Custom Storm Motion
    • Hodograph Boundary
  • Different Data Sources
  • Composite Soundings
  • Continue Learning
• 📚 Tutorials
  • 🎨 Plot Appearance & Accessibility
    • Retrieve the Example Sounding
    • Light and Dark Soundings
      • Light Mode
      • Dark Mode
    • Light and Dark Hodographs
    • Color-Deficiency-Friendly Soundings
      • Standard Colors
      • Color-Deficiency-Friendly Colors
    • Combining Appearance Options
    • Saving Figures
    • CLI Equivalents
    • Next Steps
  • 🗺️ Maps & Radar
    • Retrieve an Example Sounding
    • Disable the Map
    • Display a Map without Radar
    • Change the Map Extent
    • Single-Site Radar
    • Radar Mosaic
    • Radar Timing
    • The Same Options on Hodographs
    • CLI Examples
    • Troubleshooting
    • Next Steps
  • 🧪 Parcel Settings
    • Retrieve the Example Sounding
    • Default Parcel Behavior
    • Simple Parcel Behavior
    • Custom Parcel Configuration
    • Understanding Parcel Codes
      • Parcel Type
      • Adiabatic Scheme
      • CAPE Type
    • Valid Parcel Codes
    • Highlight Multiple Parcels
    • Performance Considerations
    • Next Steps
  • 🌀 Hodograph Options
    • Retrieve the Example Profile
    • Ground-Relative Hodograph
    • Storm-Relative Hodograph
    • Selecting Storm Motion
    • User-Defined Storm Motion
    • Hodograph Boundaries
    • Theme and Output Options
    • CLI Examples
    • Next Steps
  • 🌎 Working with Data Sources
    • The Core clean_data Structure
    • Observed RAOB / IGRA Profiles
    • RAP/RUC Reanalysis
    • Other Model/Reanalysis Sources
    • BUFKIT Forecast Profiles
    • ACARS Aircraft Profiles
    • Why clean_data Matters
    • Model Output and Custom Data
    • CLI Equivalents
    • Next Steps
  • 📚 Composite Soundings
    • Retrieve Several Profiles
    • Basic Composite
    • Dark-Mode Composite
    • Shading between Temperature and Dewpoint
    • Choosing a Colormap
    • Custom Colors
    • Line Styles
    • Line Widths
    • Opacity
    • Combine Styling Options
    • Compare Different Data Sources
    • Save the Figure
    • Next Steps
  • 💾 Exporting Data
    • Retrieve an Example Profile
    • CSV Export
    • SHARPpy Export
    • Read a SHARPpy File Back into SounderPy
    • CM1 Export
    • AGL Height Handling for CM1
    • Default Filename
    • CLI Export
    • Export and Plot in One CLI Command
    • Choosing an Export Format
    • Next Steps
  • 💻 Command Line Workflows
    • Check the Installation
    • Observed Soundings
    • Model/Reanalysis Profiles
    • BUFKIT Forecasts
    • ACARS Profiles
    • Create a Sounding Plot
    • Create a Hodograph
    • Plot Styling
    • Export a Profile
    • Combine Retrieval, Export, and Plotting
    • JSON Output
    • JSON and a Saved Plot
    • Verbose Mode
    • Simple Shell Batch Workflow
    • Check Exit Status in Scripts
    • Use python -m sounderpy
    • Next Steps
  • Tutorial Overview
    • 🎨 Plot Appearance & Accessibility
    • 🗺️ Maps & Radar
    • 🧪 Parcel Settings
    • 🌀 Hodograph Options
    • 🌎 Working with Data Sources
    • 📚 Composite Soundings
    • 💾 Exporting Data
    • 💻 Command Line Workflows
  • Gallery Figures
• 🌪️ Case Study: Mound City, SD
  • Case Study Goals
  • Event Timeline
  • A Note on Spatial Representativeness
  • 1. Morning Observed Environment
  • 2. Morning HRRR Forecast
  • 3. Evening Observed Environment
  • 4. Local RAP Reanalysis
  • 5. Compare the Profiles
    • The Thermodynamic Profile
    • The Kinematic Profile
  • Event Context
  • Continue Exploring

• Index