More documentation work: ush/enspost_config.py, ush/fire_emiss_tools.py, ush/interp_tools.py

ush/enspost_config.py

@@ -1,6 +1,7 @@
-# HRRR-E PYTHON GRIB GENERATION
-# CONFIGURATION FILE
+"""
+HRRR-E python GRIB generation configuration file
 
+"""
 ## CREATE DICTIONARIES ##
 grib_discipline = {}
 grib_category = {}

ush/fire_emiss_tools.py

@@ -1,16 +1,32 @@
+"""
+Fire emisivity tools?
+"""
 import os
 import numpy as np
 import xarray as xr
 from datetime import datetime
 from netCDF4 import Dataset
 import interp_tools as i_tools
 
-#Compute average FRP from raw RAVE for the previous 24 hours 
 def averaging_FRP(fcst_dates, cols, rows, intp_dir, rave_to_intp, veg_map, tgt_area, beta, fg_to_ug):
-    # There are two situations here.
-    #   1) there is only on fire detection whithin 24 hours so FRP is divided by 2 
-    #   2) There are more than one fire detection so the average FRP is stimated
-    # ebb_smoke is always divided by the number of times a fire is detected within 24 hours window
+    """
+    Compute average FRP from raw RAVE for the previous 24 hours.
+
+    There are two situations here.
+    1) there is only on fire detection whithin 24 hours so FRP is divided by 2 
+    2) There are more than one fire detection so the average FRP is stimated
+    ebb_smoke is always divided by the number of times a fire is detected within 24 hours window
+
+    fcst_dates: ???
+    cols: ???
+    rows: ???
+    intp_dir: ???
+    rave_to_intp: ???
+    veg_map: ???
+    tgt_area: ???
+    beta: ???
+    fg_to_ug: ???
+    """
     base_array = np.zeros((cols*rows))
     frp_daily = base_array
     ebb_smoke_total = []
@@ -67,9 +83,25 @@ def averaging_FRP(fcst_dates, cols, rows, intp_dir, rave_to_intp, veg_map, tgt_a
     return(frp_avg_reshaped, ebb_total_reshaped)
 
 def estimate_fire_duration(intp_avail_hours, intp_dir, fcst_dates, current_day, cols, rows, rave_to_intp):
-    # There are two steps here.
-    #   1) First day simulation no RAVE from previous 24 hours available (fire age is set to zero)
-    #   2) previus files are present (estimate fire age as the difference between the date of the current cycle and the date whe the fire was last observed whiting 24 hours)
+    """
+    There are two steps here.
+
+    1. First day simulation no RAVE from previous 24 hours available
+    (fire age is set to zero)
+
+    2. previus files are present (estimate fire age as the difference
+    between the date of the current cycle and the date whe the fire
+    was last observed whiting 24 hours)
+
+    intp_avail_hours: ???
+    intp_dir: ???
+    fcst_dates: ???
+    current_day: ???
+    cols: ???
+    rows: ???
+    rave_to_intp: ???
+
+    """
     t_fire = np.zeros((cols, rows))
 
     for date_str in fcst_dates:
@@ -103,10 +135,34 @@ def estimate_fire_duration(intp_avail_hours, intp_dir, fcst_dates, current_day,
     return(te)
 
 def save_fire_dur(cols, rows, te):
+    """
+    ???
+
+    cols: ???
+    rows: ???
+    te: ???
+
+    """
     fire_dur = np.array(te).reshape(cols, rows)
     return(fire_dur)
 
 def produce_emiss_file(xarr_hwp, frp_avg_reshaped, totprcp_ave_arr, xarr_totprcp, intp_dir, current_day, tgt_latt, tgt_lont, ebb_tot_reshaped, fire_age, cols, rows):
+    """
+    ???
+
+    xarr_hwp: ???
+    frp_avg_reshaped: ???
+    totprcp_ave_arr: ???
+    xarr_totprcp: ???
+    intp_dir: ???
+    current_day: ???
+    tgt_latt: ???
+    tgt_lont: ???
+    ebb_tot_reshaped: ???
+    fire_age: ???
+    cols: ???
+    rows: ???
+    """
     # Ensure arrays are not negative or NaN
     frp_avg_reshaped = np.clip(frp_avg_reshaped, 0, None)
     frp_avg_reshaped = np.nan_to_num(frp_avg_reshaped)
@@ -159,4 +215,4 @@ def produce_emiss_file(xarr_hwp, frp_avg_reshaped, totprcp_ave_arr, xarr_totprcp
         print(f"Error creating or writing to NetCDF file {file_path}: {e}")
         return f"Error creating or writing to NetCDF file {file_path}: {e}"
 
-    return "Emissions file created successfully"
+    return "Emissions file created successfully"

ush/interp_tools.py

@@ -1,3 +1,7 @@
+"""
+???
+
+"""
 import datetime as dt
 import pandas as pd
 import os
@@ -7,8 +11,13 @@
 import numpy as np
 from netCDF4 import Dataset
 
-#Create date range, this is later used to search for RAVE and HWP from previous 24 hours
 def date_range(current_day):
+    """
+    Create date range, this is later used to search for RAVE and HWP from previous 24 hours.
+
+    current_day: ???
+
+    """
     print(f'Searching for interpolated RAVE for {current_day}')
 
     fcst_datetime = dt.datetime.strptime(current_day, "%Y%m%d%H")
@@ -19,8 +28,15 @@ def date_range(current_day):
     print(f'Current cycle: {fcst_datetime}')
     return(fcst_dates)
 
-# Check if interoplated RAVE is available for the previous 24 hours
 def check_for_intp_rave(intp_dir, fcst_dates, rave_to_intp):
+    """
+    Check if interoplated RAVE is available for the previous 24 hours.
+
+    intp_dir: ???
+    fcst_dates: ???
+    rave_to_intp: ???
+
+    """
     intp_avail_hours = []
     intp_non_avail_hours = []
     # There are four situations here.
@@ -48,8 +64,15 @@ def check_for_intp_rave(intp_dir, fcst_dates, rave_to_intp):
 
     return(intp_avail_hours, intp_non_avail_hours, inp_files_2use)
 
-#Check if raw RAVE in intp_non_avail_hours list is available for interpolatation
 def check_for_raw_rave(RAVE, intp_non_avail_hours, intp_avail_hours):
+    """
+    Check if raw RAVE in intp_non_avail_hours list is available for interpolatation.
+
+    RAVE: ???
+    intp_non_avail_hours: ???
+    intp_avail_hours: ???
+
+    """
     rave_avail = []
     rave_avail_hours = []
     rave_nonavail_hours_test = []
@@ -72,9 +95,16 @@ def check_for_raw_rave(RAVE, intp_non_avail_hours, intp_avail_hours):
     print(f'FIRST DAY?: {first_day}')
     return(rave_avail, rave_avail_hours, rave_nonavail_hours_test, first_day)
 
-#Create source and target fields
 def creates_st_fields(grid_in, grid_out, intp_dir, rave_avail_hours):
+    """
+    Create source and target fields.
 
+    grid_in: ???
+    grid_out: ???
+    intp_dir: ???
+    rave_avail_hours: ???
+
+    """
     # Open datasets with context managers
     with xr.open_dataset(grid_in) as ds_in, xr.open_dataset(grid_out) as ds_out:
         tgt_area = ds_out['area']
@@ -93,15 +123,30 @@ def creates_st_fields(grid_in, grid_out, intp_dir, rave_avail_hours):
 
 #Define output and variable meta data
 def create_emiss_file(fout, cols, rows):
-    """Create necessary dimensions for the emission file."""
+    """Create necessary dimensions for the emission file.
+
+    fout: ???
+    cols: ???
+    rows: ???
+    """
     fout.createDimension('t', None)
     fout.createDimension('lat', cols)
     fout.createDimension('lon', rows)
     setattr(fout, 'PRODUCT_ALGORITHM_VERSION', 'Beta')
     setattr(fout, 'TIME_RANGE', '1 hour')
 
 def Store_latlon_by_Level(fout, varname, var, long_name, units, dim, fval, sfactor):
-    """Store a 2D variable (latitude/longitude) in the file."""
+    """Store a 2D variable (latitude/longitude) in the file.
+
+    fout: ???
+    varname: ???
+    var: ???
+    long_name: ???
+    units: ???
+    dim: ???
+    fval: ???
+    sfactor: ???
+    """
     var_out = fout.createVariable(varname,   'f4', ('lat','lon'))
     var_out.units=units
     var_out.long_name=long_name
@@ -111,16 +156,35 @@ def Store_latlon_by_Level(fout, varname, var, long_name, units, dim, fval, sfact
     var_out.coordinates='geolat geolon'
 
 def Store_by_Level(fout, varname, long_name, units, dim, fval, sfactor):
-    """Store a 3D variable (time, latitude/longitude) in the file."""
+    """Store a 3D variable (time, latitude/longitude) in the file.
+
+    fout: ???
+    varname: ???
+    long_name: ???
+    units: ???
+    dim: ???
+    fval: ???
+    sfactor: ???
+    """
     var_out = fout.createVariable(varname,   'f4', ('t','lat','lon'))
     var_out.units=units
     var_out.long_name = long_name
     var_out.standard_name=long_name
     var_out.FillValue=fval
     var_out.coordinates='t geolat geolon'
 
-#create a dummy rave interpolated file if first day or regrider fails
 def create_dummy(intp_dir, current_day, tgt_latt, tgt_lont, cols, rows):
+    """
+    Create a dummy rave interpolated file if first day or regrider fails.
+
+    intp_dir: ???
+    current_day: ???
+    tgt_latt: ???
+    tgt_lont: ???
+    cols: ???
+    rows: ???
+
+    """
     file_path = os.path.join(intp_dir, f'SMOKE_RRFS_data_{current_day}00.nc')
     dummy_file = np.zeros((cols, rows))  # Changed to 3D to match the '3D' dimensions
     with Dataset(file_path, 'w') as fout:
@@ -143,8 +207,18 @@ def create_dummy(intp_dir, current_day, tgt_latt, tgt_lont, cols, rows):
 
     return "Emissions dummy file created successfully"
 
-#generate regridder
 def generate_regrider(rave_avail_hours, srcfield, tgtfield, weightfile, inp_files_2use, intp_avail_hours):
+    """
+    generate regridder.
+
+    rave_avail_hours: ???
+    srcfield: ???
+    tgtfield: ???
+    weightfile: ???
+    inp_files_2use: ???
+    intp_avail_hours: ???
+
+    """
     print('Checking conditions for generating regridder.')
     use_dummy_emiss = len(rave_avail_hours) == 0 and len(intp_avail_hours) == 0
     regridder = None
@@ -167,9 +241,28 @@ def generate_regrider(rave_avail_hours, srcfield, tgtfield, weightfile, inp_file
 
     return(regridder, use_dummy_emiss)
 
-#process RAVE available for interpolation
 def interpolate_rave(RAVE, rave_avail, rave_avail_hours, use_dummy_emiss, vars_emis, regridder, 
                     srcgrid, tgtgrid, rave_to_intp, intp_dir, src_latt, tgt_latt, tgt_lont, cols, rows):
+    """
+    Process RAVE available for interpolation.
+
+    RAVE: ???
+    rave_avail: ???
+    rave_avail_hours: ???
+    use_dummy_emiss: ???
+    vars_emis: ???
+    regridder: ???
+    srcgrid: ???
+    tgtgrid: ???
+    rave_to_intp: ???
+    intp_dir: ???
+    src_latt: ???
+    tgt_latt: ???
+    tgt_lont: ???
+    cols: ???
+    rows: ???
+
+    """
     for index, current_hour in enumerate(rave_avail_hours):
         file_name = rave_avail[index]
         rave_file_path = os.path.join(RAVE, file_name[0])  
@@ -221,4 +314,4 @@ def interpolate_rave(RAVE, rave_avail, rave_avail_hours, use_dummy_emiss, vars_e
             except (OSError, IOError, RuntimeError, FileNotFoundError, TypeError, IndexError, MemoryError) as e:
                 print(f"Error reading NetCDF file {rave_file_path}: {e}")
         else:
-            print(f"File not found or dummy emissions required: {rave_file_path}")
+            print(f"File not found or dummy emissions required: {rave_file_path}")