🛠️ Helper Tools

A collection of helper tools included within SounderPy.

Returning a dictionary of profile parameters

Return a dictionary of common calculated sounding paramters and special variables for a given vertical profile.

Data returned in this dictionary include…

an interpolated version of the profile
basic parameters such as mixing ratio, theta-e, wet-bulb, etc
Thermodynamic parameters such as SB, MU, ML parcel properties (LCL, LFC, EL, CAPE, CIN, etc), Entrainment CAPE, etc
Kinematic parameters such as storm motion, storm-relative wind, streamwise vorticity, SRH, composite parameters, etc

class sounding_params(clean_data, storm_motion='right_moving', modify_sfc=None)

Parameters:

clean_data (dict, required) – the dictionary of profile data to calculate profile parameters for (see 🌐 Tools for Getting Data)
storm_motion (str or list of floats, optional) – the storm motion used for calculations. Default is ‘right_moving’. Custom storm motions are accepted as a list of floats representing direction and speed. Ex: [270.0, 25.0] where ‘270.0’ is the direction in degrees and ‘25.0’ is the speed in kts. See the Storm Motion Logic section for more details.
modify_sfc (None or dict, optional, default is None) – a dict in the format {'T': 25, 'Td': 21, 'ws': 20, 'wd': 270} to modify the surface values of the clean_data dict.

.calc()

Returns:: special sounding parameters
Return type:: dict

Example:

spy.sounding_params(clean_data).calc()

Note

These calculated parameters are the same used on SounderPy plots. This function simply returns the master dictionary of all of these values.

Saving data to a file

spy.to_file(file_type, clean_data, filename=None, convert_to_AGL=True)

Create a file of ‘cleaned’ SounderPy data

Parameters:

file_type (str, required) – a str representing the file type you’d like to export data to.
clean_data (dict, required) – ‘cleaned’ SounderPy data dict
filename (str, required) – the name you’d like to give the file
convert_to_AGL (bool, optional, default is True) – whether or not to convert height values to “above ground level” when saving to a file. Useful for CM1.

Returns:

a file of SounderPy data.

Example:

File options include csv, cm1, & sharppy

spy.to_file('csv', clean_data)
spy.to_file('cm1', clean_data)
spy.to_file('sharppy', clean_data)

Merging two profiles via weighted averaging

Merge two profiles together using weighted averaging of values along a common height axis to return a single profile.

spy.merge_profiles(profile_a, profile_b, weight_a)

Parameters:

profile_a (dict, required) – a SounderPy `clean_data`dictionary containing variable arrays for profile_a.
profile_b (dict, required) – a SounderPy clean_data dictionary containing variable arrays for profile_b.
weight_a (float, optional) – the weight for profile_a in the averaging scheme, default is 0.5 (50%)

Returns:

a clean_data dictionary with weighted-averaged values for z, T, Td, u, v, and p without metadata (see example below)

Return type:

dict

Example:

# load in some sounding data
profile_a = spy.get_obs_data("OAX", "2014", "06", "16", "18")
profile_b = spy.get_obs_data("OAX", "2014", "06", "17", "00")

# apply `merge_profiles()` function
merged_profile = spy.merge_profiles(profile_a, profile_b, weight_a=0.6)

# reapply profile metadata and plot titles
merged_profile['site_info'] = {'site-id': 'KOAX',
                          'site-name': 'OMAHA VALLEY',
                          'site-lctn': 'NE US',
                          'site-latlon': [41.32, -96.37],
                          'site-elv': 350,
                          'source': 'RAOB OBSERVED PROFILE',
                          'model': 'none',
                          'fcst-hour': 'none',
                          'run-time': 'none',
                          'valid-time': 'none',
                          'box_area': 'none'}
merged_profile['titles'] =  {'top_title':   'COMPOSITE VERTICAL PROFILE',
                          'left_title':  'Profile-a (60%): 18z OAX 06/16/2014 | Profile-b (40%): 18z OAX 06/16/2014',
                          'right_title': 'KOAX, OMAHA VALLEY, NE | 41.32, -96.37    '}

# build a sounding
spy.build_sounding(merged_profile, radar=None, special_parcels='simple')

Smooth a profile

Apply a simple SciPy gaussian smoother to a SounderPy clean_data profile

spy.smooth_profile(clean_data, sigma)

Parameters:

clean_data (dict, required) – a SounderPy `clean_data`dictionary.
sigma (float, optional) – from SciPy: “Standard deviation for Gaussian kernel”. Default is 0.5.

Returns:

a clean_data dictionary with smoothed values for z, T, Td, u, v, and p. Metadata remains unchanged.

Return type:

dict

Here is an (extreme) example:

# load in some sounding data
clean_data = spy.get_obs_data("OAX", "2014", "06", "16", "18")

smoothed_profile = spy.smooth_profile(clean_data, 3)
spy.build_sounding(smoothed_profile, radar=None, special_parcels='simple')

Finding site lat/lon pairs

spy.get_latlon(station_type, station_id)

Return a latitude-longitude float pair in a list

Parameters:

station_type (str, required) – the station ‘type’ that corresponds with the given station ID
station_id (str, required) – the station ID for the given station type

Returns:

lat/lon float pair

Return type:

list

Example:

spy.get_latlon('metar', 'kmop')
spy.get_latlon('bufkit', 'apx')
spy.get_latlon('raob', 'oun')
spy.get_latlon('buoy', '45210')

note: you can use this lat/lon pair list when calling the function get_model_data

Interpolating a vertical profile

spy.interp_data(variable, heights, step=100)

Interpolate a 1D array of data (such as a temperature profile) over a given interval (step) based on a corresponding array of height values.

Parameters:

variable (arr, required) – an array of data to be interpolated. Must be same length as height array.
heights (arr, required) – heights corresponding to the vertical profile used to interpolate. Must be same length as variable array.
step (int, optional) – the resolution of interpolation. Default is 100 (recommended value is 100)

Returns:

interp_var, an array of interpolated data.

Return type:

arr

Example:

spy.interp_data(temperature_array, height_array, step=100)

Finding a ‘nearest’ value

spy.find_nearest(array, value)

Return a value of an index of an array who’s value is closest to a define value.

Parameters:

array (arr, required) – an array of data to be searched through
heights (int or float, required) – the value used to compare against the array of data

Returns:

nearest_idx, index of the data array that corresponds with the nearest value to the given value

Return type:

int

Example:

z_equals_500m = spy.interp_data(z, 500)

Printing data to the console

spy.print_variables(clean_data, storm_motion='right_moving', modify_sfc=None)

Parameters:

clean_data (dict, required) – the dictionary of profile data to calculate profile parameters for (see 🌐 Tools for Getting Data)
storm_motion (str or list of floats, optional) – the storm motion used for calculations. Default is ‘right_moving’. Custom storm motions are accepted as a list of floats representing direction and speed. Ex: [270.0, 25.0] where ‘270.0’ is the direction in degrees and ‘25.0’ is the speed in kts. See the Storm Motion Logic section for more details.
modify_sfc (None or dict, optional, default is None) – a dict in the format {'T': 25, 'Td': 21, 'ws': 20, 'wd': 270} to modify the surface values of the clean_data dict.

Returns:

prints a number of thermodynamic and kinematic variables to the console.

Return type:

data print out to the console

> THERMODYNAMICS ---------------------------------------------
--- SBCAPE: 2090.8 | MUCAPE: 2090.8 | MLCAPE: 1878.3 | MUECAPE: 1651.9
--- MU 0-3: 71.1 | MU 0-6: 533.0 | SB 0-3: 71.1 | SB 0-6: 533.0

> KINEMATICS -------------------------------------------------
--- 0-500 SRW: 35.0 knot | 0-500 SWV: 0.019 | 0-500 SHEAR: 21.8 | 0-500 SRH: 186.2
--- 1-3km SRW: 20.9 knot | 1-3km SWV: 0.005 | 1-3km SHEAR: 14.1 | | 1-3km SRH: 54.0