✏️ Custom Data Sources

A neat and very useful aspect of SounderPy is the “clean_data dictionary” that stores sounding data. This dictionary is fed into a SounderPy plotting function. The plotting functions are designed in such a way that any data can be passed to it, so long as the data maintains the SounderPy “clean_data dictionary” format.


Built-in Custom Data Ingestion Tools

Have model data or your own observations? Pipe them into SounderPy with these custom data tools and methods!

Note

from_wrf() and from_cm1() were called make_wrf_profile() and make_cm1_profile() before SounderPy 3.3.0. The old names still work, with a FutureWarning, and will be removed in a later release.

Ingesting WRF Output Data

spy.from_wrf(
ds,
latlon,
model_name='WRF-ARW',
run_name='CONTROL RUN',
box_avg_size=0.10,
time_idx=0,
)

Return a dict of ‘cleaned up’ WRF output profile data for a given location

Parameters:
  • ds (netCDF4.Dataset(), required) – a netcdf4 dataset object of your wrfout*.nc file (an opened dataset, not a file path)

  • latlon (list, required) – the latitude & longitude pair for sounding (ex: [44.92, -84.72])

  • model_name (str, recommended, default is "WRF-ARW") – the name of your model for plot titles

  • run_name (str, optional, default is "CONTROL RUN") – the name of your run for plot titles

  • box_avg_size (float, optional, default is 0.10) – the width, in degrees, of the box of grid points averaged into the profile. A box smaller than one grid cell uses the nearest grid point.

  • time_idx (int, optional, default is 0) – the index of the output time to use, for wrfout files with more than one time

Returns:

clean_data, a dict of ready-to-use vertical profile data including pressure, height, temperature, dewpoint, u-wind, v-wind, & model information

Return type:

dict

import sounderpy as spy
import netcdf4

# open your `wrfout*.nc` file as a netCDF4 dataset
wrf_ds = netCDF4.Dataset(filename_of_wrf_data)

# use `from_wrf()` to create a `clean_data` dictionary of sounding data
clean_data = spy.from_wrf(wrf_ds, [48.978, -100.861])

# Now, pass the 'clean_data' dictionary into the SounderPy `build_sounding` function
spy.build_sounding(clean_data)

Ingesting CM1 input_sounding Data

spy.from_cm1(filename, meta_data_dict)

Return a dict of CM1 input_sounding data

Parameters:
  • filename (str, required) – the filename of an input_sounding file

  • meta_data_dict (dict, required) – a simple dictionary of metadata for the profile (see ‘CM1 Example’)

Returns:

clean_data, a dict of ready-to-use vertical profile data including pressure, height, temperature, dewpoint, u-wind, v-wind, & model information

Return type:

dict

import sounderpy as spy

# create this simple dict of information for your profile
# latitude & longitude are required. elevation (m) defaults to 0 m and the
# titles default to "CM1 INPUT SOUNDING" and blank left & right titles
meta_data_dict = {
 'latlon': [45.100, -100.89],
 'elev': 358,
 'top_title': f"CUSTOM CM1 COMPOSITE SOUNDING",
 'left_title': f"Near-storm inflow RUC sounding for the El-Reno EF3 tornado",
 'right_title': f"May 24, 2011"}

# use `from_cm1()` to create a `clean_data` dictionary of sounding data
clean_data = spy.from_cm1(input_sounding_filename, meta_data_dict)

# Now, pass the 'clean_data' dictionary into the SounderPy `build_sounding` function
spy.build_sounding(clean_data)

Note

CM1 input_sounding height data should be “AGL”, or “above ground level”. This means you’ll need an elevation value to plot your profile correctly. Find the elevation of where this profile is “supposed to be” and add it to the meta_data_dict. Without one, SounderPy warns and places the surface at 0 m.


Ingesting SHARPPY Files

spy.from_sharppy(filepath)

Return a dict of ‘cleaned up’ WRF output profile data for a given location

Parameters:

filepath (str, required) – filepath to your SHARPPY data file

Returns:

clean_data, a dict of ready-to-use vertical profile data including pressure, height, temperature, dewpoint, u-wind, v-wind

Return type:

dict

Note

To plot your SHARPPY file data with SounderPy, you’ll have to manually provide additional site meta-data. Be sure to include a site ID, name, location, lat/lon, and elevation. You must also create plot titles for the sounding plot. from_sharppy reminds you with a SounderPyNotice warning (it no longer prints).

import sounderpy as spy

# set file path
file_path = "Downloads/sounding_data/09082024_04Z"

# open your data
clean_data = spy.from_sharppy(file_path)

# manually set profile meta-data
data['site_info'] = {'site-id': 'KGFK',
                     'site-name': 'GRAND FORKS INTL',
                     'site-lctn': 'ND',
                     'site-latlon': [47.95, -97.18],
                     'site-elv': 257,
                     'source': 'BUFKIT FORECAST PROFILE',
                     'model': 'RAP',
                     'fcst-hour': 'F00',
                     'run-time': ['2024', '09', '28', '04'],
                     'valid-time': ['2024', '09', '28', '04']}

data['titles'] = {'top_title': 'BUFKIT MODEL FORECAST PROFILE | 04Z RAP F00',
                  'left_title': ' RUN: 09/28/2024 04Z  |  VALID: 09/28/2024 04Z',
                  'right_title': 'KGFK - GRAND FORKS INTL, ND | 47.95, -97.18    '}

# Now, pass the 'clean_data' dictionary into the SounderPy `build_sounding` function
spy.build_sounding(clean_data)

Ingesting GRAW, iMet, and Windsond Radiosonde Files

SounderPy can read the files saved by three common research radiosonde systems. These readers are based on conversion scripts contributed by Alec Sczepanski (University of North Dakota). Each returns the same clean_data dict as from_sharppy, keeps only the balloon’s ascent (from launch to burst), and fills in whatever site meta-data the file holds.

spy.from_graw(filepath, date=None)

Return a dict of ‘cleaned up’ profile data from a GRAW radiosonde file

Parameters:
  • filepath (str, required) – filepath to the tab-separated table saved by GRAW’s software

  • date (str or datetime.date, optional) – the launch date, as 'YYYY-MM-DD', 'YYYYMMDD', or a datetime.date, used as is. GRAW files hold the time of day but not the date; without date, it is read from a file name that starts with YYYYMMDD (e.g. 20260125_2100.txt). That date may be the nominal (synoptic) one, so when the name also has a time (HHMM) and the launch is more than 12 hours from it, the launch is moved a day, with a warning: a 23:30 launch in 20260126_0000.txt is on 2026-01-25

Returns:

clean_data, a dict of ready-to-use vertical profile data including pressure, height, temperature, dewpoint, u-wind, v-wind

Return type:

dict

spy.from_imet(filepath)

Return a dict of ‘cleaned up’ profile data from an iMet radiosonde file (InterMet’s SkySonde software)

Parameters:

filepath (str, required) – filepath to the SkySonde flight data .csv

Returns:

clean_data, a dict of ready-to-use vertical profile data including pressure, height, temperature, dewpoint, u-wind, v-wind

Return type:

dict

spy.from_windsond(filepath, elevation)

Return a dict of ‘cleaned up’ profile data from a Windsond radiosonde file

Parameters:
  • filepath (str, required) – filepath to the Windsond .sounding.csv

  • elevation (int or float, required) – the launch site’s elevation (m above sea level). Windsond files hold heights above ground level only, so the elevation is required to put them above sea level like other SounderPy data

Returns:

clean_data, a dict of ready-to-use vertical profile data including pressure, height, temperature, dewpoint, u-wind, v-wind

Return type:

dict

Besides the usual site_info keys, these readers add:

Key

Value

launch-time

The launch as an ISO 8601 UTC string, e.g. '2026-01-25T20:26:35Z', or None when the file has no launch time. valid-time still holds [year, month, day, hour] of the launch.

data-gaps

[[p_bottom, p_top], ...] (hPa) for each telemetry dropout: consecutive levels more than 25 hPa or 500 m apart, which the plot draws as a straight line. [] when there are none.

missing-sfc-wind

True when the lowest level has no wind (e.g. an iMet sonde’s GPS still locking on after launch). The winter mode then uses the lowest wind within 30 m of the surface for the 10 m wind and wind chill.

Note

  • Rows are kept from launch to burst: iMet rows before launch (ascent rate under 1 m/s) and after the burst are dropped, and so is any level missing a pressure, height, or temperature, or whose pressure doesn’t fall below the levels under it. A file saved mid-flight ends at the last level received.

  • GRAW’s first row is the ground station’s surface observation. iMet and Windsond dewpoints are calculated from temperature and relative humidity.

  • Missing winds and humidities (e.g. iMet winds before the GPS locks on) are kept as NaN.

  • Files with a UTF-8 byte order mark (as Excel saves them) and either Windows or Unix line endings are read the same way.

  • A file that isn’t in the reader’s format, or whose profile is too short to plot after cleanup (fewer than 10 levels, or less than 100 hPa deep), raises a ValueError.

  • Data gaps and a missing surface wind come as a SounderPyWarning. The reminder of the site meta-data still needed is a SounderPyNotice, which a server can silence on its own: warnings.filterwarnings('ignore', category=SounderPyNotice) (from sounderpy.utils import SounderPyNotice).

  • As with SHARPpy files, add the site meta-data the file doesn’t hold and plot titles before plotting.

import sounderpy as spy

# open your data (the date comes from the file name)
clean_data = spy.from_graw("Downloads/20260125_2100.txt")

# add the site meta-data the file doesn't have, and plot titles
clean_data['site_info'].update({'site-id': 'UND',
                                'site-name': 'UND GRAND FORKS',
                                'site-lctn': 'ND'})

clean_data['titles'] = {'top_title': 'GRAW RADIOSONDE OBSERVED VERTICAL PROFILE',
                        'left_title': 'LAUNCH: 01/25/2026 20:26Z',
                        'right_title': 'UND - UND GRAND FORKS, ND | 47.92, -97.09    '}

spy.build_sounding(clean_data, mode='winter')

Creating Custom clean_data

Given SounderPy’s data structure (See clean_data schema), it’s possible to ingest any data so long as its in the correct format. You can just manually create the entire “clean_data dictionary”. Your data could be field campaign observations, custom model output, university soundings, and anything else in between. So long as you set it up right, it can be integrated into SounderPy. When constructing a profile manually, the safest approach is to begin with the six required atmospheric variables and site_info.

At minimum:

clean_data = {
    "p": ...,
    "z": ...,
    "T": ...,
    "Td": ...,
    "u": ...,
    "v": ...,
    "site_info": {...},
}

Before passing custom data into SounderPy, verify that:

  • all six profile arrays are one-dimensional;

  • all six arrays have equal length;

  • all six arrays contain physical units;

  • pressure is physically valid;

  • the profile is ordered upward;

  • site_info is a dictionary.

Here is a full example. Here, raw_data represents a data object with your data. Using raw_data[2] is simply referencing some “column of data”, in whatever format raw_data is. I.e., if the 2nd index in raw_data holds pressure values, raw_data[2] goes into clean_data['p'].

# declare the clean_data dictionary, leave it empty for the moment
clean_data = {}

# add profile data | make sure you have p, z, T, Td, u, & v
# use metpy.units to add units to each array -- make sure they are in the same
# units as show below!
clean_data['p']  = np.array(raw_data[2])*units.hPa
clean_data['z']  = np.array(raw_data[7])*units.m
clean_data['T']  = np.array(raw_data[3])*units.degC
clean_data['Td'] = np.array(raw_data[11])*units.degC
clean_data['u']  = np.array(raw_data[5])*units.kts
clean_data['v']  = np.array(raw_data[6])*units.kts

# declare some profile metadata
clean_data['site_info'] = {
            'site-id'     : 'UND',                              # could be a station ID, site ID, launch ID, mission ID, etc
            'site-name'   : 'GRAND FORKS'                       # a location's "name", usually the city or town
            'site-lctn'   : 'ND',                               # could be another name, or the state
            'site-latlon' : [47.9213, -97.087]                  # location lat/lon, list of floats
            'site-elv'    : 257,                                # the profile's elevation in meters (int or float) (easily found on google)
            'source'      : 'UND AEROSPACE'                     # the 'source' which will be the main title component of the plot
            'model'       : 'none',                             # model name if a model was involved
            'fcst-hour'   : f'none',                            # forecast hour if a model was involved
            'run-time'    : ['none', 'none', 'none', 'none'],   # model run date if a model was involved
            'valid-time'  : ["2024", "09", "28", "16:15"]}      # the profile's valid date/time.

# declare the plot titles
clean_data['titles'] = {
            'top_title': 'UNIVERSITY OF NORTH DAKOTA AEROSPACE | OBSERVED SOUNDING',
            'left_title': 'VALID: 09/28/2024 - 16:15Z',
            'right_title': 'GRAND FORKS, ND [47.9213, -97.087]    '}

Done! Now your custom data source is integrated into a SounderPy clean_data dictionary.

Finally, you can pass it into the build_sounding() to visualize your data.

spy.build_sounding(clean_data *kwargs)