SounderPy

https://kylejgillett.github.io/sounderpy
Admin
SounderPy is an open-source Python package for retrieving and visualizing vertical profile...
Tokens:60,781
Snippets:380
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Test SounderPy Installation

Source: https://kylejgillett.github.io/sounderpy/_sources/troubleshooting.rst.txt

This Python code snippet verifies a correct SounderPy installation by fetching and plotting observational data. It requires the sounderpy library and demonstrates basic data retrieval and visualization functions.

```python
import sounderpy as spy

data = spy.get_obs_data("kabr", "2024", "08", "29", "00")

spy.build_sounding(data, color_blind=True, radar='single')
```

--------------------------------

### Example SounderPy Clean Data Dictionary

Source: https://kylejgillett.github.io/sounderpy/custom_data_example.html

This is a concrete example of the 'clean_data' dictionary structure used by SounderPy. It demonstrates the format for pressure, height, and temperature arrays, showcasing the expected data types and units.

```python
{
    'p': array([944. , 926.4, 925. , 894.5, 863.5, 850. , 848. , 833.4, 804.1,
            795. , 775.7, 774. , 748. , 721.2, 720. , 700. , 685. , 674. ,
            670. , 651. , 645.1, 630. , 621.3, 621. , 598.2, 591. , 587. ,
            583. , 572. , 554. , 509. , 500. , 473.6, 471. , 446. , 442. ,
            425. , 418. , 402. , 400. , 399. , 395. , 386. , 382. , 370. ,
            354.7, 354. , 336. , 311.2, 300. , 297. , 279. , 250. , 241. ,
            239. , 237.6, 232. , 200. , 194. , 190. , 188. , 170. , 168.9,
            165. , 162. , 161. , 160.6, 155. , 152.8, 150. , 138.2, 135. ,
            131.3, 131. , 130. , 127. , 125. , 124.8, 122. , 118.7, 118. ,
            113. , 112. , 111. , 108. , 103. , 102. , 101. , 100. ]) <Unit('hectopascal')>,
    'z': array([  446,   610,   623,   914,  1219,  1356,  1376,  1524,  1829,
            1926,  2134,  2152,  2438,  2743,  2757,  2990,  3168,  3300,
            3349,  3584,  3658,  3850,  3962,  3966,  4267,  4364,  4419,
            4473,  4625,  4877,  5542,  5680,  6096,  6137,  6550,  6617,
            6911,  7035,  7323,  7360,  7378,  7452,  7620,  7696,  7925,
            8230,  8243,  8612,  9144,  9400,  9470,  9900, 10640, 10880,
           10935, 10973, 11128, 12070, 12260, 12389, 12454, 13067, 13106,
           13246, 13356, 13394, 13411, 13628, 13716, 13830, 14326, 14466,
           14630, 14645, 14690, 14831, 14927, 14935, 15075, 15240, 15278,
           15544, 15599, 15655, 15826, 16123, 16184, 16247, 16310]) <Unit('meter')>,
    'T': array([ 26. ,  24.3,  24.2,  21.7,  19.2,  18. ,  17.4,  16.4,  14.3,
            13.6,  13.4,  13.4,  10.9,   8.3,   8.2,   6.4,   5.2,   5.8,
             6. ,   4.2,   3.6,   2. ,   2.4,   2.4,   0.2,  -0.5,  -0.7,
            -0.5,  -0.9,  -3.1,  -9.1, -10.3, -14.1, -14.5, -16.9, -16.7,
           -19.1, -19.7, -22.3, -22.5, -22.5, -22.5, -23.9, -24.5, -26.7,
           -29.6, -29.7, -32.7, -36.1, -37.7, -37.9, -41.1, -47.1, -49.3,
           -49.5, -49.8, -51.1, -59.3, -61.3, -62.3, -62.9, -68.1, -68.3,
           -68.9, -68.3, -63.9, -63.8, -62.1, -62.8, -63.7, -68.5, -69.9,
           -70.3, -70.3, -68.1, -66.5, -65.3, -65.3, -65.3, -63.8, -63.5])
}
```

--------------------------------

### Example Clean Data Dictionary Structure

Source: https://kylejgillett.github.io/sounderpy/_sources/gettingdata.rst.txt

This example illustrates the structure of the 'clean_data' dictionary returned by SounderPy's data retrieval functions. The dictionary contains arrays for various atmospheric parameters like pressure, height, temperature, and dewpoint, along with a nested dictionary for site-specific metadata.

```python
{
    'p': <Quantity([984.7 981.8 976.4 967.1 953.4 935.8 914.8 892.  867.2 839.6 809.2 775.8
      739.6 700.4 658.4 613.4 566.1 520.1 478.7 441.6 408.1 377.8 350.5 325.8
      303.6 283.6 265.5 248.7 233.5 219.6 205.7 191.7 177.7 163.8 149.8 135.9
      121.9 108.   94.   81.   70.6  62.2  54.3], 'hectopascal')>,
    'z': <Quantity([  262.29   287.38   334.72   417.39   540.9    701.94   897.92  1116.39
      1360.38  1638.85  1954.13  2311.53  2712.99  3165.6   3673.36  4247.56
      4889.99  5558.47  6202.    6817.56  7410.43  7981.44  8527.44  9050.51
      9548.   10021.78 10474.5  10917.67 11339.77 11745.44 12172.28 12626.51
     13109.32 13623.36 14184.85 14794.86 15466.97 16205.52 17052.44 17961.73
     18802.02 19579.02 20415.56], 'meter')>,
    'T': <Quantity([ 14.84  17.54  20.04  21.34  21.44  20.44  21.44  22.74  21.64  19.94
      17.54  14.84  11.94   8.64   5.24   1.84  -1.86  -6.06 -10.56 -14.66
     -18.36 -22.36 -26.66 -30.66 -34.06 -37.26 -40.06 -43.06 -45.96 -48.76
     -51.56 -54.46 -56.86 -58.26 -58.66 -59.66 -64.26 -65.26 -64.26 -64.66
     -63.86 -63.36 -62.16], 'degree_Celsius')>,
    'Td': <Quantity([   9.3     8.79    8.32    7.88    7.01    6.38   -2.2   -13.24  -14.49
      -24.86  -17.51   -9.57   -7.31   -9.9   -12.11  -12.99  -16.41  -20.62
      -25.37  -30.93  -36.12  -40.09  -42.47  -45.57  -49.39  -52.06  -54.3
      -55.81  -58.64  -62.27  -64.93  -74.24  -74.84 -101.09
     -101.6  -102.16 -102.8  -103.49 -104.11 -104.68 -105.28], 'degree_Celsius')>,
    'u': <Quantity([-2.33041109 -2.91567705 -2.3323691   0.77626972  3.5007069   5.63835178
       9.13497097 10.6914363  13.41432206 20.79403892 23.12721208 21.57710061
      20.41478107 21.38502534 22.54815854 23.51844683 24.29878342 23.71105505
      20.98924152 22.35724617 28.57257978 28.18931303 25.65927737 28.56994968
      28.57863291 29.73848546 31.87877692 31.48766321 29.74415098 27.98817845
      27.59730449 26.43360693 23.32832754 21.76679295 23.12850533 25.85409643
      33.62524652 19.4383033   8.94253878  9.13760323  6.0283743   6.02452813
       0.38886559], 'knot')>
}
```

--------------------------------

### Install SounderPy using Mamba

Source: https://kylejgillett.github.io/sounderpy/_sources/about.rst.txt

This command installs SounderPy using Mamba, a faster alternative to Conda for package management. It assumes Mamba is installed and configured.

```console
mamba install sounderpy
```

--------------------------------

### Install SounderPy using pip

Source: https://kylejgillett.github.io/sounderpy/about.html

Installs the SounderPy package using pip, the standard package installer for Python. This is the most common method for installing Python packages.

```bash
pip install sounderpy
```

--------------------------------

### Install SounderPy using Conda Forge

Source: https://kylejgillett.github.io/sounderpy/_sources/about.rst.txt

These commands install SounderPy using the conda-forge channel. It first configures conda to use conda-forge and then installs the package. This method is recommended for users who prefer the conda package management system.

```console
conda config --add channels conda-forge
conda config --set channel_priority strict
conda install sounderpy
```

--------------------------------

### Example Data Structure in SounderPy

Source: https://kylejgillett.github.io/sounderpy/_sources/customdatasources.rst.txt

Provides an example of the 'clean_data' dictionary structure, including sample data for pressure, altitude, temperature, dew point, wind components (u, v), and omega. It also includes a nested 'site_info' dictionary with example values.

```python
{
    'p': <Quantity([984.7 981.8 976.4 967.1 953.4 935.8 914.8 892.  867.2 839.6 809.2 775.8
      739.6 700.4 658.4 613.4 566.1 520.1 478.7 441.6 408.1 377.8 350.5 325.8
      303.6 283.6 265.5 248.7 233.5 219.6 205.7 191.7 177.7 163.8 149.8 135.9
      121.9 108.   94.   81.   70.6  62.2  54.3], 'hectopascal')>,
    'z': <Quantity([  262.29   287.38   334.72   417.39   540.9    701.94   897.92  1116.39
      1360.38  1638.85  1954.13  2311.53  2712.99  3165.6   3673.36  4247.56
      4889.99  5558.47  6202.    6817.56  7410.43  7981.44  8527.44  9050.51
      9548.   10021.78 10474.5  10917.67 11339.77 11745.44 12172.28 12626.51
     13109.32 13623.36 14184.85 14794.86 15466.97 16205.52 17052.44 17961.73
     18802.02 19579.02 20415.56], 'meter')>,
    'T': <Quantity([ 14.84  17.54  20.04  21.34  21.44  20.44  21.44  22.74  21.64  19.94
      17.54  14.84  11.94   8.64   5.24   1.84  -1.86  -6.06 -10.56 -14.66
     -18.36 -22.36 -26.66 -30.66 -34.06 -37.26 -40.06 -43.06 -45.96 -48.76
     -51.56 -54.46 -56.86 -58.26 -58.66 -59.66 -64.26 -65.26 -64.26 -64.66
     -63.86 -63.36 -62.16], 'degree_Celsius')>,
    'Td': <Quantity([   9.3     8.79    8.32    7.88    7.01    6.38   -2.2   -13.24  -14.49
      -24.86  -17.51   -9.57   -7.31   -9.9   -12.11  -12.99  -16.41  -20.62
      -25.37  -30.93  -36.12  -40.09  -42.47  -45.57  -49.39  -52.06  -54.3
      -55.81  -58.64  -62.27  -64.93  -74.24  -74.84 -101.09
     -101.6  -102.16 -102.8  -103.49 -104.11 -104.68 -105.28], 'degree_Celsius')>,
    'u': <Quantity([-2.33041109 -2.91567705 -2.3323691   0.77626972  3.5007069   5.63835178
      9.13497097 10.6914363  13.41432206 20.79403892 23.12721208 21.57710061
     20.41478107 21.38502534 22.54815854 23.51844683 24.29878342 23.71105505
     20.98924152 22.35724617 28.57257978 28.18931303 25.65927737 28.56994968
     28.57863291 29.73848546 31.87877692 31.48766321 29.74415098 27.98817845
     27.59730449 26.43360693 23.32832754 21.76679295 23.12850533 25.85409643
     33.62524652 19.4383033   8.94253878  9.13760323  6.0283743   6.02452813
      0.38886559], 'knot')>,
    'v': <Quantity([ 3.88459575  9.13602361 12.24993691 13.79818123 13.99892679 13.41310886
     10.68811982  9.33002089  9.33014275  6.99796725  2.91344493  1.36129697
     -1.35952707 -4.85855855 -5.83135029 -5.44263343 -4.85978647 -4.08282603
     -4.27412453 -5.44184192 -4.46923758 -0.19680173 -0.19257433 -4.0813693
     -2.52543878 -1.75116608 -3.49692463 -2.13557144  0.97112424  2.71960789
      2.13803291  0.5813991   1.55355538  5.2458388   6.21890192 20.41100923
     13.40831073  9.91285856 15.74811418  9.3310132   9.72277241  7.38416961
      6.99920592], 'knot')>,
    'omega': <Quantity([ 0.   0.   0.   0.   0.   0.1  0.1  0.1 -0.1 -0.3 -0.4 -0.2 -0.1  0.
      0.   0.1  0.1  0.   0.   0.   0.   0.   0.   0.1  0.1  0.   0.   0.
     -0.1  0.   0.   0.1  0.1  0.   0.   0.   0.   0.   0.   0.   0.
      0. ], 'pascal / second')>,

    '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']
    }
}
```

--------------------------------

### Install SounderPy using conda

Source: https://kylejgillett.github.io/sounderpy/about.html

Installs the SounderPy package using conda, a package and environment management system. This method requires setting up the conda-forge channel first.

```bash
conda config --add channels conda-forge
conda config --set channel_priority strict
conda install sounderpy
```

```bash
mamba install sounderpy
```

--------------------------------

### Build Sounding with Dark Mode and Color Blind Mode

Source: https://kylejgillett.github.io/sounderpy/sounding_example.html

This example shows how to activate both dark mode and color-blind mode simultaneously. The `build_sounding` function is called with both `dark_mode` and `color_blind` parameters set to `True`. This configuration aims to provide an accessible and visually comfortable sounding plot.

```python
# dark_mode and color_blind turned on!
spy.build_sounding(clean_data, dark_mode=True, color_blind=True)
```

--------------------------------

### Loading Custom Data Source in SounderPy

Source: https://kylejgillett.github.io/sounderpy/custom_data_example.html

This example shows how to specify a custom data source for SounderPy. It declares a file path to a CSV containing field campaign data, which can then be processed by SounderPy for analysis and plotting.

```python
# declare file
file = 'https://raw.githubusercontent.com/kylejgillett/sounderpy/main/test_data/Far_Field_MW41_output_20190520_214246.csv'
```

--------------------------------

### Get Observed Sounding Data (RAOB/IGRA2) with SounderPy

Source: https://kylejgillett.github.io/sounderpy/index.html

Retrieves observed sounding data from RAOB and IGRA2 archives using `spy.get_obs_data()`. Requires specifying available RAOB sites. Returns observational data for the specified site.

```python
import sounderpy as spy

# Example: Get RAOB data for a specific site
# (Replace 'SITE_ID' with an actual RAOB site identifier)
obs_data = spy.get_obs_data(site='SITE_ID', data_type='raob')
print(obs_data)
```

--------------------------------

### Get BUFKIT Model Forecast Data - Python

Source: https://kylejgillett.github.io/sounderpy/_sources/gettingdata.rst.txt

Retrieves BUFKIT model forecast vertical profile data for a specified site, model, and forecast hour. It can optionally clean the data and hush output. Requires model and station identifiers.

```python
import sounderpy as spy

# Example: Get RAP model data for site KGFK at forecast hour 5
# This will fetch the latest available forecast by default.
data = spy.get_bufkit_data('rap', 'kgfk', 5)

# Example: Get HRRR model data for site KDEN at forecast hour 12 for a specific run date
data_specific_run = spy.get_bufkit_data('hrrr', 'kden', 12, run_year='2023', run_month='10', run_day='26', run_hour='00')

# Example: Get GFS model data and keep the raw output
raw_data = spy.get_bufkit_data('gfs', 'kord', 24, clean_it=False)

# Example: Get SREF model data and hush the thermodynamic/kinematic output
quiet_data = spy.get_bufkit_data('sref', 'kchi', 36, hush=True)
```

--------------------------------

### Manually Create SounderPy 'clean_data' Dictionary

Source: https://kylejgillett.github.io/sounderpy/_sources/customdatasources.rst.txt

This example demonstrates how to manually construct the 'clean_data' dictionary required by SounderPy plotting functions. It outlines the necessary keys for profile data (pressure, height, temperature, etc.) and site metadata, allowing integration of any custom sounding data.

```python
# Example structure for a 'clean_data' dictionary
clean_data = {
 'p': [...],
 'z': [...],
 'T': [...],
 'Td': [...],
 'u': [...],
 'v': [...],
 # 'omega': [...] # Optional, for model data only
 'site_info': {
  'site-name': 'Example Site',
  'site-lctn': 'Example Location'
 }
}

# Pass this dictionary to SounderPy plotting functions, e.g.:
# spy.build_sounding(clean_data)
```

--------------------------------

### Get BUFKIT Model Forecast Data with SounderPy

Source: https://kylejgillett.github.io/sounderpy/index.html

Fetches BUFKIT model forecast data using `spy.get_bufkit_data()`. Users need to know the available BUFKIT sites and models. The function returns forecast data for a specified site and model.

```python
import sounderpy as spy

# Example: Get GFS forecast data for a BUFKIT site
# (Replace 'SITE_ID' with an actual BUFKIT site identifier)
forecast_data = spy.get_bufkit_data(site='SITE_ID', model='gfs')
print(forecast_data)
```

--------------------------------

### Retrieve BUFKIT Forecast Data using sounderpy

Source: https://kylejgillett.github.io/sounderpy/bufkit_data_example.html

Demonstrates how to fetch BUFKIT forecast data using the `get_bufkit_data()` function from the sounderpy library. It shows examples for retrieving both archived and the most recent forecasts, highlighting the required parameters for each. Note that BUFKIT data is only available at specific site locations.

```python
################################ THE FUNCTION ###################################
# to get bufkit data, we need to use the `get_bufkit_data()` function
# `get_bufkit_data(model, station, fcst_hr, run_year, run_month, run_day, run_hour)`
################################################################################


########################## TYPES OF BUFKIT DATA ################################
# we can access archived model forecasts from the GFS, NAM, RAP & HRRR
# or most recent run forecasts from the GFS, NAM, NAMNEST, RAP, HRRR, SREF, & HIRESW
################################################################################


########################## WHERE DATA IS AVAILABLE #############################
# NOTE: bufkit forecast data is *only available at specific BUFKIT site locations*
# you can find them here: http://www.meteo.psu.edu/bufkit/DomainNAMRAP_NAM_12.html
################################################################################


############################# LETS GET SOME DATA ###############################
# to get archived forecasts we need every kwarg. (a kwarg is a Keyword Argument, like 'year', and 'station')
# the line below will get us a 12z GFS forecast from 08/05/2023 at forecast hour 6 for bufkit site KMOP:

# clean_data = spy.get_bufkit_data('gfs', 'kmop', 6, '2023', '08', '05', '12')

# to get the most recent forecasts we use the same function, but we *don't need a year, month, day or hour kwarg!*
# you just need a model, station and forecast hour.
# this will get you the most recent HRRR run, at forecast hour 6, for
# site `KAMA` (AMARILLO ARPT(AWOS)):

clean_data = spy.get_bufkit_data('hrrr', 'kama', 6)
```

--------------------------------

### Create and Populate Custom Clean Data Dictionary (Python)

Source: https://kylejgillett.github.io/sounderpy/customdatasources.html

This snippet demonstrates how to initialize an empty dictionary and populate it with sounding data and metadata. It emphasizes the use of 'metpy.units' for correct unit assignment and provides examples for site information and plot titles. Ensure all required profile data (p, z, T, Td, u, v) are included with appropriate units.

```python
# 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]    '}

```

--------------------------------

### Load BUFKIT Forecast Model Data (Python)

Source: https://kylejgillett.github.io/sounderpy/beginners_sounderpy_cookbook.html

Retrieves BUFKIT forecast model data for a specified model, station, and forecast time. Requires valid BUFKIT model names and site identifiers. Outputs a summary of thermodynamic and kinematic data.

```python
bufkit_data = spy.get_bufkit_data('hrrr', 'OUN', 0, '2024', '05', '07', '00')
```

--------------------------------

### Load Observation Data in SounderPy

Source: https://kylejgillett.github.io/sounderpy/beginners_sounderpy_cookbook.html

Demonstrates how to load radiosonde observation data using the `get_obs_data` function in SounderPy. This function requires a station identifier, year, month, day, and hour to retrieve a specific sounding profile. The output includes a summary of the retrieved data and thermodynamic and kinematic parameters.

```python
obs_data = spy.get_obs_data('OUN', '2024', '05', '07', '00')
```

--------------------------------

### Get BUFKIT Model Forecast Data

Source: https://kylejgillett.github.io/sounderpy/gettingdata.html

Retrieves vertical profile data from BUFKIT model forecasts for a specified site, forecast hour, and model run.

```APIDOC
## GET /api/bufkit/data

### Description
Retrieves vertical profile data from BUFKIT model forecasts for a specified site, forecast hour, and model run. The function returns a dictionary containing cleaned-up model forecast data.

### Method
GET

### Endpoint
/api/bufkit/data

### Parameters
#### Query Parameters
- **model** (str) - Required - The model 'key' name to request data from (e.g., 'rap', 'hrrr', 'gfs').
- **station** (str) - Required - A 3-4 digit BUFKIT site identifier.
- **fcst_hour** (int) - Required - The valid forecast hour.
- **run_year** (str) - Optional - The valid year for the model run.
- **run_month** (str) - Optional - The valid month for the model run.
- **run_day** (str) - Optional - The valid day for the model run.
- **run_hour** (str) - Optional - The valid hour for the model run.
- **hush** (bool) - Optional - Defaults to False. If True, suppresses the readout of thermodynamic and kinematic parameters.
- **clean_it** (bool) - Optional - Defaults to True. If True, returns a cleaned data dictionary; otherwise, returns the raw data object.

### Request Example
```python
import sounderpy as spy

# Get the latest RAP model data for site KGFK at forecast hour 5
data = spy.get_bufkit_data('rap', 'kgfk', 5)

# Get specific GFS model data for a past run
data_past = spy.get_bufkit_data('gfs', 'kden', 12, run_year='2023', run_month='10', run_day='26', run_hour='18')
```

### Response
#### Success Response (200)
- **clean_data** (dict) - A dictionary containing ready-to-use vertical profile data including pressure, height, temperature, dewpoint, u-wind, v-wind, omega, and model information.

#### Response Example
```json
{
  "pressure": [1000.0, 995.0, 990.0, ...],
  "height": [0.0, 45.0, 90.0, ...],
  "temperature": [285.5, 284.9, 284.3, ...],
  "dewpoint": [278.2, 277.8, 277.5, ...],
  "u_wind": [-5.2, -5.5, -5.8, ...],
  "v_wind": [3.1, 3.0, 2.9, ...],
  "omega": [0.1, 0.12, 0.13, ...],
  "model_info": {
    "model_name": "RAP",
    "station_id": "KGFK",
    "forecast_hour": 5,
    "run_date": "2023-10-27T12:00:00"
  }
}
```

### Notes
- The data returned is model forecast data and is subject to the limitations of BUFKIT data. 
- Reanalysis data (if applicable) is not a forecast and may not be representative of the actual atmosphere. Understand the caveats of using reanalysis model data.
- Accessing ERA5 data requires setting up an ECMWF Climate Data Store (CDS) account and personal access token.
```

--------------------------------

### Build Sounding Plot with SoundingPy

Source: https://kylejgillett.github.io/sounderpy/custom_data_example.html

Demonstrates how to build a sounding plot using the `build_sounding` function from the SoundingPy library. This function visualizes atmospheric data, with options for dark mode and color-blind accessibility.

```python
# lets make a sounding!
spy.build_sounding(clean_data, dark_mode=True, color_blind=True)
```

--------------------------------

### Build Sounding with Color Blind and Dark Mode

Source: https://kylejgillett.github.io/sounderpy/beginners_sounderpy_cookbook.html

Constructs a sounding plot with options for colorblind users and dark mode enabled. This function takes observation data and applies specific plotting configurations. Dependencies include the SounderPy library and observation data.

```python
spy.build_sounding(obs_data, special_parcels='simple', map_zoom=5, color_blind=True, dark_mode=True)
```

--------------------------------

### Build Basic Sounding Plot

Source: https://kylejgillett.github.io/sounderpy/sounding_example.html

Generates a default sounding plot using the `build_sounding` function with the loaded observational data. This creates a standard meteorological sounding visualization.

```python
# lets make a full sounding!
spy.build_sounding(clean_data)
```

--------------------------------

### Get Model Reanalysis Data with SounderPy

Source: https://kylejgillett.github.io/sounderpy/gettingdata.html

Retrieves model reanalysis profile data from ERA5, RAP/RUC, and NCEP FNL datasets. It parses pressure-level and surface data using a 'box average approach' to create a SounderPy clean_data dictionary. Supports specifying a particular dataset for RAP-RUC data.

```python
import spy

# Example usage for RAP data
model_data = spy.get_model_data(
    _model_="rap-ruc",
    _latlon_=[44.92, -84.72],
    _year_="2023",
    _month_="10",
    _day_="26",
    _hour_="12",
    _dataset_="RAP_25km",
    _box_avg_size_=0.25,
    _clean_it_=True
)

# Example usage for ERA5 data
era5_data = spy.get_model_data(
    _model_="era5",
    _latlon_=[34.05, -118.24],
    _year_="2023",
    _month_="10",
    _day_="26",
    _hour_="00",
    _clean_it_=True
)
```

--------------------------------

### Basic SounderPy Data Retrieval and Plotting

Source: https://kylejgillett.github.io/sounderpy/about.html

Demonstrates a basic usage of SounderPy to retrieve HRRR forecast data for a specific site and time, and then plot the sounding. This showcases the package's core functionality in three lines of code.

```python
import sounderpy as spy
clean_data = spy.get_bufkit_data('hrrr', 'kmli', 8, '2023', '03', '31', '12')
spy.build_sounding(clean_data)
```

--------------------------------

### Get BUFKIT Model Forecast Data (Python)

Source: https://kylejgillett.github.io/sounderpy/gettingdata.html

Retrieves cleaned-up model forecast data from a specified BUFKIT model and site. Requires model name, station identifier, and forecast hour. Optional parameters allow specifying the model run date and controlling data cleaning. Returns a dictionary of vertical profile data.

```python
import spy

# Example: Get RAP model data for site KGFK at forecast hour 5
model_data = spy.get_bufkit_data('rap', 'kgfk', 5)

# Example with specific run date
# model_data = spy.get_bufkit_data('rap', 'kgfk', 5, run_year='2023', run_month='10', run_day='26', run_hour='12')
```

--------------------------------

### Get Latitude/Longitude

Source: https://kylejgillett.github.io/sounderpy/helpertools.html

Retrieves the latitude and longitude pair for a given station type and ID.

```APIDOC
## GET /latlon

### Description
Finds site lat/lon pairs based on station type and ID.

### Method
GET

### Endpoint
/latlon

### Parameters
#### Query Parameters
- **station_type** (str) - Required - The station type (e.g., 'metar', 'bufkit', 'raob', 'buoy').
- **station_id** (str) - Required - The station ID (e.g., 'kmop', 'apx', 'oun', '45210').

### Request Example
```
GET /latlon?station_type=metar&station_id=kmop
```

### Response
#### Success Response (200)
- **latlon** (list) - A list containing the latitude and longitude float pair (e.g., [41.32, -96.37]).

#### Response Example
```json
{
  "latlon": [41.32, -96.37]
}
```

### Notes
This lat/lon pair can be used when calling the `get_model_data` function.
```

--------------------------------

### Create Clean Data Dictionary with Profile and Metadata (Python)

Source: https://kylejgillett.github.io/sounderpy/_sources/customdatasources.rst.txt

This Python code demonstrates how to initialize and populate a 'clean_data' dictionary with sounding profile data and associated metadata. It assumes raw data is available and uses 'metpy.units' for unit handling. The metadata includes site information and plot titles required for visualization.

```python
# 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',
            'site-name'   : 'GRAND FORKS',
            'site-lctn'   : 'ND',
            'site-latlon' : [47.9213, -97.087],
            'site-elv'    : 257,
            'source'      : 'UND AEROSPACE',
            'model'       : 'none',
            'fcst-hour'   : f'none',
            'run-time'    : ['none', 'none', 'none', 'none'],
            'valid-time'  : ["2024", "09", "28", "16:15"]}

# 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]    '}
```

--------------------------------

### Get Reanalysis Data

Source: https://kylejgillett.github.io/sounderpy/beginners_sounderpy_cookbook.html

This function retrieves reanalysis data for a specified model, location, and time. It supports various reanalysis models and allows for specifying date and time components.

```APIDOC
## GET /api/reanalysis_data

### Description
Retrieves reanalysis data for a specified model, location (latitude and longitude), year, month, day, and hour. It supports different reanalysis data models and allows for optional dataset specification and averaging.

### Method
GET

### Endpoint
`/api/reanalysis_data`

### Parameters
#### Query Parameters
- **model** (string) - Required - The name of a valid reanalysis data model (e.g., 'rap'). See: https://kylejgillett.github.io/sounderpy/gettingdata.html#model-key-names
- **latlon** (list of floats) - Required - A list containing latitude and longitude coordinates [latitude, longitude].
- **year** (string) - Required - The year of the desired data (e.g., '2024').
- **month** (string) - Required - The month of the desired data (e.g., '05').
- **day** (string) - Required - The day of the desired data (e.g., '07').
- **hour** (string) - Required - The hour of the desired data (e.g., '00').
- **dataset** (string) - Optional - The specific dataset to use (e.g., 'RAP_25km_anl').
- **box_avg_size** (float) - Optional - Size of the averaging box (default: 0.10).
- **hush** (boolean) - Optional - Suppress output messages (default: False).
- **clean_it** (boolean) - Optional - Clean up the data (default: True).

### Request Example
```python
import sounderpy as spy

reanl_data = spy.get_model_data('rap', [-97.44, 35.22], '2024', '05', '07', '00')
```

### Response
#### Success Response (200)
- **data** (dict) - A dictionary containing the cleaned-up reanalysis data.

#### Response Example
```json
{
  "temperature": [...],
  "dewpoint": [...],
  "wind_u": [...],
  "wind_v": [...],
  "pressure": [...],
  "latitude": [...],
  "longitude": [...],
  "time": "..."
}
```

#### Error Response (404)
- **message** (string) - Indicates that the requested file was not found.

#### Error Response Example
```json
{
  "message": "FileNotFound: No such file or directory"
}
```
```
Tokens:
Raw