๐ SounderPy๏
VERTICAL PROFILE DATA RETRIEVAL & ANALYSIS FOR PYTHON
Retrieve, analyze, visualize, and export atmospheric vertical profiles from observations, forecasts, reanalyses, and numerical models.
pip install sounderpy
conda install sounderpy
Start Here๏
๐ Getting Started
Install SounderPy, retrieve a profile, and create your first sounding.
๐จโ๐ณ Tutorials
Step-by-step guides for plots, radar, parcels, hodographs, data sources, exports, and command-line workflows.
๐ Plot Gallery
Explore sounding, hodograph, composite, radar, parcel, and data-source examples.
๐ Data Sources
Work with RAOB, ACARS, RAP/RUC, BUFKIT, ERA5, NCEP, WRF, CM1, and custom vertical profiles.
๐ Reference
Find detailed retrieval, plotting, calculation, and helper-function documentation.
๐ป Command Line Interface
Retrieve, plot, export, and automate SounderPy directly from a terminal.
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.
Whatโs New in SounderPy 3.3.0๏
SounderPy 3.3.0 rebuilds the plotting module and makes every figure easier to customize.
๐ SounderPyโs plot module is fully rebuilt and refactored allowing for increased figure customization and generation speed. Most figures are roughly 50% faster.
๐จ The new figure kwarg
themelets you set your own colors while credit text and logo can be changed withspy.set_watermark().๐ Full sounding and composite figures now include a
ylimkwarg, allowing you to adjust the Skew-Tโs y-axis (pressure) limits.๐งฉ Composite soundings have been completely rebuilt. Composites include a table of various parameters, normalized kwarg names, and support for custom data sources.
๐บ๏ธ VAD hodographs now include the map, radar, hodograph boundary, and DPI options of the other figures.
โ๏ธ New winter sounding:
build_sounding(mode='winter')draws a sounding built around precipitation type, snow growth, and winter hazards.mode='auto'picks the winter sounding when the surface wet-bulb is below 35 degrees F, andshow_obs=Trueadds the latest surface observation. See โ๏ธ Winter Soundings.๐งฎ
spy.winter_params(clean_data).calc()returns everysounding_paramsvalue plus the winter values behind the winter sounding.๐ป The command line tool adds
--mode {severe,winter,auto}and--obsfor sounding plots.โ๏ธ ACARS profiles now use the airport elevation in meters (it was read in feet), which corrects the surface label and surface pressure.
๐งต RAP/RUC reanalysis GRIB parsing is now thread safe.
get_model_data('rap-ruc', ...)can run from several threads at once (for example, to fetch composite profiles in parallel); downloads still run in parallel while GRIB decoding takes turns.๐ฆ๏ธ The NAM and NAMNEST (NAM3km) BUFKIT forecasts are archive only after their NCEP decommissioning on Nov. 2nd, 2026.
๐ Refactored and redesigned documentation to match new SounderPy web app: sounderpy.app
Important
sounding_params(...).calc() and vad_params(...).calc() now return a dictionary
instead of a tuple, and build_composite()โs colors_to_use, ls_to_use,
alphas_to_use, and lw_to_use are renamed to colors, linestyles,
alphas, and linewidths. The old names still work in 3.3.0 but show a
FutureWarning, and will be removed in a later release. The data retrieval and file modules
(such as sounderpy.bufkit_data) moved into sounderpy.data (sounderpy.data.bufkit_data);
spy.* functions are unchanged, and the old module paths still work with a FutureWarning.
See ๐ ๏ธ Helper Tools and ๐ Tools for Plotting Data.
Using SounderPy in Research?๏
SounderPy is open-source scientific software developed for atmospheric vertical profile retrieval, analysis, and visualization.
โ 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:
API Reference:
- ๐ Tools for Getting Data
- โ๏ธ Custom Data Sources
- ๐งผ The
clean_dataSchema - ๐ Tools for Plotting Data
- ๐ ๏ธ Helper Tools
- Returning a dictionary of profile parameters
- Returning a dictionary of winter parameters
- Saving data to a file
- Merging two profiles via weighted averaging
- Smooth a profile
- Finding a station latitude/longitude
- Interpolating a vertical profile
- Finding a โnearestโ value
- Printing data to the console
- ๐ป Command Line Interface (CLI)
Tutorials:
- ๐ณ SounderPy Beginnerโs Cookbook
- Before We Get Started
- 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
- ๐ Tutorials
- ๐จ Plot Appearance & Accessibility
- ๐บ๏ธ Maps & Radar
- โ๏ธ Winter Soundings
- ๐งช Parcel Settings
- ๐ Hodograph Options
- ๐ Working with Data Sources
- ๐ Composite Soundings
- ๐พ Exporting Data
- ๐ป 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
- Calculated Parameters
- Work With a Saved File
- 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
- Example Notebooks
- Gallery Figures
- ๐ช๏ธ Case Study: Mound City, SD