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.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.interpolate_to_model_level
   credit.nwp.format_data
   credit.nwp.format_datetime


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

.. py:data:: gfs_map

.. py:data:: level_map

.. py:data:: upper_air
   :value: ['T', 'U', 'V', 'Q', 'Z']


.. py:data:: surface
   :value: ['SP', 't2m']


.. py:function:: build_GFS_init(output_grid, date, variables, model_level_indices, gdas_base_path='https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod/', n_procs=1)

   Create GFS initial conditions on model levels that are interpolated from ECMWF L137 model levels.
   :param output_grid: grid of ERA5 model levels
   :type output_grid: xr.DataArray
   :param date: date of GFS initialization
   :type date: pd.Timestamp
   :param variables: list of variable names
   :type variables: list
   :param model_level_indices: list of model level indices to extract from L137 model levels
   :type model_level_indices: list
   :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 n_procs: Number of processors to use in pool.
   :type n_procs: int

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


.. py:function:: add_pressure_and_geopotential(data)

   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')

   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')

   :returns: (str) NOMADS filepaths


.. 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)

   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='conservative', pool=None)

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

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


.. py:function:: interpolate_to_model_level(regridded_nwp_data, output_grid, model_level_indices, variables)

   Verticallly interpolate GFS model level data to CREDIT model levels
   :param regridded_nwp_data: (xr.Dataset) GFS initial conditions on CREDIT grid
   :param output_grid: (xr.Dataset) CREDIT Grid
   :param model_level_indices: (list) list of model level indices to extract from L137 model levels
   :param variables: (list) list of variable names

   :returns: Dictionary of xr.DataArrays of interpolated GFS model level data
   :rtype: (dict)


.. 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