wxdata 0.1.1__py3-none-any.whl

wxdata/__init__.py

@@ -0,0 +1,137 @@
+"""
+This file hosts all of the functions in the WxData Python library that directly interact with the user. 
+
+(C) Eric J. Drewitz 2025
+"""
+
+
+"""
+This section of functions are for users who want full wxdata functionality.
+
+These functions do the following:
+
+1) Scan for the latest available data. 
+    - If the data on your local machine is not up to date, new data will download automatically.
+    - If the data on your local machine is up to date, new data download is bypassed.
+    - This is a safeguard that prevents excessive requests on the data servers.
+    
+2) Builds the wxdata directory to store the weather data files. 
+    - Scans for the directory branch and builds the branch if it does not exist. 
+
+3) Downloads the data.
+    - Users can define their VPN/PROXY IP Address as a (dict) in their script and pass their
+      VPN/PROXY IP address into the function to avoid SSL Certificate errors when requesting data.
+    - Algorithm allows for up to 5 retries with a 30 second break between each retry to resolve connection
+      interruptions while not overburdening the data servers. 
+
+4) Pre-processes the data via filename formatting and correctly filing in the wxdata directory. 
+
+5) Post-processing by doing the following tasks:
+     - Remapping GRIB2 variable keys into plain language variable keys.
+     - Fixing dataset build errors and grouping all variables together.
+     - Transforms longitude from 0 to 360 degrees into -180 to 180 degrees.
+     - Subsetting the data to the latitude/longitude boundaries specified by the user. 
+     - Converting temperature from kelvin to units the user wants (default is Celsius).
+     - Returning a post-processed xarray.array to the user. 
+     
+6) Preserves system memory by doing the following:
+     - Deleting old data files before each new download.
+     - When clear_recycle_bin=True, the user's recycle bin is also cleared. 
+"""
+
+# Global Forecast System (GFS)
+from wxdata.gfs.gfs import(
+    gfs_0p25,
+    gfs_0p25_secondary_parameters,
+    gfs_0p50
+)
+
+
+# Global Ensemble Forecast System (GEFS)
+from wxdata.gefs.gefs import(
+    
+    gefs_0p50,
+    gefs_0p50_secondary_parameters,
+    gefs_0p25
+)
+
+# European Centre for Medium-Range Weather Forecasts (ECMWF)
+from wxdata.ecmwf.ecmwf import(
+    ecmwf_ifs,
+    ecmwf_aifs,
+    ecmwf_ifs_high_res,
+    ecmwf_ifs_wave
+)
+
+# FEMS RAWS Network
+from wxdata.fems.fems import(
+    get_single_station_data,
+    get_raws_sig_data,
+    get_nfdrs_forecast_data
+)
+
+# Real-Time Mesoscale Analysis (RTMA)
+from wxdata.rtma.rtma import(
+    rtma, 
+    rtma_comparison
+)
+
+# NOAA 
+# Storm Prediction Center Outlooks
+# National Weather Service Forecasts
+from wxdata.noaa.nws import get_ndfd_grids
+
+# Observed Upper-Air Soundings
+# (University of Wyoming Database)
+from wxdata.soundings.wyoming_soundings import get_observed_sounding_data
+
+# METAR Observational Data (From NOAA)
+from wxdata.metars.metar_obs import download_metar_data
+
+
+"""
+This section hosts the utility functions accessable to the user. 
+
+These functions provide helpful utilities when analyzing weather data. 
+
+Utility functions are geared towards the following types of users:
+
+1) Users who want to use their own scripts to download the data however, they
+   would like to use the wxdata post-processing capabilities. 
+   
+2) Users who want to make hemispheric graphics or any graphics where cyclic points
+   resolve missing data along the prime meridian or international dateline. 
+"""
+# Global Forecast System (GFS)
+import wxdata.utils.gfs_post_processing as gfs_post_processing
+
+# Global Ensemble Forecast System (GEFS)
+import wxdata.utils.gefs_post_processing as gefs_post_processing
+
+# European Centre for Medium-Range Weather Forecasts (ECMWF)
+import wxdata.utils.ecmwf_post_processing as ecmwf_post_processing
+
+# Real-Time Mesoscale Analysis (RTMA)
+from wxdata.utils.rtma_post_processing import process_rtma_data
+
+
+# WxData function using cartopy to make cyclic points
+# This is for users who wish to make graphics that cross the -180/180 degree longitude line
+# This is commonly used for Hemispheric graphics
+# Function that converts the longitude dimension in an xarray.array 
+# From 0 to 360 to -180 to 180
+from wxdata.utils.coords import(
+    cyclic_point,
+    shift_longitude
+)
+
+# Functions to pixel query and query pixels along a line between points A and B
+from wxdata.utils.tools import(
+    pixel_query,
+    line_query
+)
+
+# This is the wxdata HTTPS Client with full VPN/PROXY Support
+import wxdata.client.client as client
+
+

wxdata/calc/__init__.py

@@ -0,0 +1,3 @@
+from wxdata.calc.kinematics import *
+from wxdata.calc.thermodynamics import *
+from wxdata.calc.unit_conversion import *

wxdata/calc/derived_fields.py

@@ -0,0 +1,44 @@
+"""
+This file hosts the functions that will calculate derived model fields.
+
+These calculations will occur after the post-processing. 
+
+(C) Eric J. Drewitz
+"""
+
+import xarray as xr
+import metpy.calc as mpcalc
+
+from metpy.units import units
+
+
+def rtma_derived_fields(ds,
+                        convert_temperature,
+                        convert_to):
+    
+    try:
+        if convert_temperature == True:
+            if convert_to == 'celsius':
+                unit = 'degC'
+            else:
+                unit = 'degF'
+        else:
+            unit = 'kelvin'
+    except Exception as e:
+        pass
+    
+    try:
+        ds['2m_apparent_temperature'] = mpcalc.apparent_temperature(ds['2m_temperature'] * units(unit), ds['2m_relative_humidity'], ds['10m_wind_speed'] * units('m/s'))
+    except Exception as e:
+        pass
+    
+    
+    ds = ds.metpy.dequantify()
+    
+    try:
+        ds['2m_dew_point_depression'] = ds['2m_temperature'] - ds['2m_dew_point']
+    except Exception as e:
+        pass
+        
+    return ds
+

wxdata/calc/kinematics.py

@@ -0,0 +1,29 @@
+"""
+This file hosts functions that perform calculations using kinematics equations
+
+(C) Eric J. Drewitz 2025
+"""
+import numpy as np
+
+def get_u_and_v(wind_speed, 
+                wind_dir):
+
+    """
+    This function calculates the u and u wind components
+
+    Required Arguments:
+
+    1) wind_speed (Float or Integer) 
+
+    2) wind_direction (Float or Integer)
+
+    Returns
+    -------
+
+    u and v wind components
+    """
+
+    u = wind_speed * np.cos(wind_dir)
+    v = wind_speed * np.sin(wind_dir)
+
+    return u, v

wxdata/calc/thermodynamics.py

@@ -0,0 +1,49 @@
+"""
+This file hosts functions that perform calculations using thermodynamics equations
+
+(C) Eric J. Drewitz 2025
+"""
+
+import numpy as np
+
+def saturation_vapor_pressure(temperature):
+
+    """
+    This function calculates the saturation vapor pressure from temperature.
+    This function uses the formula from Bolton 1980.   
+
+    Required Arguments:
+
+    1) temperature (Float or Integer)
+
+    Returns
+    -------
+
+    The saturation vapor pressure
+    """
+
+    e = 6.112 * np.exp(17.67 * (temperature) / (temperature + 243.5))
+    return e
+
+
+def relative_humidity(temperature, 
+                      dewpoint):
+
+    """
+    This function calculates the relative humidity from temperature and dewpoint. 
+
+    Required Arguments:
+
+    1) temperature (Float or Integer)
+
+    2) dewpoint (Float or Integer)
+
+    Returns
+    -------
+
+    The relative humidity
+    """
+
+    e = saturation_vapor_pressure(dewpoint)
+    e_s = saturation_vapor_pressure(temperature)
+    return (e / e_s) * 100

wxdata/calc/unit_conversion.py

@@ -0,0 +1,63 @@
+"""
+This file hosts the functions that convert units
+
+(C) Eric J. Drewitz
+"""
+
+def convert_temperature_units(ds, 
+                              convert_to,
+                              cat='mean'):
+    
+    """
+    This function converts temperature variables from Kelvin to Fahrenheit
+    
+    Required Arguments: 
+    
+    1) ds (xarray.array) - The xarray data array 
+    
+    2) convert_to (String) - Convert to Celsius or Fahrenheit
+    
+    Optional Arguments: None
+    
+    Returns
+    -------
+    
+    Temperature variables in Fahrenheit or Celsius  
+    """
+    convert_to = convert_to.lower()
+    cat = cat.lower()
+    
+    params = list(ds.data_vars.keys())
+    
+    keyword1 = 'temperature'
+    keyword2 = 'dew_point'
+    keyword3 = 'dew_point_depression'
+    for param in params:
+        if keyword1 in param:
+            if convert_to == 'celsius':
+                if cat != 'spread':
+                    ds[param] = ds[param] - 273.15
+                else:
+                    ds[param] = ds[param]
+            else:
+                if cat != 'spread':
+                    frac = 9/5
+                    ds[param] = ds[param] - 273.15
+                    ds[param] = (ds[param] * frac) + 32
+                else:
+                    ds[param] = ds[param] * 1.8
+        if keyword2 in param:
+            if convert_to == 'celsius':
+                if cat != 'spread':
+                    ds[param] = ds[param] - 273.15
+                else:
+                    ds[param] = ds[param]
+            else:
+                if cat != 'spread':
+                    frac = 9/5
+                    ds[param] = ds[param] - 273.15
+                    ds[param] = (ds[param] * frac) + 32
+                else:
+                    ds[param] = ds[param] * 1.8              
+            
+    return ds

wxdata/client/__init__.py

@@ -0,0 +1 @@
+import wxdata.client.client

wxdata/client/client.py

@@ -0,0 +1,251 @@
+import requests
+import time
+import sys
+import os
+import pandas as pd
+
+from io import BytesIO
+from wxdata.utils.recycle_bin import *
+
+def get_gridded_data(url,
+             path,
+             filename,
+             proxies=None,
+             chunk_size=8192,
+             notifications='on',
+             clear_recycle_bin=True):
+    
+    """
+    This function is the client that retrieves gridded weather/climate data (GRIB2 and NETCDF) files. 
+    This client supports VPN/PROXY connections. 
+    
+    Required Arguments:
+    
+    1) url (String) - The download URL to the file. 
+    
+    2) path (String) - The directory where the file is saved to. 
+    
+    3) filename (String) - The name the user wishes to save the file as. 
+    
+    Optional Arguments:
+    
+    1) proxies (dict or None) - Default=None. If the user is using proxy server(s), the user must change the following:
+
+       proxies=None ---> proxies={
+                           'http':'http://url',
+                           'https':'https://url'
+                        } 
+                        
+    2) chunk_size (Integer) - Default=8192. The size of the chunks when writing the GRIB/NETCDF data to a file.
+    
+    3) notifications (String) - Default='on'. Notification when a file is downloaded and saved to {path}
+    
+    4) clear_recycle_bin (Boolean) - Default=True. When set to True, the contents in your recycle/trash bin will be deleted with each run
+        of the program you are calling WxData. This setting is to help preserve memory on the machine. 
+    
+    Returns
+    -------
+    
+    Gridded weather/climate data files (GRIB2 or NETCDF) saved to {path}    
+    """
+    
+    if clear_recycle_bin == True:
+        clear_recycle_bin_windows()
+        clear_trash_bin_mac()
+        clear_trash_bin_linux()
+    else:
+        pass
+    
+    try:
+        os.makedirs(f"{path}")
+    except Exception as e:
+        pass
+
+    if proxies == None:
+        try:
+            with requests.get(url, stream=True) as r:
+                r.raise_for_status() 
+                with open(f"{path}/{filename}", 'wb') as f:
+                    for chunk in r.iter_content(chunk_size=chunk_size):
+                        f.write(chunk)
+            if notifications == 'on':
+                print(f"Successfully saved {filename} to f:{path}")
+            else:
+                pass
+        except requests.exceptions.RequestException as e:
+            for i in range(0, 6, 1):
+                if i < 3:
+                    print(f"Alert: Network connection unstable.\nWaiting 30 seconds then automatically trying again.\nAttempts remaining: {5 - i}")
+                    time.sleep(30)
+                else:
+                    print(f"Alert: Network connection unstable.\nWaiting 60 seconds then automatically trying again.\nAttempts remaining: {5 - i}")
+                    time.sleep(60)  
+                    
+                try:
+                    with requests.get(url, stream=True) as r:
+                        r.raise_for_status() 
+                        with open(f"{path}/{filename}", 'wb') as f:
+                            for chunk in r.iter_content(chunk_size=chunk_size):
+                                f.write(chunk)
+                    if notifications == 'on':
+                        print(f"Successfully saved {filename} to f:{path}")  
+                    break
+                except requests.exceptions.RequestException as e:
+                    i = i 
+                    if i >= 5:
+                        print(f"Error - File Cannot Be Downloaded.\nError Code: {e}")    
+                        sys.exit(1)           
+            
+    else:
+        try:
+            with requests.get(url, stream=True, proxies=proxies) as r:
+                r.raise_for_status() 
+                with open(f"{path}/{filename}", 'wb') as f:
+                    for chunk in r.iter_content(chunk_size=chunk_size):
+                        f.write(chunk)
+            if notifications == 'on':
+                print(f"Successfully saved {filename} to f:{path}")
+            else:
+                pass
+        except requests.exceptions.RequestException as e:
+            for i in range(0, 6, 1):
+                if i < 3:
+                    print(f"Alert: Network connection unstable.\nWaiting 30 seconds then automatically trying again.\nAttempts remaining: {5 - i}")
+                    time.sleep(30)
+                else:
+                    print(f"Alert: Network connection unstable.\nWaiting 60 seconds then automatically trying again.\nAttempts remaining: {5 - i}")
+                    time.sleep(60)  
+                    
+                try:
+                    with requests.get(url, stream=True, proxies=proxies) as r:
+                        r.raise_for_status() 
+                        with open(f"{path}/{filename}", 'wb') as f:
+                            for chunk in r.iter_content(chunk_size=chunk_size):
+                                f.write(chunk)
+                    if notifications == 'on':
+                        print(f"Successfully saved {filename} to f:{path}")  
+                    break
+                except requests.exceptions.RequestException as e:
+                    i = i 
+                    if i >= 5:
+                        print(f"Error - File Cannot Be Downloaded.\nError Code: {e}")    
+                        sys.exit(1)    
+                        
+                        
+def get_csv_data(url,
+                 path,
+                 filename,
+                 proxies=None,
+                 notifications='on',
+                 return_pandas_df=True,
+                 clear_recycle_bin=True):
+    
+    """
+    This function is the client that retrieves CSV files from the web.
+    This client supports VPN/PROXY connections. 
+    User also has the ability to read the CSV file and return a Pandas.DataFrame()
+    
+    Required Arguments:
+    
+    1) url (String) - The download URL to the file. 
+    
+    2) path (String) - The directory where the file is saved to. 
+    
+    3) filename (String) - The name the user wishes to save the file as. 
+    
+    Optional Arguments:
+    
+    1) proxies (dict or None) - Default=None. If the user is using proxy server(s), the user must change the following:
+
+       proxies=None ---> proxies={
+                           'http':'http://url',
+                           'https':'https://url'
+                        } 
+    
+    2) notifications (String) - Default='on'. Notification when a file is downloaded and saved to {path}
+    
+    3) return_pandas_df (Boolean) - Default=True. When set to True, a Pandas.DataFrame() of the data inside the CSV file will be returned to the user. 
+    
+    4) clear_recycle_bin (Boolean) - Default=True. When set to True, the contents in your recycle/trash bin will be deleted with each run
+        of the program you are calling WxData. This setting is to help preserve memory on the machine. 
+    
+    
+    Returns
+    -------
+    
+    A CSV file saved to {path}
+    
+    if return_pandas_df=True - A Pandas.DataFrame()
+    """
+    
+    if clear_recycle_bin == True:
+        clear_recycle_bin_windows()
+        clear_trash_bin_mac()
+        clear_trash_bin_linux()
+    else:
+        pass
+    
+    try:
+        os.makedirs(f"{path}")
+    except Exception as e:
+        pass
+    
+    if proxies==None:
+        try:
+            response = requests.get(url, stream=True)
+        except Exception as e:
+            for i in range(0, 6, 1):
+                if i < 3:
+                    print(f"Alert: Network connection unstable.\nWaiting 30 seconds then automatically trying again.\nAttempts remaining: {5 - i}")
+                    time.sleep(30)
+                else:
+                    print(f"Alert: Network connection unstable.\nWaiting 60 seconds then automatically trying again.\nAttempts remaining: {5 - i}")
+                    time.sleep(60)  
+                    
+                try:
+                    response = requests.get(url, stream=True)
+                    break
+                except Exception as e:
+                    i = i                    
+                    if i >= 5:
+                        print(f"Error - File Cannot Be Downloaded.\nError Code: {e}")    
+                        sys.exit(1)    
+                        
+    else:
+        try:
+            response = requests.get(url, stream=True, proxies=proxies)
+        except Exception as e:
+            for i in range(0, 6, 1):
+                if i < 3:
+                    print(f"Alert: Network connection unstable.\nWaiting 30 seconds then automatically trying again.\nAttempts remaining: {5 - i}")
+                    time.sleep(30)
+                else:
+                    print(f"Alert: Network connection unstable.\nWaiting 60 seconds then automatically trying again.\nAttempts remaining: {5 - i}")
+                    time.sleep(60)  
+                    
+                try:
+                    response = requests.get(url, stream=True, proxies=proxies)
+                    break
+                except Exception as e:
+                    i = i                    
+                    if i >= 5:
+                        print(f"Error - File Cannot Be Downloaded.\nError Code: {e}")    
+                        sys.exit(1) 
+                
+                        
+    data_stream = BytesIO(response.content)
+    
+    df = pd.read_csv(data_stream)
+    
+    df.to_csv(f"{path}/{filename}", index=False)
+    if notifications == True:
+        print(f"{filename} saved to {path}")
+    else:
+        pass
+    
+    if return_pandas_df == True:
+    
+        return df
+    
+    else:
+        pass

wxdata/ecmwf/__init__.py

@@ -0,0 +1,7 @@
+from wxdata.ecmwf.ecmwf import(
+    ecmwf_ifs,
+    ecmwf_aifs,
+    ecmwf_ifs_high_res,
+    ecmwf_ifs_wave
+)
+