pysonde: A Python repository from sodoesaburningbus

This package contains contains the PySonde module
A PySonde class provides utilities for interfacing with several
common sounding formats, including cloud-based data from the university of Wyoming.
It also provides utilities for common applications such as plotting, CAPE calculations, and LLJ identification.
Further, once a sounding is loaded, it can be written out for
other applications such as input to the WRF SCM.
By default, the object supports unit aware computing, but the option exists to strip
units from the sounding.

The object only supports one sounding per file. If more are present, the reader will likely break. If it does not, use
the output at your own risk.

If this code is useful in a research project, please contact
Christopher Phillips and provide an acknolwedgement in any publications.
If the software is a key part of the analysis, please consider offering co-authorship.

Any questions or suggestions should be directed to Christopher Phillips at chris.phillips@uah.edu

Written by Christopher Phillips
Atmopsheric and Earth Science Department
University of Alabama in Huntsville, June 2020

Module requirements
Python 3+
Matplotlib
MetPy 1+
NetCDF4
Numpy

------------------------------------INSTALLATION------------------------------------

The PySonde package may be installed with pip:

pip install git+https://github.com/sodoesaburningbus/pysonde

Or manually:

Get PySonde:
git clone https://github.com/sodoesaburningbus/pysonde
cd pysonde
python3 setup.py install
cd ..

------------------------------------CURRENT AND FUTURE SOUNDING FORMATS------------------------------------

Currently supports:
NWS - NWS high density soundings
CSWR - Center for Severe Weather Research L2 soundings
EOL - National Center for Atmospheric Research - Earth Observing Laboratory soundings
UAH - University of Alabama in Huntsville UPSTORM group soundings
WRF - Weather Research and Forecasting Single Column Model Input Sounding
WYO - University of Wyoming sounding file
WYOWEB - University of Wyoming sounding online archive. (These are pulled from online.)
IGRA2 - The IGRA2 online sounding archive. (These are pulled from online.)
PSF - PySonde Sounding Format, a netCDF4 format more fully described in the documentation.
CSV - CSV files originally outputted by PySonde

Future updates also plan to add support for the following sounding formats
SPC sounding archive

------------------------------------CURRENT FEATURES------------------------------------

All methods and attributes are fully documented in the PySonde.py module file.
Summaries are presented here.
Currently, the PySonde object has the following attributes and methods:

Attributes:

General:
fpath - The location of the sounding file
sformat - The sounding format
sounding - A dictionary containing the sounding variables with Pint (MetPy) units attached.
sounding_units - A dictionary containing the units used by PySonde
units - The MetPy unit object

Thermo:
lcl_alt - The height of the Lifting Condensation Level
lcl_pres - The pressure of the Lifting Condensation Level
lfc_alt - The height of the Level of Free Convection
lfc_pres - The pressure of the Level of Free Convection
lfc_temp - The environmental temperature at the Level of Free Convection
parcel_path - The temeprature profile of a parcel lifted from the surface
pw - Precipitable Water
sfc_cape - The sounding's CAPE using a near-surface parcel
sfc_cin - The sounding's CIN using a near-surface parcel

PBLH:
sbi - Whether a Surface-Based Inversion exists
sbih - The depth of the Surface-Based Inversion
sbih_ind - The sounding data index of the Surface-Based Inversion top
sbih_pres - The pressure of the top of the Surface-Based Inversion
pblh - The depth of the Planetary Boundary Layer
pblh_ind - The sounding data index of the top of the Planetary Boundary Layer
pblh_pres - The pressure at the top of the Planetary Boundary Layer

Methods (For the user; others exist that are used internally by the object.):

basic_skewt(nbarbs=None, llj=False, pblh=False, sbi=False) - Returns a MetPy SkewT figure object. options exist for
highlighting the PBL top, LLJ, and any surface-based inversion. Wind barb spacing can also be passed in.

calculate_Cn2() - Compute the index of refraction structure parameter Cn^2 using the methodology
found in Fiorino and Meier 2016 "Improving the Fidelity of the Tatarskii Cn2 Calculation with Inclusion
of Pressure Perturbations"

calculate_gph(units=True) - Compute geopotential height from the sounding by integrating the hypsometric equation.
By default returns geopotential height with untis attached.

calculate_pres(units=True) - Compute the hydrostatic pressure profile by integrating hypsometric equation.
By default returns the hydrostatic pressure with untis attached.

calculate_layer_thickness(level1, level2) - Calculate the thickness between 2 pressure levels. Requires units on input.

extract_level(level) - Extract observations for a single pressure level from the sounding. If units are not used in input, then pressure must be hPa.

find_llj() - Outputs a dictionary contianing the altitude, pressure, speed, and direction of the low-level jet
if present in a sounding. Also returns the category of the jet. Methodology follows that of Yang et al. 2020
"Understanding irrigation impacts on low-level jets over the Great Plains" in Climate Dynamics"

strip_units() - Return a dictionary containing the sounding without MetPy units attached.

write_csv(save_path) - Converts sounding to an easily accessed CSV format at the specified file location.

write_interpolated_csv(levs, save_path, coords="Z", write=True) - Interpolates a sounding to the desired coordinates
in either height or pressure. Can optionally write to a file or output a dicionary with the inteprolated sounding.

write_rams(save_path, maxz=None) - Write a RAMS input sounding.

write_wrfscm(save_path) - Write a WRF single-column model input sounding

sonde.

------------------------------------FUTURE UPDATES------------------------------------

Add installation via pip

Options to calculate mixed layer and most unstable CAPE

---------------------------------------------EXAMPLES---------------------------------------------

For full examples, please see the example/ directory. The creation of the PySonde object is clarified here.

Example creation of the PySonde object

from pysonde.pysonde import PySonde
sonde = PySonde(sounding_file_path, format_code, units=True)

Accessing the sounding data (e.g. temperature) may then be accomplished via:

sonde.sounding["temp"]

sounding_file_path, string, path to file containing a single sounding
format_code, string, format of the sounding, see below for the options
units, boolean, optional, default=True, whether to attach units to variables via MetPy.