credit.nwp
==========

.. py:module:: credit.nwp


Attributes
----------

.. autoapisummary::

   credit.nwp.gfs_map
   credit.nwp.level_map
   credit.nwp.upper_air
   credit.nwp.surface


Functions
---------

.. autoapisummary::

   credit.nwp.build_GFS_init
   credit.nwp._get_gfs_maps
   credit.nwp._add_pressure_and_geopotential
   credit.nwp._build_file_path
   credit.nwp._load_gfs_variable
   credit.nwp._load_gfs_data
   credit.nwp._combine_data
   credit.nwp._regrid_variable
   credit.nwp._regrid
   credit.nwp._vertical_interpolation
   credit.nwp._format_data
   credit.nwp._format_datetime


Module Contents
---------------

.. py:data:: gfs_map

.. py:data:: level_map

.. py:data:: upper_air

.. py:data:: surface

.. py:function:: build_GFS_init(output_grid: xarray.Dataset, date: pandas.Timestamp, variables: list, model_level_file: str = '', model_levels: numpy.ndarray = None, gdas_base_path: str = 'gs://global-forecast-system/', variable_mapping: str = 'wchapmanera5', n_procs: int = 1)

   Download GFS model level initial conditions, regrid to CREDIT model's grid, and vertically interpolate
   3D variables to CREDIT model levels.

   :param output_grid: netCDF file containing latitude and longitude coordinates of CREDIT model grid.
   :type output_grid: xr.Dataset
   :param date: date of GFS initialization
   :type date: pd.Timestamp
   :param variables: list of variable names.
   :type variables: list
   :param model_level_file: Path to file containing output model level a and b coefficients on full and half levels.
   :type model_level_file: str
   :param model_levels: Subset of model levels to interpolate to.
   :type model_levels: np.ndarray
   :param gdas_base_path: Path to GFS base directory on NOMADS (archives last 10 days) or Google Cloud (since 2021)
   :type gdas_base_path: str
   :param variable_mapping:
   :type variable_mapping: str
   :param n_procs: Number of processors to use in pool.
   :type n_procs: int

   :returns: (xr.Dataset) Interpolated GFS initial conditions


.. py:function:: _get_gfs_maps(variable_mapping_type: str)

.. py:function:: _add_pressure_and_geopotential(data, temperature_var, specific_humidity_var)

   Derive pressure and geopotential fields from model level data and to dataset
   :param data: (xr.Dataset) GFS model level data

   :returns: xr.Dataset


.. py:function:: _build_file_path(date, base_path, file_type='atm', step='f000')

   Create NOMADS filepaths for etiher upper air or surface data
   :param date: (pd.Timestamp) date of GFS initialization
   :param base_path: (str) NOMADS base directory (archives last 10 days)
   :param file_type: (str) Type of analysis data (supports 'atm' or 'sfc')
   :param step: (str) "anl" or "f000" to "f009". f times have additional diagnostics
                like ugrd10 and vgrd10 not found in the analysis files.

   :returns: (str) NOMADS or Google Cloud filepaths that can be read in xarray with the h5netcdf engine


.. py:function:: _load_gfs_variable(variable, full_file_path=None)

.. py:function:: _load_gfs_data(full_file_path, variables, pool=None)

   Load GFS data directly from Nomads or Google Cloud server
   :param full_file_path: (str) NOMADS filepath
   :param variables: (list) list of variable names

   :returns: xr.Dataset


.. py:function:: _combine_data(atm_data, sfc_data, temperature_var, specific_humidity_var)

   Merge upper air and surface data
   :param atm_data: (xr.Dataset) GFS upper air data
   :param sfc_data: (xr.Dataset) GFS surface data

   :returns: xr.Dataset


.. py:function:: _regrid_variable(variable_data, regridder)

.. py:function:: _regrid(nwp_data, output_grid, method='bilinear', pool=None)

   Spatially regrid (interpolate) from GFS grid to CREDIT grid
   :param nwp_data: GFS initial conditions
   :type nwp_data: xr.Dataset
   :param output_grid: CREDIT grid
   :type output_grid: xr.Dataset
   :param method: conservative or bilinear
   :type method: str

   :returns: Regridded GFS initial conditions
   :rtype: (xr.Dataset)


.. py:function:: _vertical_interpolation(state_dataset, model_level_file, model_levels, variable_mapping, variables, surface_pressure_var)

.. py:function:: _format_data(data_dict, regridded_data, model_levels)

   Format data for CREDIT model ingestion
   :param data_dict: (dict) Dictionary of xr.DataArrays of interpolated GFS model level data
   :param regridded_data: (xr.Dataset) GFS initial conditions on CREDIT grid
   :param model_levels: (list) list of model level indices to extract from L137 model levels

   :returns: xr.Dataset of GFS initial conditions interpolated to CREDIT grid and model levels


.. py:function:: _format_datetime(init_time)

   Format datetime string from CREDIT configuration file
   :param init_time: (dict) Dictionary of Forecast times from configuration file

   :returns: pd.Timestamp of initialization time