diff --git a/src/wrf/api.py b/src/wrf/api.py index 46f7d46..7882541 100644 --- a/src/wrf/api.py +++ b/src/wrf/api.py @@ -3,24 +3,24 @@ from .config import (xarray_enabled, disable_xarray, enable_xarray, basemap_enabled, disable_basemap, enable_basemap, pyngl_enabled, enable_pyngl, disable_pyngl, set_cache_size, get_cache_size, omp_enabled) -from .constants import (ALL_TIMES, Constants, ConversionFactors, +from .constants import (ALL_TIMES, Constants, ConversionFactors, ProjectionTypes, default_fill, - OMP_SCHED_STATIC, OMP_SCHED_DYNAMIC, + OMP_SCHED_STATIC, OMP_SCHED_DYNAMIC, OMP_SCHED_GUIDED, OMP_SCHED_AUTO) from .destag import destagger from .routines import getvar -from .computation import (xy, interp1d, interp2dxy, interpz3d, slp, tk, td, rh, +from .computation import (xy, interp1d, interp2dxy, interpz3d, slp, tk, td, rh, uvmet, smooth2d, cape_2d, cape_3d, cloudfrac, ctt, dbz, srhel, udhel, avo, pvo, eth, wetbulb, tvirtual, omega, pw) -from .extension import (DiagnosticError, omp_set_num_threads, - omp_get_num_threads, +from .extension import (DiagnosticError, omp_set_num_threads, + omp_get_num_threads, omp_get_max_threads, omp_get_thread_num, - omp_get_num_procs, omp_in_parallel, + omp_get_num_procs, omp_in_parallel, omp_set_dynamic, omp_get_dynamic, omp_set_nested, - omp_get_nested, omp_set_schedule, - omp_get_schedule, omp_get_thread_limit, - omp_set_max_active_levels, + omp_get_nested, omp_set_schedule, + omp_get_schedule, omp_get_thread_limit, + omp_set_max_active_levels, omp_get_max_active_levels, omp_get_level, omp_get_ancestor_thread_num, omp_get_team_size, omp_get_active_level, omp_in_final, @@ -32,23 +32,23 @@ from .extension import (DiagnosticError, omp_set_num_threads, omp_get_wtime, omp_get_wtick) from .interp import (interplevel, vertcross, interpline, vinterp) from .g_latlon import (xy_to_ll, ll_to_xy, xy_to_ll_proj, ll_to_xy_proj) -from .py3compat import (viewitems, viewkeys, viewvalues, isstr, py2round, +from .py3compat import (viewitems, viewkeys, viewvalues, isstr, py2round, py3range, ucode) from .util import (to_np, extract_global_attrs, is_standard_wrf_var, extract_dim, extract_vars, extract_times, combine_files, - extract_times, npbytes_to_str, is_moving_domain, + extract_times, npbytes_to_str, is_moving_domain, is_staggered, get_left_indexes, iter_left_indexes, - get_right_slices, get_proj_params, from_args, + get_right_slices, get_proj_params, from_args, args_to_list, arg_location, psafilepath, get_id, from_var, combine_dims, either, get_iterable, IterWrapper, is_coordvar, latlon_coordvars, is_mapping, has_time_coord, is_multi_file, is_multi_time_req, - get_coord_pairs, is_time_coord_var, geo_bounds, + get_coord_pairs, is_time_coord_var, geo_bounds, get_cartopy, get_basemap, get_pyngl, cartopy_xlim, cartopy_ylim, latlon_coords, ll_points, pairs_to_latlon) from .geobnds import GeoBounds, NullGeoBounds from .projection import (WrfProj, NullProjection, LambertConformal, Mercator, - PolarStereographic, LatLon, RotatedLatLon, + PolarStereographic, LatLon, RotatedLatLon, getproj) from .coordpair import CoordPair from .interputils import to_xy_coords @@ -62,22 +62,22 @@ __all__ += ["xarray_enabled", "disable_xarray", "enable_xarray", "pyngl_enabled", "enable_pyngl", "disable_pyngl", "set_cache_size", "get_cache_size", "omp_enabled"] __all__ += ["ALL_TIMES", "Constants", "ConversionFactors", "ProjectionTypes", - "default_fill", "OMP_SCHED_STATIC", "OMP_SCHED_DYNAMIC", + "default_fill", "OMP_SCHED_STATIC", "OMP_SCHED_DYNAMIC", "OMP_SCHED_GUIDED", "OMP_SCHED_AUTO"] __all__ += ["destagger"] __all__ += ["getvar"] -__all__ += ["xy", "interp1d", "interp2dxy", "interpz3d", "slp", "tk", "td", +__all__ += ["xy", "interp1d", "interp2dxy", "interpz3d", "slp", "tk", "td", "rh", "uvmet", "smooth2d", "cape_2d", "cape_3d", "cloudfrac", "ctt", "dbz", "srhel", "udhel", "avo", "pvo", "eth", "wetbulb", "tvirtual", "omega", "pw"] -__all__ += ["DiagnosticError", "omp_set_num_threads", - "omp_get_num_threads", +__all__ += ["DiagnosticError", "omp_set_num_threads", + "omp_get_num_threads", "omp_get_max_threads", "omp_get_thread_num", - "omp_get_num_procs", "omp_in_parallel", + "omp_get_num_procs", "omp_in_parallel", "omp_set_dynamic", "omp_get_dynamic", "omp_set_nested", - "omp_get_nested", "omp_set_schedule", - "omp_get_schedule", "omp_get_thread_limit", - "omp_set_max_active_levels", + "omp_get_nested", "omp_set_schedule", + "omp_get_schedule", "omp_get_thread_limit", + "omp_set_max_active_levels", "omp_get_max_active_levels", "omp_get_level", "omp_get_ancestor_thread_num", "omp_get_team_size", "omp_get_active_level", "omp_in_final", @@ -89,18 +89,18 @@ __all__ += ["DiagnosticError", "omp_set_num_threads", "omp_get_wtime", "omp_get_wtick"] __all__ += ["interplevel", "vertcross", "interpline", "vinterp"] __all__ += ["xy_to_ll", "ll_to_xy", "xy_to_ll_proj", "ll_to_xy_proj"] -__all__ += ["viewitems", "viewkeys", "viewvalues", "isstr", "py2round", +__all__ += ["viewitems", "viewkeys", "viewvalues", "isstr", "py2round", "py3range", "ucode"] __all__ += ["to_np", "extract_global_attrs", "is_standard_wrf_var", "extract_dim", "extract_vars", "extract_times", "combine_files", - "extract_times", "npbytes_to_str", "is_moving_domain", - "is_staggered", "get_left_indexes", "iter_left_indexes", - "get_right_slices", "get_proj_params", "from_args", + "extract_times", "npbytes_to_str", "is_moving_domain", + "is_staggered", "get_left_indexes", "iter_left_indexes", + "get_right_slices", "get_proj_params", "from_args", "args_to_list", "arg_location", "psafilepath", "get_id", "from_var", "combine_dims", "either", "get_iterable", "IterWrapper", "is_coordvar", "latlon_coordvars", "is_mapping", "has_time_coord", "is_multi_file", "is_multi_time_req", - "get_coord_pairs", "is_time_coord_var", "geo_bounds", + "get_coord_pairs", "is_time_coord_var", "geo_bounds", "get_cartopy", "get_basemap", "get_pyngl", "cartopy_xlim", "cartopy_ylim", "latlon_coords", "ll_points", "pairs_to_latlon"] __all__ += ["GeoBounds", "NullGeoBounds"] @@ -110,4 +110,3 @@ __all__ += ["CoordPair"] __all__ += ["to_xy_coords"] __all__ += ["cache_item", "get_cached_item"] __all__ += ["__version__"] - diff --git a/src/wrf/cache.py b/src/wrf/cache.py index 571f653..64a4da6 100644 --- a/src/wrf/cache.py +++ b/src/wrf/cache.py @@ -11,158 +11,153 @@ _local_storage = local() def _shrink_cache(): """Shrink the cache if applicable. - - This only applies if a user has modified the cache size, otherwise it + + This only applies if a user has modified the cache size, otherwise it just returns. - + Returns: - + None - + """ global _local_storage - + try: cache = _local_storage.cache except AttributeError: return - + diff = len(cache) - get_cache_size() - + if diff > 0: for _ in py3range(diff): cache.popitem(last=False) - + def cache_item(key, product, value): """Store an item in the threadlocal cache. - - The cache should be viewed as two nested dictionaries. The outer key is - usually the id for the sequence where the cached item was generated. The + + The cache should be viewed as two nested dictionaries. The outer key is + usually the id for the sequence where the cached item was generated. The inner key is the product type. - + Storing a cached item behaves like: - + cache[key][product] = value - - The cache is thread local, so stored items are only available in + + The cache is thread local, so stored items are only available in the thread that cached them. - + Args: - - key (:obj:`int`): The outer dictionary cache key, which is typically + + key (:obj:`int`): The outer dictionary cache key, which is typically the id of the sequence where the cached item was generated. - - product (:obj:`str`): The inner dictionary cache key, which is a + + product (:obj:`str`): The inner dictionary cache key, which is a string for the product type. - + value (:obj:`object`): The object to store in the cache. - + Returns: - + None. - + See Also: - + :meth:`get_cached_item` - + """ global _local_storage - + _shrink_cache() - + if key is None or get_cache_size() == 0: return - + try: cache = _local_storage.cache except AttributeError: _local_storage.cache = OrderedDict() cache = _local_storage.cache - + try: _ = cache[key] except KeyError: if len(cache) >= get_cache_size(): - cache.popitem(last=False) # Remove the oldest dataset - + cache.popitem(last=False) # Remove the oldest dataset + cache[key] = OrderedDict() - + cache[key][product] = value - - + + def get_cached_item(key, product): """Return an item from the threadlocal cache. - - The cache should be viewed as two nested dictionaries. The outer key is - usually the id for the sequence where the cached item was generated. The + + The cache should be viewed as two nested dictionaries. The outer key is + usually the id for the sequence where the cached item was generated. The inner key is the product type. - + Retrieving a cached item behaves like: - + value = cache[key][product] - - The cache is thread local, so stored items are only available in + + The cache is thread local, so stored items are only available in the thread that cached them. - + Args: - - key (:obj:`int`): The outer dictionary cache key, which is typically + + key (:obj:`int`): The outer dictionary cache key, which is typically the id of the sequence where the cached item was generated. - - product (:obj:`str`): The inner dictionary cache key, which is a + + product (:obj:`str`): The inner dictionary cache key, which is a string for the product type. - + Returns: - + :obj:`object`: The cached object. - + See Also: - + :meth:`cache_item` - + """ global _local_storage - + _shrink_cache() - + if key is None or get_cache_size == 0: return None - + cache = getattr(_local_storage, "cache", None) - + if cache is None: return None - + if len(cache) == 0: return None - + prod_dict = cache.get(key, None) - + if prod_dict is None: return None - + result = prod_dict.get(product, None) - + return result def _get_cache(): """Return the threadlocal cache. - + This is primarily used for testing. - + Returns: - + :class:`threading.local` - + """ global _local_storage - + _shrink_cache() return getattr(_local_storage, "cache", None) - - - - - \ No newline at end of file diff --git a/src/wrf/computation.py b/src/wrf/computation.py index f75ae87..5241230 100644 --- a/src/wrf/computation.py +++ b/src/wrf/computation.py @@ -4,174 +4,175 @@ import numpy as np import numpy.ma as ma from .constants import default_fill -from .extension import (_interpz3d, _interp2dxy, _interp1d, _slp, _tk, _td, +from .extension import (_interpz3d, _interp2dxy, _interp1d, _slp, _tk, _td, _rh, _uvmet, _smooth2d, _cape, _cloudfrac, _ctt, _dbz, - _srhel, _udhel, _avo, _pvo, _eth, _wetbulb, _tv, + _srhel, _udhel, _avo, _pvo, _eth, _wetbulb, _tv, _omega, _pw) from .decorators import convert_units -from .metadecorators import (set_alg_metadata, set_uvmet_alg_metadata, +from .metadecorators import (set_alg_metadata, set_uvmet_alg_metadata, set_interp_metadata, set_cape_alg_metadata, set_cloudfrac_alg_metadata, set_smooth_metdata) from .interputils import get_xy + @set_interp_metadata("xy") def xy(field, pivot_point=None, angle=None, start_point=None, end_point=None, meta=True): """Return the x,y points for a line within a two-dimensional grid. - - This function is primarily used to obtain the x,y points when making a + + This function is primarily used to obtain the x,y points when making a cross section. - + Args: - - field (:class:`xarray.DataArray` or :class:`numpy.ndarray`): A + + field (:class:`xarray.DataArray` or :class:`numpy.ndarray`): A field with at least two dimensions. - - pivot_point (:obj:`tuple` or :obj:`list`, optional): A - :obj:`tuple` or :obj:`list` with two entries, - in the form of [x, y] (or [west_east, south_north]), which - indicates the x,y location through which the plane will pass. + + pivot_point (:obj:`tuple` or :obj:`list`, optional): A + :obj:`tuple` or :obj:`list` with two entries, + in the form of [x, y] (or [west_east, south_north]), which + indicates the x,y location through which the plane will pass. Must also specify `angle`. - - angle (:obj:`float`, optional): Only valid for cross sections where - a plane will be plotted through - a given point on the model domain. 0.0 represents a S-N cross - section. 90.0 is a W-E cross section. - - start_point (:obj:`tuple` or :obj:`list`, optional): A - :obj:`tuple` or :obj:`list` with two entries, in the form of - [x, y] (or [west_east, south_north]), which indicates the start + + angle (:obj:`float`, optional): Only valid for cross sections where + a plane will be plotted through + a given point on the model domain. 0.0 represents a S-N cross + section. 90.0 is a W-E cross section. + + start_point (:obj:`tuple` or :obj:`list`, optional): A + :obj:`tuple` or :obj:`list` with two entries, in the form of + [x, y] (or [west_east, south_north]), which indicates the start x,y location through which the plane will pass. - - end_point (:obj:`tuple` or :obj:`list`, optional): A - :obj:`tuple` or :obj:`list` with two entries, in the form of - [x, y] (or [west_east, south_north]), which indicates the end x,y + + end_point (:obj:`tuple` or :obj:`list`, optional): A + :obj:`tuple` or :obj:`list` with two entries, in the form of + [x, y] (or [west_east, south_north]), which indicates the end x,y location through which the plane will pass. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: An array of - x,y points, which has shape num_points x 2. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: An array of + x,y points, which has shape num_points x 2. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + Examples: - + Example 1: Using Pivot Point and Angle - + .. code-block:: python - + from wrf import getvar, xy from netCDF4 import Dataset - + wrfnc = Dataset("wrfout_d02_2010-06-13_21:00:00") field = wrf.getvar(wrfnc, "slp") - + # Use the center of the grid pivot = (field.shape[-1]/2.0, field.shape[-2]/2.0) - + # West-East angle = 90.0 - + xy_points = xy(field, pivot_point=pivot, angle=angle) - + Example 2: Using Start Point and End Point - + .. code-block:: python - + from wrf import getvar, xy from netCDF4 import Dataset - + wrfnc = Dataset("wrfout_d02_2010-06-13_21:00:00") field = wrf.getvar(wrfnc, "slp") - + # Make a diagonal of lower left to upper right start = (0, 0) end = (-1, -1) - + xy_points = xy(field, start_point=start, end_point=end) - - + + """ return get_xy(field, pivot_point, angle, start_point, end_point) - + @set_interp_metadata("1d") -def interp1d(field, z_in, z_out, missing=default_fill(np.float64), +def interp1d(field, z_in, z_out, missing=default_fill(np.float64), meta=True): """Return the linear interpolation of a one-dimensional variable. - + This function is typically used to interpolate a variable in a vertical - column, but the coordinate system need not be a vertical coordinate - system. Multiple interpolation points may be specified in the *z_out* + column, but the coordinate system need not be a vertical coordinate + system. Multiple interpolation points may be specified in the *z_out* parameter. - + Args: - + field (:class:`xarray.DataArray` or :class:`numpy.ndarray`): A - one-dimensional field. Metadata for *field* is only copied + one-dimensional field. Metadata for *field* is only copied to the output if *field* is a :class:`xarray.DataArray` object. - - z_in (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The - one-dimensional coordinates associated with *field* (usually the + + z_in (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The + one-dimensional coordinates associated with *field* (usually the vertical coordinates, either height or pressure). - - z_out (:class:`xarray.DataArray`, :class:`numpy.ndarray`): A - one-dimensional array of *z_in* coordinate points to interpolate - to. Must be the same type as *z_in*. - - missing (:obj:`float`, optional): The fill value to use for the + + z_out (:class:`xarray.DataArray`, :class:`numpy.ndarray`): A + one-dimensional array of *z_in* coordinate points to interpolate + to. Must be the same type as *z_in*. + + missing (:obj:`float`, optional): The fill value to use for the output. Default is :data:`wrf.default_fill(np.float64)`. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - + :class:`xarray.DataArray` or :class:`numpy.ndarray`: An array with the same dimensionality as *z_out* containing the interpolated values. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - - + + Examples: - + Example 1: Calculate the 850 hPa and 500 hPa values at location \ x,y = (100,200) - + .. code-block:: python - + import numpy as np from wrf import getvar, interp1d from netCDF4 import Dataset - + wrfnc = Dataset("wrfout_d02_2010-06-13_21:00:00") - + # Get a 1D vertical column for pressure at location x,y = 100,200 p_1d = wrf.getvar(wrfnc, "pres", units="hPa")[:,200,100] - + # Get a 1D vertical column for height at location 100,200 ht_1d = wrf.getvar(wrfnc, "z", units="dm")[:,200,100] - + # Want the heights (in decameters) at 850, 500 hPa levels = np.asarray([850., 500.]) - + # Get the 850 hPa and 500 hPa values at location 100,200. interp_vals = interp1d(p_1d, ht_1d, levels) - + """ return _interp1d(field, z_in, z_out, missing) @@ -179,72 +180,72 @@ def interp1d(field, z_in, z_out, missing=default_fill(np.float64), @set_interp_metadata("2dxy") def interp2dxy(field3d, xy, meta=True): """Return a cross section for a three-dimensional field. - - The returned array will hold the vertical cross section data along the + + The returned array will hold the vertical cross section data along the line described by *xy*. - - This method differs from :meth:`wrf.vertcross` in that it will return - all vertical levels found in *field3d*. :meth:`wrf.vertcross` includes - an additional interpolation to set the output to a fixed number of - vertical levels. Also, a :class:`numpy.ma.MaskedArray` is not created - and this routine should be considered as low-level access to the underlying + + This method differs from :meth:`wrf.vertcross` in that it will return + all vertical levels found in *field3d*. :meth:`wrf.vertcross` includes + an additional interpolation to set the output to a fixed number of + vertical levels. Also, a :class:`numpy.ma.MaskedArray` is not created + and this routine should be considered as low-level access to the underlying Fortran routine. - + See Also: - + :meth:`wrf.xy`, :meth:`wrf.vertcross` - + Args: - - field3d (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The - array to interpolate with at least three dimensions, whose + + field3d (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The + array to interpolate with at least three dimensions, whose rightmost dimensions are nz x ny x nx. - - xy (:class:`xarray.DataArray` or :class:`numpy.ndarray`): An array - of one less dimension than *field3d*, whose rightmost dimensions - are nxy x 2. This array holds the x,y pairs of a line across the - model domain. The requested vertical cross section will be + + xy (:class:`xarray.DataArray` or :class:`numpy.ndarray`): An array + of one less dimension than *field3d*, whose rightmost dimensions + are nxy x 2. This array holds the x,y pairs of a line across the + model domain. The requested vertical cross section will be extracted from *field3d* along this line. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - - + + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: An array - containing the vertical cross section along the line *xy*. The + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: An array + containing the vertical cross section along the line *xy*. The returned dimensions will be the same as *xy*, but with the rightmost - dimensions being nz x nxy. If xarray is enabled and the *meta* - parameter is True, then the result will be a :class:`xarray.DataArray` - object. Otherwise, the result will + dimensions being nz x nxy. If xarray is enabled and the *meta* + parameter is True, then the result will be a :class:`xarray.DataArray` + object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + Examples: - - Example 1: Calculate the vertical cross section for RH for a diagonal + + Example 1: Calculate the vertical cross section for RH for a diagonal line from the lower left to the upper right of the domain. - + .. code-block:: python - + from wrf import getvar, xy, interp2dxy from netCDF4 import Dataset - + wrfnc = Dataset("wrfout_d02_2010-06-13_21:00:00") - + rh = getvar(wrfnc, "rh") start = (0, 0) end = (-1, -1) xy_line = xy(rh, start_point=start, end_point=end) - + vert_cross = interp2dxy(rh, xy_line) - + """ return _interp2dxy(field3d, xy) @@ -253,67 +254,67 @@ def interp2dxy(field3d, xy, meta=True): def interpz3d(field3d, vert, desiredlev, missing=default_fill(np.float64), meta=True): """Return the field interpolated to a specified pressure or height level. - - This function is roughly equivalent to :meth:`interplevel`, but does not - handle multi-product diagnostics (uvmet, cape_3d, etc) that contain an - additional leftmost dimension for the product type. Also, a + + This function is roughly equivalent to :meth:`interplevel`, but does not + handle multi-product diagnostics (uvmet, cape_3d, etc) that contain an + additional leftmost dimension for the product type. Also, a :class:`numpy.ma.MaskedArray` is not created and this routine should be considered as low-level access to the underlying Fortran routine. - + See Also: - + :meth:`wrf.interplevel` - + Args: - - field3d (:class:`xarray.DataArray` or :class:`numpy.ndarray`): A - three-dimensional field to interpolate, with the rightmost + + field3d (:class:`xarray.DataArray` or :class:`numpy.ndarray`): A + three-dimensional field to interpolate, with the rightmost dimensions of nz x ny x nx. - - vert (:class:`xarray.DataArray` or :class:`numpy.ndarray`): A - three-dimensional array for the vertical coordinate, typically + + vert (:class:`xarray.DataArray` or :class:`numpy.ndarray`): A + three-dimensional array for the vertical coordinate, typically pressure or height. This array must have the same dimensionality as *field3d*. - - desiredlev (:obj:`float`): The desired vertical level. + + desiredlev (:obj:`float`): The desired vertical level. Must be in the same units as the *vert* parameter. - - missing (:obj:`float`): The fill value to use for the output. + + missing (:obj:`float`): The fill value to use for the output. Default is :data:`wrf.default_fill(numpy.float64)`. - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - interpolated variable. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + interpolated variable. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + Example: - + Example 1: Interpolate Geopotential Height to 500 hPa - + .. code-block:: python - + from netCDF4 import Dataset from wrf import getvar, interpz3d - + wrfin = Dataset("wrfout_d02_2010-06-13_21:00:00") - + p = getvar(wrfin, "pressure") ht = getvar(wrfin, "z", units="dm") - + ht_500 = interpz3d(ht, p, 500.0) - + """ return _interpz3d(field3d, vert, desiredlev, missing) @@ -322,59 +323,59 @@ def interpz3d(field3d, vert, desiredlev, missing=default_fill(np.float64), @convert_units("pressure", "hpa") def slp(height, tkel, pres, qv, meta=True, units="hPa"): """Return the sea level pressure. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - + Args: - - height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - Geopotential height in [m] with the rightmost dimensions being + + height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + Geopotential height in [m] with the rightmost dimensions being bottom_top x south_north x west_east. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature - in [K] with same dimensionality as *height*. - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [Pa] with - the same dimensionality as *height*. - - Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + in [K] with same dimensionality as *height*. + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [Pa] with + the same dimensionality as *height*. + + Note: + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor mixing ratio in [kg/kg] with the same dimensionality as *height*. - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'slp'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'slp'. Default is 'hPa'. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - sea level pressure. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + sea level pressure. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.temp`, :meth:`wrf.tk` - + """ return _slp(height, tkel, pres, qv) @@ -383,56 +384,56 @@ def slp(height, tkel, pres, qv, meta=True, units="hPa"): @convert_units("temp", "k") def tk(pres, theta, meta=True, units="K"): """Return the temperature. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + + Args: + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full pressure (perturbation + base state pressure) in [Pa] with at least - three dimensions. The rightmost dimensions are bottom_top x - south_north x west_east. - + three dimensions. The rightmost dimensions are bottom_top x + south_north x west_east. + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - + theta (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Potential temperature (perturbation plus reference temperature) in [K] with the same dimensionality as *pres*. - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'temp'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'temp'. Default is 'K'. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - temperature in the specified units. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + temperature in the specified units. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.tk` - + """ - + return _tk(pres, theta) @@ -440,53 +441,53 @@ def tk(pres, theta, meta=True, units="K"): @convert_units("temp", "c") def td(pres, qv, meta=True, units="degC"): """Return the dewpoint temperature. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [hPa] with at - least three dimensions. The rightmost dimensions are bottom_top x - south_north x west_east. - + + Args: + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [hPa] with at + least three dimensions. The rightmost dimensions are bottom_top x + south_north x west_east. + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor mixing ratio in [kg/kg] with the same dimensionality as *pres*. - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'dp'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'dp'. Default is 'degC'. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - dewpoint temperature. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + dewpoint temperature. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.rh` - + """ return _td(pres, qv) @@ -494,59 +495,59 @@ def td(pres, qv, meta=True, units="degC"): @set_alg_metadata(3, "pres", description="relative humidity", units=None) def rh(qv, pres, tkel, meta=True): """Return the relative humidity. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor - mixing ratio in [kg/kg] with at least three dimensions. The - rightmost dimensions are bottom_top x south_north x west_east. - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [Pa] with the - same dimensionality as *qv*. - + + Args: + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + mixing ratio in [kg/kg] with at least three dimensions. The + rightmost dimensions are bottom_top x south_north x west_east. + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [Pa] with the + same dimensionality as *qv*. + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature in [K] with same dimensionality as *qv*. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - relative humidity. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + relative humidity. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.td` - + """ return _rh(qv, pres, tkel) @@ -555,123 +556,123 @@ def rh(qv, pres, tkel, meta=True): @convert_units("wind", "m s-1") def uvmet(u, v, lat, lon, cen_long, cone, meta=True, units="m s-1"): """Return the u,v components of the wind rotated to earth coordinates. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - - - return_val[0,...] will contain U + + - return_val[0,...] will contain U - return_val[1,...] will contain V - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - u (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The u - component of the wind [m s-1]. This variable can be staggered or + + Args: + + u (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The u + component of the wind [m s-1]. This variable can be staggered or unstaggered, but must be at least two dimensions. If staggered, the rightmost dimensions are south_north x west east. - - If staggered, the rightmost dimensions are south_north x + + If staggered, the rightmost dimensions are south_north x west_east_stag. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will - be used. - - v (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The v - component of the wind [m s-1]. This variable can be staggered or + be used. + + v (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The v + component of the wind [m s-1]. This variable can be staggered or unstaggered, but must be at least two dimensions. If staggered, the rightmost dimensions are south_north x west east. - - If staggered, the rightmost dimensions are south_north_stag x + + If staggered, the rightmost dimensions are south_north_stag x west_east. - - lat (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The - latitude array. - + + lat (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The + latitude array. + This array can either be: - + - two-dimensional of size south_north x west_east. - - multi-dimensional with the same number of dimensions as *u* - and *v*, but with rightmost dimensions south_north x + - multi-dimensional with the same number of dimensions as *u* + and *v*, but with rightmost dimensions south_north x west_east and the same leftmost dimensions as *u* and *v* - - multi-dimensional with one fewer dimensions as *u* and *v*, - with rightmost dimensions south_north x west_east and the same - leftmost dimensions as *u* and *v*, minus the + - multi-dimensional with one fewer dimensions as *u* and *v*, + with rightmost dimensions south_north x west_east and the + same leftmost dimensions as *u* and *v*, minus the third-from-the-right dimension of *u* and *v*. - + Note: - - This variable must also be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must also be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will - be used. - - lon (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The - longitude array. - + be used. + + lon (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The + longitude array. + This array can either be: - + - two-dimensional of size south_north x west_east. - - multi-dimensional with the same number of dimensions as *u* - and *v*, but with rightmost dimensions south_north x + - multi-dimensional with the same number of dimensions as *u* + and *v*, but with rightmost dimensions south_north x west_east and the same leftmost dimensions as *u* and *v* - - multi-dimensional with one fewer dimensions as *u* and *v*, - with rightmost dimensions south_north x west_east and the same - leftmost dimensions as *u* and *v*, minus the + - multi-dimensional with one fewer dimensions as *u* and *v*, + with rightmost dimensions south_north x west_east and the + same leftmost dimensions as *u* and *v*, minus the third-from-the-right dimension of *u* and *v*. - - + + cen_long (:obj:`float`): The standard longitude for the map projection. - - cone (:obj:`float`): The cone factor used for the map project. If the - projection is not a conic projection, the *cone* is simply 1.0. + + cone (:obj:`float`): The cone factor used for the map project. If the + projection is not a conic projection, the *cone* is simply 1.0. For conic projections, the cone factor is given by: - + .. code-block:: python - - if((fabs(true_lat1 - true_lat2) > 0.1) and - (fabs(true_lat2 - 90.) > 0.1)): - cone = (log(cos(true_lat1*radians_per_degree)) + + if((fabs(true_lat1 - true_lat2) > 0.1) and + (fabs(true_lat2 - 90.) > 0.1)): + cone = (log(cos(true_lat1*radians_per_degree)) - log(cos(true_lat2*radians_per_degree))) - - cone = (cone / - (log(tan((45.-fabs(true_lat1/2.))*radians_per_degree)) - - log(tan((45.-fabs(true_lat2/2.))*radians_per_degree)))) + + cone = (cone / + (log(tan((45.-fabs(true_lat1/2.))*radians_per_degree)) + - log(tan((45.-fabs(true_lat2/2.))*radians_per_degree)))) else: cone = sin(fabs(true_lat1)*radians_per_degree) - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet'. Default is 'm s-1'. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - u,v components of the wind rotated to earth coordinates. The leftmost - dimension size is 2, for u and v. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + u,v components of the wind rotated to earth coordinates. The leftmost + dimension size is 2, for u and v. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar` - + """ return _uvmet(u, v, lat, lon, cen_long, cone) @@ -679,323 +680,323 @@ def uvmet(u, v, lat, lon, cen_long, cone, meta=True, units="m s-1"): @set_smooth_metdata() def smooth2d(field, passes, cenweight=2.0, meta=True): """Return the field smoothed. - + The smoothing kernel applied is: - - .. math:: - + + .. math:: + \\frac{1}{4 + cenweight} * \\begin{bmatrix} 0 & 1 & 0 \\\\ 1 & cenweight & 1 \\\\ 0 & 1 & 0 \\end{bmatrix} - - Data values along the borders are left unchanged. This routine does not + + Data values along the borders are left unchanged. This routine does not modify the original data supplied by the *field* parameter.. - - If you need more general purpose multidimensional filtering tools, + + If you need more general purpose multidimensional filtering tools, try the :meth:`scipy.ndimage.convolve` method. - + Args: - + field (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The field - to smooth, which must be at least two dimensions. Missing/fill - values will be ignored as long as the type is either a - :class:`numpy.ma.MaskedArray` or a :class:`xarray.DataArray` with + to smooth, which must be at least two dimensions. Missing/fill + values will be ignored as long as the type is either a + :class:`numpy.ma.MaskedArray` or a :class:`xarray.DataArray` with a *_FillValue* attribute. - + passes (:obj:`int`): The number of smoothing passes. - - cenweight (:obj:`float`, optional): The weight to apply to the + + cenweight (:obj:`float`, optional): The weight to apply to the center of the smoothing kernel. Default is 2.0. - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Returns: - + :class:`xarray.DataArray`, :class:`numpy.ma.MaskedArray` or \ - :class:`numpy.ndarray`): The smoothed field. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will - be either a :class:`numpy.ndarray` or a :class:`numpy.ma.MaskedArray` + :class:`numpy.ndarray`): The smoothed field. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will + be either a :class:`numpy.ndarray` or a :class:`numpy.ma.MaskedArray` depending on the type for *field*. - + See Also: - + :meth:`scipy.ndimage.convolve` - - + + """ return _smooth2d(field, passes, cenweight) @set_cape_alg_metadata(is2d=True, copyarg="pres_hpa") -def cape_2d(pres_hpa, tkel, qv, height, terrain, psfc_hpa, ter_follow, +def cape_2d(pres_hpa, tkel, qv, height, terrain, psfc_hpa, ter_follow, missing=default_fill(np.float64), meta=True): """Return the two-dimensional MCAPE, MCIN, LCL, and LFC. - - This function calculates the maximum convective available potential - energy (MCAPE), maximum convective inhibition (MCIN), - lifted condensation level (LCL), and level of free convection (LFC). This - function uses the RIP [Read/Interpolate/plot] code to calculate - potential energy (CAPE) and convective inhibition - (CIN) [J kg-1] only for the parcel with max theta-e - in the column (i.e. something akin to Colman's MCAPE). CAPE is defined as - the accumulated buoyant energy from the level of free convection (LFC) to - the equilibrium level (EL). CIN is defined as the accumulated negative - buoyant energy from the parcel starting point to the LFC. - - The cape_2d algorithm works by first finding the maximum theta-e height - level in the lowest 3000 m. A parcel with a depth of 500 m is then - calculated and centered over this maximum theta-e height level. The - parcel's moisture and temperature characteristics are calculated by - averaging over the depth of this 500 m parcel. This 'maximum' parcel + + This function calculates the maximum convective available potential + energy (MCAPE), maximum convective inhibition (MCIN), + lifted condensation level (LCL), and level of free convection (LFC). This + function uses the RIP [Read/Interpolate/plot] code to calculate + potential energy (CAPE) and convective inhibition + (CIN) [J kg-1] only for the parcel with max theta-e + in the column (i.e. something akin to Colman's MCAPE). CAPE is defined as + the accumulated buoyant energy from the level of free convection (LFC) to + the equilibrium level (EL). CIN is defined as the accumulated negative + buoyant energy from the parcel starting point to the LFC. + + The cape_2d algorithm works by first finding the maximum theta-e height + level in the lowest 3000 m. A parcel with a depth of 500 m is then + calculated and centered over this maximum theta-e height level. The + parcel's moisture and temperature characteristics are calculated by + averaging over the depth of this 500 m parcel. This 'maximum' parcel is then used to compute MCAPE, MCIN, LCL and LFC. - - The leftmost dimension of the returned array represents four different + + The leftmost dimension of the returned array represents four different quantities: - + - return_val[0,...] will contain MCAPE [J kg-1] - return_val[1,...] will contain MCIN [J kg-1] - return_val[2,...] will contain LCL [m] - return_val[3,...] will contain LFC [m] - - This function also supports computing MCAPE along a single vertical + + This function also supports computing MCAPE along a single vertical column. In this mode, the *pres_hpa*, *tkel*, *qv* and *height* arguments - must be one-dimensional vertical columns, and the *terrain* and - *psfc_hpa* arguments must be scalar values + must be one-dimensional vertical columns, and the *terrain* and + *psfc_hpa* arguments must be scalar values (:obj:`float`, :class:`numpy.float32` or :class:`numpy.float64`). - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - pres_hpa (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [hPa] with at - least three dimensions. The rightmost dimensions can be + + Args: + + pres_hpa (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [hPa] with at + least three dimensions. The rightmost dimensions can be top_bottom x south_north x west_east or bottom_top x south_north x west_east. - When operating on only a single column of values, the vertical - column can be bottom_top or top_bottom. In this case, *terrain* + When operating on only a single column of values, the vertical + column can be bottom_top or top_bottom. In this case, *terrain* and *psfc_hpa* must be scalars. - + Note: - + The units for *pres_hpa* are [hPa]. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature in [K] with same dimensionality as *pres_hpa*. - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor mixing ratio in [kg/kg] with the same dimensionality as *pres_hpa*. - - height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - Geopotential height in [m] with the same dimensionality as + + height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + Geopotential height in [m] with the same dimensionality as *pres_hpa*. - - terrain (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - Terrain height in [m]. This is at least a two-dimensional array - with the same dimensionality as *pres_hpa*, excluding the vertical - (bottom_top/top_bottom) dimension. When operating on a single - vertical column, this argument must be a scalar (:obj:`float`, + + terrain (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + Terrain height in [m]. This is at least a two-dimensional array + with the same dimensionality as *pres_hpa*, excluding the vertical + (bottom_top/top_bottom) dimension. When operating on a single + vertical column, this argument must be a scalar (:obj:`float`, :class:`numpy.float32`, or :class:`numpy.float64`). - - psfc_hpa (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - The surface pressure in [hPa]. This is at least a two-dimensional - array with the same dimensionality as *pres_hpa*, excluding the - vertical (bottom_top/top_bottom) dimension. When operating on a - singlevertical column, this argument must be a scalar + + psfc_hpa (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + The surface pressure in [hPa]. This is at least a two-dimensional + array with the same dimensionality as *pres_hpa*, excluding the + vertical (bottom_top/top_bottom) dimension. When operating on a + singlevertical column, this argument must be a scalar (:obj:`float`, :class:`numpy.float32`, or :class:`numpy.float64`). - + Note: - + The units for *psfc_hpa* are [hPa]. - - ter_follow (:obj:`bool`): A boolean that should be set to True if the - data uses terrain following coordinates (WRF data). Set to + + ter_follow (:obj:`bool`): A boolean that should be set to True if the + data uses terrain following coordinates (WRF data). Set to False for pressure level data. - - missing (:obj:`float`, optional): The fill value to use for the + + missing (:obj:`float`, optional): The fill value to use for the output. Default is :data:`wrf.default_fill(numpy.float64)`. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - cape, cin, lcl, and lfc values as an array whose - leftmost dimension is 4 (0=CAPE, 1=CIN, 2=LCL, 3=LFC) . If xarray is - enabled and the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + cape, cin, lcl, and lfc values as an array whose + leftmost dimension is 4 (0=CAPE, 1=CIN, 2=LCL, 3=LFC) . If xarray is + enabled and the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.cape_3d` - + """ - + if isinstance(ter_follow, bool): ter_follow = 1 if ter_follow else 0 - + i3dflag = 0 - cape_cin = _cape(pres_hpa, tkel, qv, height, terrain, psfc_hpa, + cape_cin = _cape(pres_hpa, tkel, qv, height, terrain, psfc_hpa, missing, i3dflag, ter_follow) - + left_dims = cape_cin.shape[1:-3] right_dims = cape_cin.shape[-2:] - + resdim = (4,) + left_dims + right_dims - + # Make a new output array for the result result = np.zeros(resdim, cape_cin.dtype) - - # Cape 2D output is not flipped in the vertical, so index from the + + # Cape 2D output is not flipped in the vertical, so index from the # end - result[0,...,:,:] = cape_cin[0,...,-1,:,:] - result[1,...,:,:] = cape_cin[1,...,-1,:,:] - result[2,...,:,:] = cape_cin[1,...,-2,:,:] - result[3,...,:,:] = cape_cin[1,...,-3,:,:] - + result[0, ..., :, :] = cape_cin[0, ..., -1, :, :] + result[1, ..., :, :] = cape_cin[1, ..., -1, :, :] + result[2, ..., :, :] = cape_cin[1, ..., -2, :, :] + result[3, ..., :, :] = cape_cin[1, ..., -3, :, :] + return ma.masked_values(result, missing) @set_cape_alg_metadata(is2d=False, copyarg="pres_hpa") -def cape_3d(pres_hpa, tkel, qv, height, terrain, psfc_hpa, ter_follow, +def cape_3d(pres_hpa, tkel, qv, height, terrain, psfc_hpa, ter_follow, missing=default_fill(np.float64), meta=True): """Return the three-dimensional CAPE and CIN. - - This function calculates the maximum convective available potential - energy (CAPE) and maximum convective inhibition (CIN). This - function uses the RIP [Read/Interpolate/plot] code to calculate - potential energy (CAPE) and convective inhibition - (CIN) [J kg-1] for every grid point in the entire 3D domain + + This function calculates the maximum convective available potential + energy (CAPE) and maximum convective inhibition (CIN). This + function uses the RIP [Read/Interpolate/plot] code to calculate + potential energy (CAPE) and convective inhibition + (CIN) [J kg-1] for every grid point in the entire 3D domain (treating each grid point as a parcel). - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain CAPE [J kg-1] - return_val[1,...] will contain CIN [J kg-1] - - This function also supports computing CAPE along a single vertical + + This function also supports computing CAPE along a single vertical column. In this mode, the *pres_hpa*, *tkel*, *qv* and *height* arguments - must be one-dimensional vertical columns, and the *terrain* and - *psfc_hpa* arguments must be scalar values + must be one-dimensional vertical columns, and the *terrain* and + *psfc_hpa* arguments must be scalar values (:obj:`float`, :class:`numpy.float32` or :class:`numpy.float64`). - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - pres_hpa (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [hPa] with at - least three dimensions when operating on a grid of values. The - rightmost dimensions can be top_bottom x south_north x west_east - or bottom_top x south_north x west_east. - When operating on only a single column of values, the vertical - column can be bottom_top or top_bottom. In this case, *terrain* + + Args: + + pres_hpa (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [hPa] with at + least three dimensions when operating on a grid of values. The + rightmost dimensions can be top_bottom x south_north x west_east + or bottom_top x south_north x west_east. + When operating on only a single column of values, the vertical + column can be bottom_top or top_bottom. In this case, *terrain* and *psfc_hpa* must be scalars. - + Note: - + The units for *pres_hpa* are [hPa]. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature in [K] with same dimensionality as *pres_hpa*. - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor mixing ratio in [kg/kg] with the same dimensionality as *pres_hpa*. - - height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - Geopotential height in [m] with the same dimensionality as + + height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + Geopotential height in [m] with the same dimensionality as *pres_hpa*. - + terrain (:class:`xarray.DataArray`, :class:`numpy.ndarray`, \ - or a scalar): Terrain height in [m]. When operating on a grid of - values, this argument is at least a two-dimensional array - with the same dimensionality as *pres_hpa*, excluding the vertical - (bottom_top/top_bottom) dimension. When operating on a single - vertical column, this argument must be a scalar (:obj:`float`, + or a scalar): Terrain height in [m]. When operating on a grid of + values, this argument is at least a two-dimensional array + with the same dimensionality as *pres_hpa*, excluding the vertical + (bottom_top/top_bottom) dimension. When operating on a single + vertical column, this argument must be a scalar (:obj:`float`, :class:`numpy.float32`, or :class:`numpy.float64`). - + psfc_hpa (:class:`xarray.DataArray`, :class:`numpy.ndarray`, \ - or a scalar): Surface pressure in [hPa]. When operating on a - grid of values, this argument is at least a two-dimensional array - with the same dimensionality as *pres_hpa*, excluding the vertical - (bottom_top/top_bottom) dimension. When operating on a single - vertical column, this argument must be a scalar (:obj:`float`, + or a scalar): Surface pressure in [hPa]. When operating on a + grid of values, this argument is at least a two-dimensional array + with the same dimensionality as *pres_hpa*, excluding the vertical + (bottom_top/top_bottom) dimension. When operating on a single + vertical column, this argument must be a scalar (:obj:`float`, :class:`numpy.float32`, or :class:`numpy.float64`). - + Note: - + The units for *psfc_hpa* are [hPa]. - - ter_follow (:obj:`bool`): A boolean that should be set to True if the - data uses terrain following coordinates (WRF data). Set to + + ter_follow (:obj:`bool`): A boolean that should be set to True if the + data uses terrain following coordinates (WRF data). Set to False for pressure level data. - - missing (:obj:`float`, optional): The fill value to use for the + + missing (:obj:`float`, optional): The fill value to use for the output. Default is :data:`wrf.default_fill(numpy.float64)`. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - CAPE and CIN as an array whose - leftmost dimension is 2 (0=CAPE, 1=CIN). If xarray is - enabled and the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + CAPE and CIN as an array whose + leftmost dimension is 2 (0=CAPE, 1=CIN). If xarray is + enabled and the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.cape_2d` - + """ - + if isinstance(ter_follow, bool): ter_follow = 1 if ter_follow else 0 - + i3dflag = 1 - cape_cin = _cape(pres_hpa, tkel, qv, height, terrain, psfc_hpa, + cape_cin = _cape(pres_hpa, tkel, qv, height, terrain, psfc_hpa, missing, i3dflag, ter_follow) - + return ma.masked_values(cape_cin, missing) @@ -1003,296 +1004,295 @@ def cape_3d(pres_hpa, tkel, qv, height, terrain, psfc_hpa, ter_follow, def cloudfrac(vert, relh, vert_inc_w_height, low_thresh, mid_thresh, high_thresh, missing=default_fill(np.float64), meta=True): """Return the cloud fraction. - - The leftmost dimension of the returned array represents three different + + The leftmost dimension of the returned array represents three different quantities: - + - return_val[0,...] will contain LOW level cloud fraction - return_val[1,...] will contain MID level cloud fraction - return_val[2,...] will contain HIGH level cloud fraction - - The *low_thresh*, *mid_thresh*, and *high_threshold* paramters specify the + + The *low_thresh*, *mid_thresh*, and *high_threshold* paramters specify the low, mid, and high cloud levels in the same units as *vert*. - - In mountainous regions, there is a possibility - that the lowest WRF level will be higher than the low_cloud or mid_cloud - threshold. When this happens, a fill value will be used in the output at + + In mountainous regions, there is a possibility + that the lowest WRF level will be higher than the low_cloud or mid_cloud + threshold. When this happens, a fill value will be used in the output at that location. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - vert (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The - vertical coordinate variable (usually pressure or height) with the + + Args: + + vert (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The + vertical coordinate variable (usually pressure or height) with the rightmost dimensions as bottom_top x south_north x west_east - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - - relh (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Relative + + relh (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Relative humidity with the same dimensionality as *vert* - - vert_inc_w_height (:obj:`int`): Set to 1 if the vertical coordinate - values increase with height (height values). Set to 0 if the + + vert_inc_w_height (:obj:`int`): Set to 1 if the vertical coordinate + values increase with height (height values). Set to 0 if the vertical coordinate values decrease with height (pressure values). - - low_thresh (:obj:`float`): The bottom vertical threshold for what is + + low_thresh (:obj:`float`): The bottom vertical threshold for what is considered a low cloud. - - mid_thresh (:obj:`float`): The bottom vertical threshold for what is + + mid_thresh (:obj:`float`): The bottom vertical threshold for what is considered a mid level cloud. - - high_thresh (:obj:`float`): The bottom vertical threshold for what is + + high_thresh (:obj:`float`): The bottom vertical threshold for what is considered a high cloud. - - missing (:obj:`float:`, optional): The fill value to use for areas - where the surface is higher than the cloud threshold level - (e.g. mountains). Default is + + missing (:obj:`float:`, optional): The fill value to use for areas + where the surface is higher than the cloud threshold level + (e.g. mountains). Default is :data:`wrf.default_fill(numpy.float64)`. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - cloud fraction array whose leftmost dimension is 3 (LOW=0, MID=1, - HIGH=2). If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + cloud fraction array whose leftmost dimension is 3 (LOW=0, MID=1, + HIGH=2). If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.rh` - + """ - cfrac = _cloudfrac(vert, relh, vert_inc_w_height, low_thresh, mid_thresh, - high_thresh, missing) - + cfrac = _cloudfrac(vert, relh, vert_inc_w_height, low_thresh, mid_thresh, + high_thresh, missing) + return ma.masked_values(cfrac, missing) -@set_alg_metadata(2, "pres_hpa", refvarndims=3, +@set_alg_metadata(2, "pres_hpa", refvarndims=3, description="cloud top temperature") @convert_units("temp", "c") -def ctt(pres_hpa, tkel, qv, qcld, height, terrain, qice=None, - fill_nocloud=False, missing=default_fill(np.float64), +def ctt(pres_hpa, tkel, qv, qcld, height, terrain, qice=None, + fill_nocloud=False, missing=default_fill(np.float64), opt_thresh=1.0, meta=True, units="degC"): """Return the cloud top temperature. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - pres_hpa (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [hPa], with the + + Args: + + pres_hpa (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [hPa], with the rightmost dimensions as bottom_top x south_north x west_east - + Note: - + The units for *psfc_hpa* are [hPa]. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature in [K] with same dimensionality as *pres_hpa*. - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor mixing ratio in [kg/kg] with the same dimensionality as *pres_hpa*. - - qcld (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Cloud water - vapor mixing ratio in [kg/kg] with the same dimensionality as + + qcld (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Cloud water + vapor mixing ratio in [kg/kg] with the same dimensionality as *pres_hpa*. - - height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - Geopotential height in [m] with the same dimensionality as + + height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + Geopotential height in [m] with the same dimensionality as *pres_hpa*. - - terrain (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - Terrain height in [m]. This is at least a two-dimensional array - with the same dimensionality as *pres_hpa*, excluding the vertical + + terrain (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + Terrain height in [m]. This is at least a two-dimensional array + with the same dimensionality as *pres_hpa*, excluding the vertical (bottom_top/top_bottom) dimension. - - qice (:class:`xarray.DataArray` or :class:`numpy.ndarray`, optional): - Ice mixing ratio in [kg/kg] with the same dimensionality as + + qice (:class:`xarray.DataArray` or :class:`numpy.ndarray`, optional): + Ice mixing ratio in [kg/kg] with the same dimensionality as *pres_hpa*. - - fill_nocloud (:obj:`bool`, optional): Set to True to use fill values in - regions where clouds are not detected (optical depth less than 1). - Otherwise, the output will contain the surface temperature for + + fill_nocloud (:obj:`bool`, optional): Set to True to use fill values in + regions where clouds are not detected (optical depth less than 1). + Otherwise, the output will contain the surface temperature for areas without clouds. Default is False. - - missing (:obj:`float`, optional): The fill value to use for areas - where no clouds are detected. Only used if *fill_nocloud* is - True. Default is - :data:`wrf.default_fill(numpy.float64)`. - - opt_thresh (:obj:`float`, optional): The amount of optical - depth (integrated from top down) required to trigger a cloud top - temperature calculation. The cloud top temperature is calculated at - the vertical level where this threshold is met. Vertical columns - with less than this threshold will be treated as cloud free areas. - In general, the larger the value is for this - threshold, the lower the altitude will be for the cloud top - temperature calculation, and therefore higher cloud top - temperature values. Default is 1.0, which should be sufficient for + + missing (:obj:`float`, optional): The fill value to use for areas + where no clouds are detected. Only used if *fill_nocloud* is + True. Default is + :data:`wrf.default_fill(numpy.float64)`. + + opt_thresh (:obj:`float`, optional): The amount of optical + depth (integrated from top down) required to trigger a cloud top + temperature calculation. The cloud top temperature is calculated at + the vertical level where this threshold is met. Vertical columns + with less than this threshold will be treated as cloud free areas. + In general, the larger the value is for this + threshold, the lower the altitude will be for the cloud top + temperature calculation, and therefore higher cloud top + temperature values. Default is 1.0, which should be sufficient for most users. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'ctt'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'ctt'. Default is 'degC'. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - cloud top temperature. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + cloud top temperature. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.cloudfrac` - + """ - + # Qice and QCLD need to be in g/kg if qice is None: qice = np.zeros(qv.shape, qv.dtype) haveqci = 0 else: haveqci = 1 if qice.any() else 0 - + _fill_nocloud = 1 if fill_nocloud else 0 - + ctt = _ctt(pres_hpa, tkel, qice, qcld, qv, height, terrain, haveqci, - _fill_nocloud, missing, opt_thresh) - + _fill_nocloud, missing, opt_thresh) + return ma.masked_values(ctt, missing) - @set_alg_metadata(3, "pres", units="dBZ", description="radar reflectivity") -def dbz(pres, tkel, qv, qr, qs=None, qg=None, use_varint=False, +def dbz(pres, tkel, qv, qr, qs=None, qg=None, use_varint=False, use_liqskin=False, meta=True): """Return the simulated radar reflectivity. - - This function computes equivalent reflectivity factor [dBZ] at each - model grid point assuming spherical particles of constant density, - with exponential size distributions. This function is based on - "dbzcalc.f" in RIP. - - This is the raw computational algorithm and does not extract any variables + + This function computes equivalent reflectivity factor [dBZ] at each + model grid point assuming spherical particles of constant density, + with exponential size distributions. This function is based on + "dbzcalc.f" in RIP. + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [Pa], with the + + Args: + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [Pa], with the rightmost dimensions as bottom_top x south_north x west_east - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature in [K] with same dimensionality as *pres*. - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor mixing ratio in [kg/kg] with the same dimensionality as *pres*. - - qr (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Rain water - vapor mixing ratio in [kg/kg] with the same dimensionality as + + qr (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Rain water + vapor mixing ratio in [kg/kg] with the same dimensionality as *pres*. - - qs (:class:`xarray.DataArray` or :class:`numpy.ndarray`, optional): - Snow mixing ratio in [kg/kg] with the same dimensionality as + + qs (:class:`xarray.DataArray` or :class:`numpy.ndarray`, optional): + Snow mixing ratio in [kg/kg] with the same dimensionality as *pres*. - - qg (:class:`xarray.DataArray` or :class:`numpy.ndarray`, optional): - Graupel mixing ratio in [kg/kg] with the same dimensionality as + + qg (:class:`xarray.DataArray` or :class:`numpy.ndarray`, optional): + Graupel mixing ratio in [kg/kg] with the same dimensionality as *pres*. - - use_varint (:obj:`bool`, optional): When set to False, - the intercept parameters are assumed constant - (as in MM5's Reisner-2 bulk microphysical scheme). - When set to True, the variable intercept - parameters are used as in the more recent version of Reisner-2 - (based on Thompson, Rasmussen, and Manning, 2004, Monthly weather - Review, Vol. 132, No. 2, pp. 519-542.). - - use_liqskin (:obj:`bool`, optional): When set to True, frozen particles - that are at a temperature above freezing are assumed to scatter + + use_varint (:obj:`bool`, optional): When set to False, + the intercept parameters are assumed constant + (as in MM5's Reisner-2 bulk microphysical scheme). + When set to True, the variable intercept + parameters are used as in the more recent version of Reisner-2 + (based on Thompson, Rasmussen, and Manning, 2004, Monthly weather + Review, Vol. 132, No. 2, pp. 519-542.). + + use_liqskin (:obj:`bool`, optional): When set to True, frozen particles + that are at a temperature above freezing are assumed to scatter as a liquid particle. Set to False to disable. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - simulated radar reflectivity. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + simulated radar reflectivity. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar` - + """ - + if qs is None: qs = np.zeros(qv.shape, qv.dtype) - + if qg is None: qg = np.zeros(qv.shape, qv.dtype) - + sn0 = 1 if qs.any() else 0 ivarint = 1 if use_varint else 0 iliqskin = 1 if use_liqskin else 0 - + return _dbz(pres, tkel, qv, qr, qs, qg, sn0, ivarint, iliqskin) @@ -1300,174 +1300,174 @@ def dbz(pres, tkel, qv, qr, qs=None, qg=None, use_varint=False, description="storm relative helicity") def srhel(u, v, height, terrain, top=3000.0, lats=None, meta=True): """Return the storm relative helicity. - - This function calculates storm relative helicity from WRF ARW output. - SRH (Storm Relative Helicity) is a measure of the potential for cyclonic - updraft rotation in right-moving supercells, and is calculated for the - lowest 1-km and 3-km layers above ground level. There is no clear threshold - value for SRH when forecasting supercells, since the formation of - supercells appears to be related more strongly to the deeper layer - vertical shear. Larger values of 0-3 km SRH (greater than 250 m2 s-2) - and 0-1 km SRH (greater than 100 m2 s-2), however, do suggest an - increased threat of tornadoes with supercells. For SRH, larger values are - generally better, but there are no clear "boundaries" between non-tornadic + + This function calculates storm relative helicity from WRF ARW output. + SRH (Storm Relative Helicity) is a measure of the potential for cyclonic + updraft rotation in right-moving supercells, and is calculated for the + lowest 1-km and 3-km layers above ground level. There is no clear threshold + value for SRH when forecasting supercells, since the formation of + supercells appears to be related more strongly to the deeper layer + vertical shear. Larger values of 0-3 km SRH (greater than 250 m2 s-2) + and 0-1 km SRH (greater than 100 m2 s-2), however, do suggest an + increased threat of tornadoes with supercells. For SRH, larger values are + generally better, but there are no clear "boundaries" between non-tornadic and significant tornadic supercells. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - u (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The u - component of the wind that must have at least three dimensions. + + Args: + + u (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The u + component of the wind that must have at least three dimensions. The rightmost dimensions are bottom_top x south_north x west_east. - - v (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The v - component of the wind with the same dimensionality as *u*. - - height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - Geopotential height in [m] with the same dimensionality as + + v (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The v + component of the wind with the same dimensionality as *u*. + + height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + Geopotential height in [m] with the same dimensionality as *u*. - - terrain (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - Terrain height in [m]. This is at least a two-dimensional array - with the same dimensionality as *u*, excluding the bottom_top + + terrain (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + Terrain height in [m]. This is at least a two-dimensional array + with the same dimensionality as *u*, excluding the bottom_top dimension. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will - be used. - - top (:obj:`float`): The height of the layer below which helicity is + be used. + + top (:obj:`float`): The height of the layer below which helicity is calculated (meters above ground level). - - lats (:class:`xarray.DataArray` or :class:`numpy.ndarray`, optional): - Array of latitudes. This is required if any (or all) of your - domain is in the southern hemisphere. If not provided, the + + lats (:class:`xarray.DataArray` or :class:`numpy.ndarray`, optional): + Array of latitudes. This is required if any (or all) of your + domain is in the southern hemisphere. If not provided, the northern hemisphere is assumed. Default is None. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - storm relative helicity. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + storm relative helicity. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.udhel` - + """ - + # u, v get swapped in vertical - _u = np.ascontiguousarray(u[...,::-1,:,:]) - _v = np.ascontiguousarray(v[...,::-1,:,:]) - _height = np.ascontiguousarray(height[...,::-1,:,:]) - + _u = np.ascontiguousarray(u[..., ::-1, :, :]) + _v = np.ascontiguousarray(v[..., ::-1, :, :]) + _height = np.ascontiguousarray(height[..., ::-1, :, :]) + if lats is None: _lats = np.ones_like(terrain) else: _lats = lats - + return _srhel(_u, _v, _height, terrain, _lats, top) @set_alg_metadata(2, "u", refvarndims=3, units="m2 s-2", description="updraft helicity") -def udhel(zstag, mapfct, u, v, wstag, dx, dy, bottom=2000.0, top=5000.0, +def udhel(zstag, mapfct, u, v, wstag, dx, dy, bottom=2000.0, top=5000.0, meta=True): """Return the updraft helicity. - - This function calculates updraft helicity to detect - rotating updrafts. The formula follows Kain et al., 2008, Wea. and - Forecasting, 931-952, but this version has controls for the limits of - integration, *bottom* to *top*, in m AGL. Kain et al used 2000 to 5000 m. - The expected range is 25 to 250 m-2/s-2. Keith Brewster, CAPS/Univ. of + + This function calculates updraft helicity to detect + rotating updrafts. The formula follows Kain et al., 2008, Wea. and + Forecasting, 931-952, but this version has controls for the limits of + integration, *bottom* to *top*, in m AGL. Kain et al used 2000 to 5000 m. + The expected range is 25 to 250 m-2/s-2. Keith Brewster, CAPS/Univ. of Oklahoma ; March, 2010 - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - zstag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + + Args: + + zstag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Geopotential height in [m] that is at least three dimensions with - a staggered vertical dimension. The rightmost dimensions are + a staggered vertical dimension. The rightmost dimensions are bottom_top_stag x south_north x west_east. - - mapfct (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map - scale factor on the mass grid. An array of at least - two dimensions, whose rightmost two dimensions must be - south_north x west_east. If this array is more than two dimensions, + + mapfct (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map + scale factor on the mass grid. An array of at least + two dimensions, whose rightmost two dimensions must be + south_north x west_east. If this array is more than two dimensions, they must be the same as *zstag*'s leftmost dimensions. - - u (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The u - component of the wind [m s-1] whose rightmost three dimensions - must be bottom_top x south_north x west_east. The leftmost + + u (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The u + component of the wind [m s-1] whose rightmost three dimensions + must be bottom_top x south_north x west_east. The leftmost dimensions must be the same as zp's leftmost dimensions. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will - be used. - - v (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The v - component of the wind [m s-1] whose rightmost three dimensions - must be bottom_top x south_north x west_east. The leftmost - dimensions must be the same as *zstag*'s leftmost dimensions. - + be used. + + v (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The v + component of the wind [m s-1] whose rightmost three dimensions + must be bottom_top x south_north x west_east. The leftmost + dimensions must be the same as *zstag*'s leftmost dimensions. + wstag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The z - component of the wind [m s-1] with the same dimensionality as + component of the wind [m s-1] with the same dimensionality as *zstag*. - + dx (:obj:`float`): The distance between x grid points. - + dy (:obj:`float`): The distance between y grid points. - - bottom (:obj:`float`, optional): The bottom limit of integration. + + bottom (:obj:`float`, optional): The bottom limit of integration. Default is 2000.0. - - top (:obj:`float`, optional): The upper limit of integration. + + top (:obj:`float`, optional): The upper limit of integration. Default is 5000.0. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - updraft helicity. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + updraft helicity. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.srhel` - + """ return _udhel(zstag, mapfct, u, v, wstag, dx, dy, bottom, top) @@ -1478,91 +1478,91 @@ def udhel(zstag, mapfct, u, v, wstag, dx, dy, bottom=2000.0, top=5000.0, description="absolute vorticity") def avo(ustag, vstag, msfu, msfv, msfm, cor, dx, dy, meta=True): """Return the absolute vorticity. - - This function returns absolute vorticity [10-5 s-1], which is the sum of - the relative vorticity at each grid point and the Coriolis parameter + + This function returns absolute vorticity [10-5 s-1], which is the sum of + the relative vorticity at each grid point and the Coriolis parameter at the latitude. - This is the raw computational algorithm and does not extract any variables + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - ustag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - The u component of the wind in [m s-1] that is at least three - dimensions with a staggered west_east dimension. The rightmost + + Args: + + ustag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + The u component of the wind in [m s-1] that is at least three + dimensions with a staggered west_east dimension. The rightmost dimensions are bottom_top x south_north x west_east_stag. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will - be used. - - vstag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - The v component of the wind in [m s-1] that is at least three - dimensions with a staggered south_north dimension. The rightmost + be used. + + vstag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + The v component of the wind in [m s-1] that is at least three + dimensions with a staggered south_north dimension. The rightmost dimensions are bottom_top x south_north_stag x west_east. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will - be used. - - msfu (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map - scale factor on the u-grid that is at least - two dimensions, whose rightmost two dimensions must be - the same as *ustag*. If this array contains more than two - dimensions, they must be the same as *ustag* and *vstag*'s leftmost + be used. + + msfu (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map + scale factor on the u-grid that is at least + two dimensions, whose rightmost two dimensions must be + the same as *ustag*. If this array contains more than two + dimensions, they must be the same as *ustag* and *vstag*'s leftmost dimensions. - - msfv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map - scale factor on the v-grid that is at least - two dimensions, whose rightmost two dimensions must be - the same as *vstag*. If this array contains more than two - dimensions, they must be the same as *ustag* and *vstag*'s leftmost + + msfv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map + scale factor on the v-grid that is at least + two dimensions, whose rightmost two dimensions must be + the same as *vstag*. If this array contains more than two + dimensions, they must be the same as *ustag* and *vstag*'s leftmost dimensions. - - msfm (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map - scale factor on the mass grid that is at least - two dimensions, whose rightmost two dimensions must be - south_north x west_east. If this array contains more than two - dimensions, they must be the same as *ustag* and *vstag*'s leftmost + + msfm (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map + scale factor on the mass grid that is at least + two dimensions, whose rightmost two dimensions must be + south_north x west_east. If this array contains more than two + dimensions, they must be the same as *ustag* and *vstag*'s leftmost dimensions. - - cor (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The Coriolis - sine latitude array that is at least + + cor (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The Coriolis + sine latitude array that is at least two dimensions, whose dimensions must be the same as *msfm*. - + dx (:obj:`float`): The distance between x grid points. - + dy (:obj:`float`): The distance between y grid points. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - absolute vorticity. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + absolute vorticity. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.pvo` - + """ return _avo(ustag, vstag, msfu, msfv, msfm, cor, dx, dy) @@ -1571,92 +1571,92 @@ def avo(ustag, vstag, msfu, msfv, msfm, cor, dx, dy, meta=True): description="potential vorticity") def pvo(ustag, vstag, theta, pres, msfu, msfv, msfm, cor, dx, dy, meta=True): """Return the potential vorticity. - + This function calculates the potential vorticity [PVU] at each grid point. - This is the raw computational algorithm and does not extract any variables + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - ustag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - The u component of the wind in [m s-1] that is at least three - dimensions with a staggered west_east dimension. The rightmost + + Args: + + ustag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + The u component of the wind in [m s-1] that is at least three + dimensions with a staggered west_east dimension. The rightmost dimensions are bottom_top x south_north x west_east_stag. - - - vstag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - The v component of the wind in [m s-1] that is at least three - dimensions with a staggered south_north dimension. The rightmost + + + vstag (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + The v component of the wind in [m s-1] that is at least three + dimensions with a staggered south_north dimension. The rightmost dimensions are bottom_top x south_north_stag x west_east. - - theta (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The - potential temperature field [K] whose rightmost dimensions are + + theta (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The + potential temperature field [K] whose rightmost dimensions are bottom_top x south_north x west_east and whose leftmost dimensions are the same as *ustag*. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [Pa], with the + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [Pa], with the same dimensions as *theta*. - - msfu (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map - scale factor on the u-grid that is at least - two dimensions, whose rightmost two dimensions must be - the same as *ustag*. If this array contains more than two - dimensions, they must be the same as *ustag* and *vstag*'s leftmost + + msfu (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map + scale factor on the u-grid that is at least + two dimensions, whose rightmost two dimensions must be + the same as *ustag*. If this array contains more than two + dimensions, they must be the same as *ustag* and *vstag*'s leftmost dimensions. - - msfv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map - scale factor on the v-grid that is at least - two dimensions, whose rightmost two dimensions must be - the same as *vstag*. If this array contains more than two - dimensions, they must be the same as *ustag* and *vstag*'s leftmost + + msfv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map + scale factor on the v-grid that is at least + two dimensions, whose rightmost two dimensions must be + the same as *vstag*. If this array contains more than two + dimensions, they must be the same as *ustag* and *vstag*'s leftmost dimensions. - - msfm (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map - scale factor on the mass grid that is at least - two dimensions, whose rightmost two dimensions must be - south_north x west_east. If this array contains more than two - dimensions, they must be the same as *ustag* and *vstag*'s leftmost + + msfm (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The map + scale factor on the mass grid that is at least + two dimensions, whose rightmost two dimensions must be + south_north x west_east. If this array contains more than two + dimensions, they must be the same as *ustag* and *vstag*'s leftmost dimensions. - - cor (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The Coriolis - sine latitude array that is at least + + cor (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The Coriolis + sine latitude array that is at least two dimensions, whose dimensions must be the same as *msfm*. - + dx (:obj:`float`): The distance between x grid points. - + dy (:obj:`float`): The distance between y grid points. - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - potential vorticity. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + potential vorticity. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`wrf.avo` - + """ return _pvo(ustag, vstag, theta, pres, msfu, msfv, msfm, cor, dx, dy) @@ -1666,59 +1666,59 @@ def pvo(ustag, vstag, theta, pres, msfu, msfv, msfm, cor, dx, dy, meta=True): @convert_units("temp", "k") def eth(qv, tkel, pres, meta=True, units="K"): """Return the equivalent potential temperature. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor - mixing ratio in [kg/kg] that is at least three dimensions, with + + Args: + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + mixing ratio in [kg/kg] that is at least three dimensions, with the rightmost dimensions of bottom_top x south_north x west_east. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature in [K] with same dimensionality as *qv*. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [Pa] with the - same dimensionality as *qv*. - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [Pa] with the + same dimensionality as *qv*. + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'eth'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'eth'. Default is 'K'. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - equivalent potential temperature. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + equivalent potential temperature. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - - :meth:`wrf.getvar`, :meth:`wrf.temp`, :meth:`wrf.wetbulb`, + + :meth:`wrf.getvar`, :meth:`wrf.temp`, :meth:`wrf.wetbulb`, :meth:`tvirtual` - + """ - + return _eth(qv, tkel, pres) @@ -1727,57 +1727,57 @@ def eth(qv, tkel, pres, meta=True, units="K"): @convert_units("temp", "k") def wetbulb(pres, tkel, qv, meta=True, units="K"): """Return the wetbulb temperature. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [Pa], with the + + Args: + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [Pa], with the rightmost dimensions as bottom_top x south_north x west_east - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature in [K] with same dimensionality as *pres*. - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor - mixing ratio in [kg/kg] with the same dimensionality as + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + mixing ratio in [kg/kg] with the same dimensionality as *pres* - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'twb'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'twb'. Default is 'K'. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - wetbulb temperature. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + wetbulb temperature. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - - :meth:`wrf.getvar`, :meth:`wrf.temp`, :meth:`wrf.eth`, + + :meth:`wrf.getvar`, :meth:`wrf.temp`, :meth:`wrf.eth`, :meth:`tvirtual` - + """ return _wetbulb(pres, tkel, qv) @@ -1787,54 +1787,54 @@ def wetbulb(pres, tkel, qv, meta=True, units="K"): @convert_units("temp", "k") def tvirtual(tkel, qv, meta=True, units="K"): """Return the virtual temperature. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - + + Args: + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature - in [K] with the rightmost dimensions as bottom_top x south_north + in [K] with the rightmost dimensions as bottom_top x south_north x west_east. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor - mixing ratio in [kg/kg] with the same dimensionality as + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + mixing ratio in [kg/kg] with the same dimensionality as *tkel* - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'tv'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'tv'. Default is 'K'. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - virtual temperature. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + virtual temperature. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - - :meth:`wrf.getvar`, :meth:`wrf.temp`, :meth:`wrf.eth`, + + :meth:`wrf.getvar`, :meth:`wrf.temp`, :meth:`wrf.eth`, :meth:`wetbulb` - + """ return _tv(tkel, qv) @@ -1843,57 +1843,57 @@ def tvirtual(tkel, qv, meta=True, units="K"): description="omega") def omega(qv, tkel, w, pres, meta=True): """Return omega. - + This function calculates omega (dp/dt) [Pa s-1]. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor - mixing ratio in [kg/kg] with the rightmost dimensions as + + Args: + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + mixing ratio in [kg/kg] with the rightmost dimensions as bottom_top x south_north x west_east. - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature in [K] with the same dimensionality as *qv*. - - w (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The vertical + + w (:class:`xarray.DataArray` or :class:`numpy.ndarray`): The vertical velocity [m s-1] with the same dimensionality as *qv*. - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [Pa] with the - same dimensionality as *qv*. - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [Pa] with the + same dimensionality as *qv*. + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: Omega. - If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: Omega. + If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar`, :meth:`uvmet` - + """ return _omega(qv, tkel, w, pres) @@ -1902,59 +1902,56 @@ def omega(qv, tkel, w, pres, meta=True): description="precipitable water") def pw(pres, tkel, qv, height, meta=True): """Return the precipitable water. - - This is the raw computational algorithm and does not extract any variables + + This is the raw computational algorithm and does not extract any variables from WRF output files. Use :meth:`wrf.getvar` to both extract and compute diagnostic variables. - - Args: - - pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full - pressure (perturbation + base state pressure) in [Pa], with the + + Args: + + pres (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Full + pressure (perturbation + base state pressure) in [Pa], with the rightmost dimensions as bottom_top x south_north x west_east - + Note: - - This variable must be - supplied as a :class:`xarray.DataArray` in order to copy the + + This variable must be + supplied as a :class:`xarray.DataArray` in order to copy the dimension names to the output. Otherwise, default names will be used. - + tkel (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Temperature in [K] with the same dimensionality as *pres*. - - qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor + + qv (:class:`xarray.DataArray` or :class:`numpy.ndarray`): Water vapor mixing ratio in [kg/kg] with the same dimensionality as *pres* - - height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): - Geopotential height in [m] with the same dimensionality as + + height (:class:`xarray.DataArray` or :class:`numpy.ndarray`): + Geopotential height in [m] with the same dimensionality as *pres*. - - meta (:obj:`bool`): Set to False to disable metadata and return - :class:`numpy.ndarray` instead of + + meta (:obj:`bool`): Set to False to disable metadata and return + :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + Warning: - - The input arrays must not contain any missing/fill values or + + The input arrays must not contain any missing/fill values or :data:`numpy.nan` values. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The precipitable - water [kg m-2]. If xarray is enabled and - the *meta* parameter is True, then the result will be an - :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The precipitable + water [kg m-2]. If xarray is enabled and + the *meta* parameter is True, then the result will be an + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + See Also: - + :meth:`wrf.getvar` - + """ tv = _tv(tkel, qv) - - return _pw(pres, tv, qv, height) - - + return _pw(pres, tv, qv, height) diff --git a/src/wrf/config.py b/src/wrf/config.py index 513cf1f..fa20201 100644 --- a/src/wrf/config.py +++ b/src/wrf/config.py @@ -3,42 +3,43 @@ from __future__ import (absolute_import, division, print_function) from threading import local import wrapt -from ._wrffortran import (fomp_enabled, fomp_set_num_threads, +from ._wrffortran import (fomp_enabled, fomp_set_num_threads, fomp_set_schedule, fomp_set_dynamic, omp_constants) _local_config = local() + def _init_local(): global _local_config - + _local_config.xarray_enabled = True _local_config.cartopy_enabled = True _local_config.basemap_enabled = True _local_config.pyngl_enabled = True _local_config.cache_size = 20 _local_config.initialized = True - + try: from xarray import DataArray except ImportError: _local_config.xarray_enabled = False - + try: from cartopy import crs except ImportError: _local_config.cartopy_enabled = False - + try: from mpl_toolkits.basemap import Basemap except ImportError: _local_config.basemap_enabled = False - + try: from Ngl import Resources except ImportError: _local_config.pyngl_enabled = False - + # Initialize the main thread's configuration _init_local() @@ -55,21 +56,21 @@ def init_local(): _init_local() else: if not init: - _init_local() - + _init_local() + return wrapped(*args, **kwargs) - + return func_wrapper @init_local() def xarray_enabled(): """Return True if xarray is installed and enabled. - + Returns: - + :obj:`bool`: True if xarray is installed and enabled. - + """ global _local_config return _local_config.xarray_enabled @@ -80,23 +81,23 @@ def disable_xarray(): """Disable xarray.""" global _local_config _local_config.xarray_enabled = False - + @init_local() def enable_xarray(): """Enable xarray.""" global _local_config _local_config.xarray_enabled = True - + @init_local() def cartopy_enabled(): """Return True if cartopy is installed and enabled. - + Returns: - + :obj:`bool`: True if cartopy is installed and enabled. - + """ global _local_config return _local_config.cartopy_enabled @@ -107,23 +108,23 @@ def enable_cartopy(): """Enable cartopy.""" global _local_config _local_config.cartopy_enabled = True - + @init_local() def disable_cartopy(): """Disable cartopy.""" global _local_config _local_config.cartopy_enabled = True - + @init_local() def basemap_enabled(): """Return True if basemap is installed and enabled. - + Returns: - + :obj:`bool`: True if basemap is installed and enabled. - + """ global _local_config return _local_config.basemap_enabled @@ -134,7 +135,7 @@ def enable_basemap(): """Enable basemap.""" global _local_config _local_config.basemap_enabled = True - + @init_local() def disable_basemap(): @@ -146,11 +147,11 @@ def disable_basemap(): @init_local() def pyngl_enabled(): """Return True if pyngl is installed and enabled. - + Returns: - + :obj:`bool`: True if pyngl is installed and enabled. - + """ global _local_config return _local_config.pyngl_enabled @@ -161,63 +162,64 @@ def enable_pyngl(): """Enable pyngl.""" global _local_config _local_config.pyngl_enabled = True - -@init_local() + +@init_local() def disable_pyngl(): """Disable pyngl.""" global _local_config _local_config.pyngl_enabled = True - -@init_local() + +@init_local() def set_cache_size(size): """Set the maximum number of items that the threadlocal cache can retain. - + This cache is primarily used for coordinate variables. - + Args: - + size (:obj:`int`): The number of items to retain in the cache. - + Returns: - + None - + """ global _local_config _local_config.cache_size = size - -@init_local() + +@init_local() def get_cache_size(): - """Return the maximum number of items that the threadlocal cache can retain. - + """Return the maximum number of items that the threadlocal cache can + retain. + Returns: - + :obj:`int`: The maximum number of items the cache can retain. - + """ global _local_config return int(_local_config.cache_size) - - + + def omp_enabled(): """Return True if OpenMP is enabled. - + OpenMP is only enabled if compiled with OpenMP features. - + Returns: - + :obj:`bool`: True if OpenMP is enabled, otherwise False. - + """ - + return True if fomp_enabled() else False # Set OpenMP to use 1 thread, static scheduler, and no dynamic -# Note: Using the raw extension functions here to prevent possible +# Note: Using the raw extension functions here to prevent possible # circular import problems in the future. fomp_set_num_threads(1) fomp_set_schedule(omp_constants.fomp_sched_static, 0) diff --git a/src/wrf/constants.py b/src/wrf/constants.py index 11cdc6c..47821ef 100755 --- a/src/wrf/constants.py +++ b/src/wrf/constants.py @@ -10,10 +10,12 @@ from ._wrffortran import wrf_constants, omp_constants #: Indicates that all times should be used in a diagnostic routine. ALL_TIMES = None + class Constants(object): pass - -for key,val in viewitems(wrf_constants.__dict__): + + +for key, val in viewitems(wrf_constants.__dict__): setattr(Constants, key.upper(), np.asscalar(val)) OMP_SCHED_STATIC = omp_constants.fomp_sched_static @@ -35,7 +37,7 @@ class ConversionFactors(object): M_TO_DM = 1.0/10.0 M_TO_FT = 3.28084 M_TO_MILES = .000621371 - + class ProjectionTypes(object): ZERO = 0 @@ -44,21 +46,22 @@ class ProjectionTypes(object): MERCATOR = 3 LAT_LON = 6 -# Create the default fill mapping based on type. + +# Create the default fill mapping based on type. _DEFAULT_FILL_MAP = {None: Constants.DEFAULT_FILL, - np.dtype(np.bool_) : False, - np.dtype(np.intc) : Constants.DEFAULT_FILL_INT32, # Usually true - np.dtype(np.int8) : Constants.DEFAULT_FILL_INT8, - np.dtype(np.uint8) : 255, - np.dtype(np.int16) : Constants.DEFAULT_FILL_INT16, - np.dtype(np.uint16) : 65535, - np.dtype(np.int32) : Constants.DEFAULT_FILL_INT32, - np.dtype(np.uint32) : 4294967295, - np.dtype(np.int64) : Constants.DEFAULT_FILL_INT64, - np.dtype(np.uint64) : 18446744073709551614, - np.dtype(np.float_) : Constants.DEFAULT_FILL_DOUBLE, - np.dtype(np.float32) : Constants.DEFAULT_FILL_FLOAT, - np.dtype(np.float64) : Constants.DEFAULT_FILL_DOUBLE + np.dtype(np.bool_): False, + np.dtype(np.intc): Constants.DEFAULT_FILL_INT32, + np.dtype(np.int8): Constants.DEFAULT_FILL_INT8, + np.dtype(np.uint8): 255, + np.dtype(np.int16): Constants.DEFAULT_FILL_INT16, + np.dtype(np.uint16): 65535, + np.dtype(np.int32): Constants.DEFAULT_FILL_INT32, + np.dtype(np.uint32): 4294967295, + np.dtype(np.int64): Constants.DEFAULT_FILL_INT64, + np.dtype(np.uint64): 18446744073709551614, + np.dtype(np.float_): Constants.DEFAULT_FILL_DOUBLE, + np.dtype(np.float32): Constants.DEFAULT_FILL_FLOAT, + np.dtype(np.float64): Constants.DEFAULT_FILL_DOUBLE } if version_info >= (3, ): @@ -76,9 +79,3 @@ else: def default_fill(dtype=None): dt = np.dtype(dtype) if dtype is not None else None return _DEFAULT_FILL_MAP.get(dt, Constants.DEFAULT_FILL) - - - - - - \ No newline at end of file diff --git a/src/wrf/coordpair.py b/src/wrf/coordpair.py index 62000cc..3aed083 100644 --- a/src/wrf/coordpair.py +++ b/src/wrf/coordpair.py @@ -1,265 +1,254 @@ from __future__ import (absolute_import, division, print_function) from .py3compat import py2round - - + + def _binary_operator(operator): """Function wrapper for binary operators. - + Args: - + operator (method): The operator to wrap. - + Returns: - + method: An implementation for the *operator* type. - + """ def func(self, other): """Operator implementation. - - Operator action is performed across the same class attributes when + + Operator action is performed across the same class attributes when the *other* object is a :class:`CoordPair`. If the *other* object is - a scalar value, the operator action is performed across all + a scalar value, the operator action is performed across all attributes with the scalar value. - + Args: - - other (:class:`CoordPair` or scalar): A separate :class:`CoordPair` + + other (:class:`CoordPair` or scalar): A separate :class:`CoordPair` object or scalar value. - + Returns: - - :class:`CoordPair`: A new :class:`CoordPair` object that is the + + :class:`CoordPair`: A new :class:`CoordPair` object that is the result of the operator action. - + """ if isinstance(other, CoordPair): - args = [ - None if getattr(self, attr) is None or getattr(other, attr) is None - else getattr(getattr(self, attr), operator)(getattr(other, attr)) - for attr in ("x", "y", "lat", "lon")] + args = [None if getattr(self, attr) is None or + getattr(other, attr) is None else + getattr(getattr(self, attr), operator)(getattr(other, + attr)) + for attr in ("x", "y", "lat", "lon")] else: - args = [ - None if getattr(self, attr) is None - else getattr(getattr(self, attr), operator)(other) - for attr in ("x", "y", "lat", "lon")] - + args = [None if getattr(self, attr) is None + else getattr(getattr(self, attr), operator)(other) + for attr in ("x", "y", "lat", "lon")] + return CoordPair(*args) - + return func def _unary_operator(operator): """Function wrapper for unary operators. - + Args: - + operator (method): The operator to wrap. - + Returns: - + method: An implementation for the *operator* type. - + """ def func(self): """Operator implementation. - + Operator action is performed across all class attributes. - + Returns: - - :class:`CoordPair`: A new :class:`CoordPair` object that is the + + :class:`CoordPair`: A new :class:`CoordPair` object that is the result of the operator action. - + """ args = [None if getattr(self, attr) is None - else getattr(getattr(self, attr), operator)() + else getattr(getattr(self, attr), operator)() for attr in ("x", "y", "lat", "lon")] - + return CoordPair(*args) - + return func def _cmp_operator(operator): """Function wrapper for comparison operators. - + Args: - + operator (method): The operator to wrap. - + Returns: - + method: An implementation for the *operator* type. - + """ - + def func(self, other): """Operator implementation. - - Performs a comparison operation across all of the same class - attributes, and returns True if all these operations are True. - + + Performs a comparison operation across all of the same class + attributes, and returns True if all these operations are True. + Returns: - - :obj:`boot`: Returns True if all comparisons across class + + :obj:`boot`: Returns True if all comparisons across class attributes returns True, otherwise False. - + """ vals = [getattr(getattr(self, attr), operator)(getattr(other, attr)) - for attr in ("x", "y", "lat", "lon") + for attr in ("x", "y", "lat", "lon") if getattr(self, attr) is not None] - + return all(vals) - + return func - - + + class CoordPair(object): - """A class that stores (x, y) and/or (latitude, longitude) + """A class that stores (x, y) and/or (latitude, longitude) coordinate pairs. - - Most math operators are supplied. When the other operand is a - :class:`CoordPair`, the operation is performed with the same attribute. - When a math operation uses a scalar as the other operand, the - operation is applied across all attributes. - + + Most math operators are supplied. When the other operand is a + :class:`CoordPair`, the operation is performed with the same attribute. + When a math operation uses a scalar as the other operand, the + operation is applied across all attributes. + Attributes: - + x (:obj:`float`): The x-coordinate. y (:obj:`float`): The y-coordinate. lat (:obj:`float`): The latitude coordinate. lon (:obj:`float`): The longitude coordinate. - - + + """ def __init__(self, x=None, y=None, lat=None, lon=None): """Initialize a :class:`CoordPair` object. - + Args: - + x (:obj:`float`, optional): The x-coordinate. y (:obj:`float`, optional): The y-coordinate. lat (:obj:`float`, optional): The latitude coordinate. lon (:obj:`float`, optional): The longitude coordinate. - - + + """ self.x = x self.y = y self.lat = lat self.lon = lon - - + def __repr__(self): args = [] if self.x is not None: args.append("x={}".format(self.x)) args.append("y={}".format(self.y)) - + if self.lat is not None: args.append("lat={}".format(self.lat)) args.append("lon={}".format(self.lon)) - + argstr = ", ".join(args) - + return "{}({})".format(self.__class__.__name__, argstr) - - + def __str__(self): return self.__repr__() - - + def xy_str(self, fmt="{:.4f}, {:.4f}"): """Return a :obj:`str` for the (x,y) coordinate pair. - + Args: - + fmt (:obj:`str`): The format string. Default is '{:.4f}, {:.4f}' - + Returns: - + :obj:`str`: A string for the (x,y) coordinate pair - + """ if self.x is None or self.y is None: return None - + return fmt.format(self.x, self.y) - - + def latlon_str(self, fmt="{:.4f}, {:.4f}"): """Return a :obj:`str` for the (latitude, longitude) coordinate pair. - + Args: - + fmt (:obj:`str`): The format string. Default is '{:.4f}, {:.4f}' - + Returns: - + :obj:`str`: A string for the (latitude, longitude) coordinate pair - + """ if self.lat is None or self.lon is None: return None - + return fmt.format(self.lat, self.lon) - - + def __round__(self, ndigits=None): """Return a new :class:`CoordPair` object with all coordinate values rounded to the nearest integer. - + Args: - + ndigits (:obj:`int`): The number of digits. - + Returns: - + :class:`CoordPair`: A CoordPair object. - + """ args = [None if getattr(self, attr) is None - else py2round(getattr(self, attr), ndigits) + else py2round(getattr(self, attr), ndigits) for attr in ("x", "y", "lat", "lon")] - + return CoordPair(*args) - - + def __pow__(self, other, modulo=None): if isinstance(other, CoordPair): - args = [ - None if getattr(self, attr) is None or getattr(other, attr) is None - else getattr(getattr(self, attr), "__pow__")(getattr(other, attr), - modulo) - for attr in ("x", "y", "lat", "lon")] + args = [None if getattr(self, attr) is None or + getattr(other, attr) is None + else getattr(getattr(self, attr), "__pow__")( + getattr(other, attr), modulo) + for attr in ("x", "y", "lat", "lon")] else: - args = [ - None if getattr(self, attr) is None - else getattr(getattr(self, attr), "__pow__")(other, modulo) - for attr in ("x", "y", "lat", "lon")] - + args = [None if getattr(self, attr) is None + else getattr(getattr(self, attr), "__pow__")(other, modulo) + for attr in ("x", "y", "lat", "lon")] + return CoordPair(*args) - - + def __rpow__(self, other): return self.__pow__(other) - -for operator in ("__add__", "__divmod__", "__floordiv__", "__mod__", - "__mul__", "__sub__", "__truediv__", "__radd__", - "__rdivmod__", "__rsub__", "__rmul__", "__rtruediv__", + +for operator in ("__add__", "__divmod__", "__floordiv__", "__mod__", + "__mul__", "__sub__", "__truediv__", "__radd__", + "__rdivmod__", "__rsub__", "__rmul__", "__rtruediv__", "__rfloordiv__", "__rmod__"): setattr(CoordPair, operator, _binary_operator(operator)) - + for operator in ("__neg__", "__pos__", "__abs__", "__invert__"): setattr(CoordPair, operator, _unary_operator(operator)) - + for operator in ("__lt__", "__le__", "__eq__", "__ne__", "__gt__", "__ge__"): setattr(CoordPair, operator, _cmp_operator(operator)) - - - \ No newline at end of file diff --git a/src/wrf/decorators.py b/src/wrf/decorators.py index 1427462..806fbf5 100644 --- a/src/wrf/decorators.py +++ b/src/wrf/decorators.py @@ -2,7 +2,7 @@ from __future__ import (absolute_import, division, print_function) from collections import Iterable, OrderedDict -import wrapt +import wrapt import numpy as np import numpy.ma as ma @@ -14,188 +14,177 @@ from .constants import default_fill if xarray_enabled(): from xarray import DataArray - + + def convert_units(unit_type, alg_unit): """A decorator that converts the units from the wrapped function's output. - + The desired units are determined from the wrapped function's arguments. - + Args: - - unit_type (:obj:`str`): The unit type. Choices are: 'wind', + + unit_type (:obj:`str`): The unit type. Choices are: 'wind', 'pressure', 'temp', or 'height'. - - alg_unit (:obj:`str`): The units returned by the wrapped function, + + alg_unit (:obj:`str`): The units returned by the wrapped function, which is usually the units returned by the Fortran routine. - + Returns: - - :class:`numpy.ndarray`: The wrapped function's output in the desired + + :class:`numpy.ndarray`: The wrapped function's output in the desired units. - + """ @wrapt.decorator def func_wrapper(wrapped, instance, args, kwargs): desired_units = from_args(wrapped, "units", *args, **kwargs)["units"] u_cleaned = dealias_and_clean_unit(desired_units) check_units(u_cleaned, unit_type) - + # Unit conversion done here - return do_conversion(wrapped(*args, **kwargs), unit_type, + return do_conversion(wrapped(*args, **kwargs), unit_type, alg_unit, desired_units) - - return func_wrapper + return func_wrapper -#def _calc_out_dims(outvar, left_dims): -# """ -# -# """ -# #left_dims = [x for x in left_dims] -# #right_dims = [x for x in outvar.shape] -# #return left_dims + right_dims -# -# return left_dims + outvar.shape - def left_iteration(ref_var_expected_dims, ref_var_right_ndims, insert_dims=None, ref_var_idx=None, ref_var_name=None, - ignore_args=None, + ignore_args=None, ignore_kargs=None, outviews="outview", alg_dtype=np.float64, cast_output=True): """A decorator to handle iterating over the leftmost dimensions. - + For example, if a wrapped function works with three-dimensional arrays, but - the variables include a 4th leftmost dimension for 'Time', this decorator + the variables include a 4th leftmost dimension for 'Time', this decorator will iterate over all times, call the 3D Fortran routine, and aggregate the results in to a 4D output array. - - It is also important to note that the final output array is allocated - first, and then views are passed to the wrapped function so that values + + It is also important to note that the final output array is allocated + first, and then views are passed to the wrapped function so that values do not need to get copied in to the final output array. - + Args: - - ref_var_expected_dims (:obj:`int`): The number of dimensions that the + + ref_var_expected_dims (:obj:`int`): The number of dimensions that the Fortran routine is expecting for the reference variable. - - ref_var_right_ndims (:obj:`int`): The number of dimensions from the - right to keep for the reference variable when making the output. - Can also be a :class:`combine_dims` object if the sizes are + + ref_var_right_ndims (:obj:`int`): The number of dimensions from the + right to keep for the reference variable when making the output. + Can also be a :class:`combine_dims` object if the sizes are determined from multiple variables. - - insert_dims (sequence of :obj:`int`, optional): A sequence of - dimensions to insert between the left dimensions (e.g. time) and + + insert_dims (sequence of :obj:`int`, optional): A sequence of + dimensions to insert between the left dimensions (e.g. time) and the kept right dimensions. Default is None. - - ref_var_idx (:obj:`int`, optional): The index in the wrapped function's - positional arguments to be used as the reference variable for - determining the leftmost dimensions. Must be specified if + + ref_var_idx (:obj:`int`, optional): The index in the wrapped function's + positional arguments to be used as the reference variable for + determining the leftmost dimensions. Must be specified if *ref_var_name* is None. Default is None. - - ref_var_name (:obj:`str`, optional): The keyword argument name for the - wrapped function's keyword arguments to be used as the reference - variable for calculating the leftmost dimensions. Must be + + ref_var_name (:obj:`str`, optional): The keyword argument name for the + wrapped function's keyword arguments to be used as the reference + variable for calculating the leftmost dimensions. Must be specified if *ref_var_idx* is None. Default is None. - + ignore_args (sequence of :obj:`int`): Indexes of any arguments that - should be ignored when creating the sliced views that are + should be ignored when creating the sliced views that are passed to the Fortran routine. - - ignore_kargs (sequence of :obj:`str`): Keys of any keyword arguments - that should be ignored when creating the sliced views that are + + ignore_kargs (sequence of :obj:`str`): Keys of any keyword arguments + that should be ignored when creating the sliced views that are passed to the Fortran routine. - - outviews (:obj:`str` or a sequence): A single key or sequence of keys - that indicate the wrapped function's keyword argument to use + + outviews (:obj:`str` or a sequence): A single key or sequence of keys + that indicate the wrapped function's keyword argument to use as the output variable(s) in the wrapped function. - - alg_dtype (:class:`numpy.dtype` or :obj:`str`): The numpy data type + + alg_dtype (:class:`numpy.dtype` or :obj:`str`): The numpy data type used in the wrapped function. - - cast_output (:obj:`bool`): Set to True to cast the wrapped function's + + cast_output (:obj:`bool`): Set to True to cast the wrapped function's output to the same type as the reference variable. - + Returns: - - :class:`numpy.ndarray`: The aggregated output array that includes + + :class:`numpy.ndarray`: The aggregated output array that includes all extra leftmost dimensions found in the reference variable. - + """ @wrapt.decorator def func_wrapper(wrapped, instance, args, kwargs): _ignore_args = ignore_args if ignore_args is not None else () _ignore_kargs = ignore_kargs if ignore_kargs is not None else () _outkeys = [outviews] if isstr(outviews) else outviews - + if ref_var_idx is not None: ref_var = args[ref_var_idx] else: ref_var = kwargs[ref_var_name] - + ref_var_dtype = ref_var.dtype ref_var_shape = ref_var.shape extra_dim_num = ref_var.ndim - ref_var_expected_dims - + # No special left side iteration, return the function result if (extra_dim_num == 0): return wrapped(*args, **kwargs) - + # Start by getting the left-most 'extra' dims - extra_dims = ref_var_shape[0:extra_dim_num] - + extra_dims = ref_var_shape[0:extra_dim_num] + mid_dims = () if insert_dims is None else tuple(insert_dims) - + if not isinstance(ref_var_right_ndims, combine_dims): right_dims = ref_var_shape[-ref_var_right_ndims:] else: right_dims = ref_var_right_ndims(*args) - + left_dims = extra_dims outdims = left_dims + mid_dims + right_dims - + if "outview" not in kwargs: outd = OrderedDict((outkey, np.empty(outdims, alg_dtype)) - for outkey in _outkeys) - + for outkey in _outkeys) + mask_output = False for left_idxs in iter_left_indexes(extra_dims): # Make the left indexes plus a single slice object # The single slice will handle all the dimensions to # the right (e.g. [1,1,:]) left_and_slice_idxs = left_idxs + (slice(None), ) - - + # Slice the args if applicable - new_args = [arg[left_and_slice_idxs] - if i not in _ignore_args else arg - for i,arg in enumerate(args)] - + new_args = [arg[left_and_slice_idxs] + if i not in _ignore_args else arg + for i, arg in enumerate(args)] + # Slice the kwargs if applicable - new_kargs = {key:(val[left_and_slice_idxs] + new_kargs = {key: (val[left_and_slice_idxs] if key not in _ignore_kargs else val) - for key,val in viewitems(kwargs)} - + for key, val in viewitems(kwargs)} + # Skip the possible empty/missing arrays for the join method skip_missing = False for arg in new_args: try: _ = arg.ndim except AttributeError: - continue # Not an array object + continue # Not an array object else: arr = to_np(arg) - + try: all_masked = arr.mask.all() except AttributeError: - pass # Not a masked array + pass # Not a masked array else: if all_masked: for output in viewvalues(outd): @@ -204,261 +193,257 @@ def left_iteration(ref_var_expected_dims, skip_missing = True mask_output = True break - + if skip_missing: continue - + # Insert the output views if one hasn't been provided if "outview" not in new_kargs: - for outkey,output in viewitems(outd): + for outkey, output in viewitems(outd): outview = output[left_and_slice_idxs] new_kargs[outkey] = outview - + result = wrapped(*new_args, **new_kargs) - - # Make sure the result is the same data as what got passed in + + # Make sure the result is the same data as what got passed in # Can delete this once everything works - if (result.__array_interface__["data"][0] != - outview.__array_interface__["data"][0]): + if (result.__array_interface__["data"][0] != + outview.__array_interface__["data"][0]): raise RuntimeError("output array was copied") - - + if len(outd) == 1: output = next(iter(viewvalues(outd))) else: output = tuple(arr for arr in viewvalues(outd)) - - - + if cast_output: if isinstance(output, np.ndarray): output = output.astype(ref_var_dtype) else: output = tuple(arr.astype(ref_var_dtype) for arr in output) - + # Mostly when used with join if mask_output: if isinstance(output, np.ndarray): output = ma.masked_values(output, default_fill(np.float64)) else: - output = tuple(ma.masked_values(arr, default_fill(np.float64)) + output = tuple(ma.masked_values(arr, default_fill(np.float64)) for arr in output) - + return output - + return func_wrapper -def cast_type(ref_idx=0, arg_idxs=None, karg_names=None, +def cast_type(ref_idx=0, arg_idxs=None, karg_names=None, alg_dtype=np.float64, outviews="outview"): - """A decorator to handle type casting. - - This decorator is used to cast variables to and from the required + """A decorator to handle type casting. + + This decorator is used to cast variables to and from the required :class:`numpy.dtype` used in the wrapped function. - + Args: - - ref_idx (:obj:`int`, optional): The index in the wrapped function's - positional arguments to be used as the reference variable for + + ref_idx (:obj:`int`, optional): The index in the wrapped function's + positional arguments to be used as the reference variable for determining the :class:`numpy.dtype` to return. Default is 0. - - arg_idxs (sequence of :obj:`int`, optional): A sequence of indexes in the - wrapped function's positional arguments that indicate which + + arg_idxs (sequence of :obj:`int`, optional): A sequence of indexes in + the wrapped function's positional arguments that indicate which arguments to cast. Must be specified if *karg_names* is None. Default is None. - + karg_names (sequence of :obj:`str`): A sequence of keyword arguments - in the wrapped function's keyword arguments that indicate the - arguments to cast. Must be specified if *arg_idxs* is None. + in the wrapped function's keyword arguments that indicate the + arguments to cast. Must be specified if *arg_idxs* is None. Default is None. - - alg_dtype (:class:`numpy.dtype` or :obj:`str`): The numpy data type used - in the wrapped function. - - outviews (:obj:`str` or a sequence): A single key or sequence of keys - that indicate the wrapped function's keyword argument to use + + alg_dtype (:class:`numpy.dtype` or :obj:`str`): The numpy data type + used in the wrapped function. + + outviews (:obj:`str` or a sequence): A single key or sequence of keys + that indicate the wrapped function's keyword argument to use as the output variable(s) in the wrapped function. - + Returns: - - :class:`numpy.ndarray`: The wrapped function's output cast to the + + :class:`numpy.ndarray`: The wrapped function's output cast to the same :class:`numpy.dtype` as the reference variable. - + """ @wrapt.decorator def func_wrapper(wrapped, instance, args, kwargs): _arg_idxs = arg_idxs if arg_idxs is not None else () _karg_names = karg_names if karg_names is not None else () - + # Handle output views if applicable _outkeys = [outviews] if isstr(outviews) else outviews _outviews = from_args(wrapped, _outkeys, *args, **kwargs) - + has_outview = False for outkey in _outkeys: _outview = _outviews[outkey] if _outview is not None: has_outview = True - - + orig_type = args[ref_idx].dtype - + new_args = [arg.astype(alg_dtype) - if i in _arg_idxs else arg - for i,arg in enumerate(args)] - - new_kargs = {key:(val.astype(alg_dtype) - if key in _karg_names else val) - for key,val in viewitems(kwargs)} - - result = wrapped(*new_args, **new_kargs) - + if i in _arg_idxs else arg + for i, arg in enumerate(args)] + + new_kargs = {key: (val.astype(alg_dtype) + if key in _karg_names else val) + for key, val in viewitems(kwargs)} + + result = wrapped(*new_args, **new_kargs) + # Do nothing for supplied output views if not has_outview: if isinstance(result, np.ndarray): if result.dtype == orig_type: return result return result.astype(orig_type) - elif isinstance(result, Iterable): # got back a sequence of arrays - return tuple(arr.astype(orig_type) + elif isinstance(result, Iterable): # got back a sequence of arrays + return tuple(arr.astype(orig_type) if arr.dtype != orig_type else arr for arr in result) - + return result - + return func_wrapper def _extract_and_transpose(arg, do_transpose): - """Return a transposed view of the :class:`numpy.ndarray` inside of a + """Return a transposed view of the :class:`numpy.ndarray` inside of a :class:`xarray.DataArray` object. - - If the *arg* parameter is not a :class:`xarray.DataArray` object, then + + If the *arg* parameter is not a :class:`xarray.DataArray` object, then *arg* is returned. - + Args: - - arg (:class:`xarray.DataArray` or :obj:`object`): Can be any object + + arg (:class:`xarray.DataArray` or :obj:`object`): Can be any object type. - + do_transpose: Set to False to only extract the variable. When True, the extracted array will also be transposed to a Fortran view if it is not already Fortran contiguous. - + Returns: - - :class:`numpy.ndarray`: A numpy array. If *do_transpose* is True, + + :class:`numpy.ndarray`: A numpy array. If *do_transpose* is True, the numpy array will also be a Fortran contiguous view. - + """ - + if xarray_enabled(): if isinstance(arg, DataArray): arg = to_np(arg) - + if do_transpose: if isinstance(arg, np.ndarray): if not arg.flags.f_contiguous and arg.ndim > 1: return arg.T - + return arg - + def extract_and_transpose(do_transpose=True, outviews="outview"): - """A decorator to extract the data array from a :class:`xarray.DataArray` - - This decorator also transposes the view of the data to Fortran + """A decorator to extract the data array from a :class:`xarray.DataArray` + + This decorator also transposes the view of the data to Fortran contiguous if *do_transpose* is True. - + Args: - + do_transpose: Set to False to only extract the variable. When True, the extracted array will also be transposed to a Fortran view if it is not already Fortran contiguous. - - outviews (:obj:`str` or a sequence): A single key or sequence of keys - that indicate the wrapped function's keyword argument to use + + outviews (:obj:`str` or a sequence): A single key or sequence of keys + that indicate the wrapped function's keyword argument to use as the output variable(s) in the wrapped function. - + Returns: - - :class:`numpy.ndarray`: A numpy array. If *do_transpose* is True, + + :class:`numpy.ndarray`: A numpy array. If *do_transpose* is True, the numpy array will also be a Fortran contiguous view. - + """ @wrapt.decorator def func_wrapper(wrapped, instance, args, kwargs): - + # Handle output views if applicable _outkeys = [outviews] if isstr(outviews) else outviews _outviews = from_args(wrapped, _outkeys, *args, **kwargs) - + has_outview = False for outkey in _outkeys: _outview = _outviews[outkey] if _outview is not None: has_outview = True - + new_args = [_extract_and_transpose(arg, do_transpose) for arg in args] - - new_kargs = {key:_extract_and_transpose(val, do_transpose) - for key,val in viewitems(kwargs)} - - result = wrapped(*new_args, **new_kargs) - + + new_kargs = {key: _extract_and_transpose(val, do_transpose) + for key, val in viewitems(kwargs)} + + result = wrapped(*new_args, **new_kargs) + # Do nothing for supplied output views if has_outview: return result - + if isinstance(result, np.ndarray): if result.flags.f_contiguous and result.ndim > 1: return result.T elif isinstance(result, Iterable): - return tuple(x.T if x.flags.f_contiguous and x.ndim > 1 else x + return tuple(x.T if x.flags.f_contiguous and x.ndim > 1 else x for x in result) - + return result - + return func_wrapper def check_args(refvaridx, refvarndim, rightdims, stagger=None, refstagdim=None): """A decorator to check that the wrapped function's arguments are valid. - + An exception is raised when an invalid argument is found. - + Args: - - refvaridx (:obj:`int`): The wrapped function's positional argument + + refvaridx (:obj:`int`): The wrapped function's positional argument index to use as the reference variable. - - refvarndim (:obj:`int`): The number of dimensions for the reference + + refvarndim (:obj:`int`): The number of dimensions for the reference variable that is expected by the wrapped function. - - rightdims (sequence of :obj:`int`): The expected number of right + + rightdims (sequence of :obj:`int`): The expected number of right dimensions for each argument. - - stagger (sequence of :obj:`int` or :obj:`None`, optional): The - dimension that is staggered for each argument in the wrapped - function. Use :obj:`None` in the sequence to indicate no + + stagger (sequence of :obj:`int` or :obj:`None`, optional): The + dimension that is staggered for each argument in the wrapped + function. Use :obj:`None` in the sequence to indicate no staggering for that argument. Default is None. - - refstagdim (:obj:`int`, optional): The staggered dimension for the + + refstagdim (:obj:`int`, optional): The staggered dimension for the reference variable, if applicable. Default is None. - + Returns: - + None - + Raises: - + :class:`ValueError`: Raised when an invalid argument is detected. - + """ @wrapt.decorator def func_wrapper(wrapped, instance, args, kwargs): - + refvar = args[refvaridx] try: _ndim = refvar.ndim @@ -467,7 +452,7 @@ def check_args(refvaridx, refvarndim, rightdims, stagger=None, "object".format(refvaridx)) else: extra_dims = refvar.ndim - refvarndim - + # Always use unstaggered as the basis of comparison if refstagdim is not None: _refshape = list(refvar.shape) @@ -475,33 +460,34 @@ def check_args(refvaridx, refvarndim, rightdims, stagger=None, _refshape = tuple(_refshape) else: _refshape = refvar.shape - + if stagger is None: _stagger = [None]*len(rightdims) else: _stagger = stagger - - for i,ndim in enumerate(rightdims): + + for i, ndim in enumerate(rightdims): if ndim is None: continue - + var = args[i] - + try: _ = var.ndim except AttributeError: raise ValueError("argument {} is not an arraylike " "object".format(i)) - + right_var_ndims = rightdims[i] - + # Check that the number of dims is correct if (var.ndim - extra_dims != right_var_ndims): raise ValueError("invalid number of dimensions for argument " - "{} (got {}, expected {}).".format(i, - var.ndim, - right_var_ndims + extra_dims)) - + "{} (got {}, expected {}).".format( + i, + var.ndim, + right_var_ndims + extra_dims)) + # Add 1 to the reference staggered dim index before doing the check if _stagger[i] is not None: ref_shape = list(_refshape) @@ -509,27 +495,19 @@ def check_args(refvaridx, refvarndim, rightdims, stagger=None, ref_shape = tuple(ref_shape) else: ref_shape = _refshape - - ref_right_sizes = ref_shape[extra_dims:] - - # Check that right dimensions are lined up - if (var.shape[-right_var_ndims:] != - ref_right_sizes[-right_var_ndims:]): - - raise ValueError("invalid shape for argument " - "{} (got {}, expected {})".format(i, - var.shape[-right_var_ndims:], - ref_right_sizes[-right_var_ndims:])) - - return wrapped(*args, **kwargs) - - return func_wrapper + ref_right_sizes = ref_shape[extra_dims:] - - + # Check that right dimensions are lined up + if (var.shape[-right_var_ndims:] != + ref_right_sizes[-right_var_ndims:]): - - + raise ValueError("invalid shape for argument " + "{} (got {}, expected {})".format( + i, + var.shape[-right_var_ndims:], + ref_right_sizes[-right_var_ndims:])) + return wrapped(*args, **kwargs) + return func_wrapper diff --git a/src/wrf/destag.py b/src/wrf/destag.py index 21d688d..2a1275c 100755 --- a/src/wrf/destag.py +++ b/src/wrf/destag.py @@ -8,57 +8,55 @@ from .metadecorators import set_destag_metadata @extract_and_transpose(do_transpose=False) def destagger(var, stagger_dim, meta=False): """Return the variable on the unstaggered grid. - - This function destaggers the variable by taking the average of the - values located on either side of the grid box. - + + This function destaggers the variable by taking the average of the + values located on either side of the grid box. + Args: - - var (:class:`xarray.DataArray` or :class:`numpy.ndarray`): A variable + + var (:class:`xarray.DataArray` or :class:`numpy.ndarray`): A variable on a staggered grid. - + stagger_dim (:obj:`int`): The dimension index to destagger. - Negative values can be used to choose dimensions referenced + Negative values can be used to choose dimensions referenced from the right hand side (-1 is the rightmost dimension). - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is False. - + Returns: - + :class:`xarray.DataArray` or :class:`numpy.ndarray`: - The destaggered variable. If xarray is enabled and - the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + The destaggered variable. If xarray is enabled and + the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ var_shape = var.shape num_dims = var.ndim stagger_dim_size = var_shape[stagger_dim] - - # Dynamically building the range slices to create the appropriate + + # Dynamically building the range slices to create the appropriate # number of ':'s in the array accessor lists. - # For example, for a 3D array, the calculation would be - # result = .5 * (var[:,:,0:stagger_dim_size-2] + # For example, for a 3D array, the calculation would be + # result = .5 * (var[:,:,0:stagger_dim_size-2] # + var[:,:,1:stagger_dim_size-1]) - # for stagger_dim=2. So, full slices would be used for dims 0 and 1, but - # dim 2 needs the special slice. + # for stagger_dim=2. So, full slices would be used for dims 0 and 1, but + # dim 2 needs the special slice. full_slice = slice(None) slice1 = slice(0, stagger_dim_size - 1, 1) slice2 = slice(1, stagger_dim_size, 1) - + # default to full slices dim_ranges_1 = [full_slice] * num_dims dim_ranges_2 = [full_slice] * num_dims - + # for the stagger dim, insert the appropriate slice range dim_ranges_1[stagger_dim] = slice1 dim_ranges_2[stagger_dim] = slice2 - + result = .5*(var[tuple(dim_ranges_1)] + var[tuple(dim_ranges_2)]) - - return result - \ No newline at end of file + return result diff --git a/src/wrf/extension.py b/src/wrf/extension.py index 84803ef..177fc64 100755 --- a/src/wrf/extension.py +++ b/src/wrf/extension.py @@ -5,148 +5,150 @@ import numpy as np from .constants import Constants, default_fill from wrf._wrffortran import (dcomputetk, dinterp3dz, dinterp2dxy, dinterp1d, - dcomputeseaprs, dfilter2d, dcomputerh, dcomputeuvmet, - dcomputetd, dcapecalc2d, dcapecalc3d, dcloudfrac2, - wrfcttcalc, calcdbz, dcalrelhl, dcalcuh, dcomputepv, - dcomputeabsvort, dlltoij, dijtoll, deqthecalc, - omgcalc, virtual_temp, wetbulbcalc, dcomputepw, - wrf_monotonic, wrf_vintrp, dcomputewspd, - dcomputewdir, dinterp3dz_2dlev, - fomp_set_num_threads, fomp_get_num_threads, - fomp_get_max_threads, fomp_get_thread_num, - fomp_get_num_procs, fomp_in_parallel, - fomp_set_dynamic, fomp_get_dynamic, fomp_set_nested, - fomp_get_nested, fomp_set_schedule, - fomp_get_schedule, fomp_get_thread_limit, - fomp_set_max_active_levels, - fomp_get_max_active_levels, fomp_get_level, - fomp_get_ancestor_thread_num, fomp_get_team_size, - fomp_get_active_level, fomp_in_final, - fomp_init_lock, fomp_init_nest_lock, - fomp_destroy_lock, fomp_destroy_nest_lock, - fomp_set_lock, fomp_set_nest_lock, - fomp_unset_lock, fomp_unset_nest_lock, - fomp_test_lock, fomp_test_nest_lock, - fomp_get_wtime, fomp_get_wtick, fomp_enabled) - -from .decorators import (left_iteration, cast_type, + dcomputeseaprs, dfilter2d, dcomputerh, + dcomputeuvmet, dcomputetd, dcapecalc2d, + dcapecalc3d, dcloudfrac2, wrfcttcalc, calcdbz, + dcalrelhl, dcalcuh, dcomputepv, dcomputeabsvort, + dlltoij, dijtoll, deqthecalc, omgcalc, + virtual_temp, wetbulbcalc, dcomputepw, + wrf_monotonic, wrf_vintrp, dcomputewspd, + dcomputewdir, dinterp3dz_2dlev, + fomp_set_num_threads, fomp_get_num_threads, + fomp_get_max_threads, fomp_get_thread_num, + fomp_get_num_procs, fomp_in_parallel, + fomp_set_dynamic, fomp_get_dynamic, + fomp_set_nested, fomp_get_nested, + fomp_set_schedule, fomp_get_schedule, + fomp_get_thread_limit, fomp_set_max_active_levels, + fomp_get_max_active_levels, fomp_get_level, + fomp_get_ancestor_thread_num, fomp_get_team_size, + fomp_get_active_level, fomp_in_final, + fomp_init_lock, fomp_init_nest_lock, + fomp_destroy_lock, fomp_destroy_nest_lock, + fomp_set_lock, fomp_set_nest_lock, + fomp_unset_lock, fomp_unset_nest_lock, + fomp_test_lock, fomp_test_nest_lock, + fomp_get_wtime, fomp_get_wtick, fomp_enabled) + +from .decorators import (left_iteration, cast_type, extract_and_transpose, check_args) from .util import combine_dims, npbytes_to_str, psafilepath from .py3compat import py3range -from .specialdec import (uvmet_left_iter, cape_left_iter, +from .specialdec import (uvmet_left_iter, cape_left_iter, cloudfrac_left_iter, check_cape_args, interplevel_left_iter, check_interplevel_args) + class DiagnosticError(Exception): """Raised when an error occurs in a diagnostic routine.""" def __init__(self, message=None): """Initialize a :class:`wrf.DiagnosticError` object. - + Args: - + message (:obj:`str`): The error message. - + """ self._msg = message - + def __str__(self): return self._msg - + def __call__(self, message): """Callable method to make the exception object raise itself. - - This allows the exception to be thrown from inside Fortran routines - by using f2py's callback mechanism. This is no longer used within + + This allows the exception to be thrown from inside Fortran routines + by using f2py's callback mechanism. This is no longer used within wrf-python, but may be useful to other users. - + See Also: - + `f2py doc `_ - + """ raise self.__class__(message) -# The routines below are thin wrappers around the Fortran functions. These -# are not meant to be called by end users. Use the public API instead for + +# The routines below are thin wrappers around the Fortran functions. These +# are not meant to be called by end users. Use the public API instead for # that purpose. -# IMPORTANT! Unless otherwise noted, all variables used in the routines +# IMPORTANT! Unless otherwise noted, all variables used in the routines # below assume that Fortran-ordered views are being used. This allows # f2py to pass the array pointers directly to the Fortran routine. - @check_interplevel_args(is2dlev=False) @interplevel_left_iter(is2dlev=False) -@cast_type(arg_idxs=(0,1,2)) +@cast_type(arg_idxs=(0, 1, 2)) @extract_and_transpose() def _interpz3d(field3d, z, desiredloc, missingval, outview=None): """Wrapper for dinterp3dz. - + Located in wrf_user.f90. - + """ - if outview is None: + if outview is None: outshape = field3d.shape[0:2] + desiredloc.shape outview = np.empty(outshape, np.float64, order="F") - - result = dinterp3dz(field3d, + + result = dinterp3dz(field3d, outview, - z, - desiredloc, + z, + desiredloc, missingval) return result @check_interplevel_args(is2dlev=True) @interplevel_left_iter(is2dlev=True) -@cast_type(arg_idxs=(0,1,2)) +@cast_type(arg_idxs=(0, 1, 2)) @extract_and_transpose() def _interpz3d_lev2d(field3d, z, lev2d, missingval, outview=None): """Wrapper for dinterp3dz. - + Located in wrf_user.f90. - + """ if outview is None: outview = np.empty(field3d.shape[0:2], np.float64, order="F") - - result = dinterp3dz_2dlev(field3d, + + result = dinterp3dz_2dlev(field3d, outview, - z, - lev2d, + z, + lev2d, missingval) return result -@check_args(0, 3, (3,)) -@left_iteration(3, combine_dims([(0,-3),(1,-2)]), ref_var_idx=0, - ignore_args=(1,)) -@cast_type(arg_idxs=(0,1)) +@check_args(0, 3, (3, )) +@left_iteration(3, combine_dims([(0, -3), (1, -2)]), ref_var_idx=0, + ignore_args=(1, )) +@cast_type(arg_idxs=(0, 1)) @extract_and_transpose() def _interp2dxy(field3d, xy, outview=None): """Wrapper for dinterp2dxy. - + Located in wrf_user.f90. - + """ if outview is None: - outview = np.empty((xy.shape[-1], field3d.shape[-1]), np.float64, + outview = np.empty((xy.shape[-1], field3d.shape[-1]), np.float64, order="F") - + result = dinterp2dxy(field3d, outview, xy) return result -@check_args(0, 1, (1,1,None,None)) -@left_iteration(1, combine_dims([(2,0)]), ref_var_idx=0, ignore_args=(2,3)) -@cast_type(arg_idxs=(0,1,2)) +@check_args(0, 1, (1, 1, None, None)) +@left_iteration(1, combine_dims([(2, 0)]), ref_var_idx=0, ignore_args=(2, 3)) +@cast_type(arg_idxs=(0, 1, 2)) @extract_and_transpose() def _interp1d(v_in, z_in, z_out, missingval, outview=None): """Wrapper for dinterp1d. - + Located in wrf_user.f90. - + """ if outview is None: outview = np.empty_like(z_out) @@ -156,47 +158,47 @@ def _interp1d(v_in, z_in, z_out, missingval, outview=None): z_in, z_out, missingval) - + return result -@left_iteration(3, combine_dims([(3,0), (1,0)]), - ref_var_idx=0, ignore_args=(1,3,4)) -@cast_type(arg_idxs=(0,)) +@left_iteration(3, combine_dims([(3, 0), (1, 0)]), + ref_var_idx=0, ignore_args=(1, 3, 4)) +@cast_type(arg_idxs=(0, )) @extract_and_transpose(do_transpose=False) def _vertcross(field3d, xy, var2dz, z_var2d, missingval, outview=None): """Return the vertical cross section. - - This routine was originally written in scripted NCL code and doesn't + + This routine was originally written in scripted NCL code and doesn't directly wrap a Fortran routine. - + Located in WRFUserARW.ncl. - + """ # Note: This is using C-ordering if outview is None: outview = np.empty((z_var2d.shape[0], xy.shape[0]), dtype=var2dz.dtype) - + var2dtmp = _interp2dxy(field3d, xy) - + for i in py3range(xy.shape[0]): - outview[:,i] = _interp1d(var2dtmp[:,i], var2dz[:,i], z_var2d, - missingval) - + outview[:, i] = _interp1d(var2dtmp[:, i], var2dz[:, i], z_var2d, + missingval) + return outview -@left_iteration(2, combine_dims([(1,0)]), ref_var_idx=0, ignore_args=(1,)) -@cast_type(arg_idxs=(0,)) +@left_iteration(2, combine_dims([(1, 0)]), ref_var_idx=0, ignore_args=(1, )) +@cast_type(arg_idxs=(0, )) @extract_and_transpose(do_transpose=False) def _interpline(field2d, xy, outview=None): """Return the two-dimensional field interpolated to a line. - - This routine was originally written in scripted NCL code and doesn't + + This routine was originally written in scripted NCL code and doesn't directly wrap a Fortran routine. - + Located in WRFUserARW.ncl. - + """ # Note: This is using C-ordering if outview is None: @@ -204,35 +206,35 @@ def _interpline(field2d, xy, outview=None): tmp_shape = (1,) + field2d.shape var2dtmp = np.empty(tmp_shape, field2d.dtype) - var2dtmp[0,:,:] = field2d[:,:] - + var2dtmp[0, :, :] = field2d[:, :] + var1dtmp = _interp2dxy(var2dtmp, xy) - + outview[:] = var1dtmp[0, :] - + return outview -@check_args(0, 3, (3,3,3,3)) +@check_args(0, 3, (3, 3, 3, 3)) @left_iteration(3, 2, ref_var_idx=0) -@cast_type(arg_idxs=(0,1,2,3)) +@cast_type(arg_idxs=(0, 1, 2, 3)) @extract_and_transpose() def _slp(z, t, p, q, outview=None): """Wrapper for dcomputeseaprs. - + Located in wrf_user.f90. - + """ t_surf = np.zeros(z.shape[0:2], np.float64, order="F") t_sea_level = np.zeros(z.shape[0:2], np.float64, order="F") level = np.zeros(z.shape[0:2], np.int32, order="F") - + if outview is None: outview = np.empty(z.shape[0:2], np.float64, order="F") - + errstat = np.array(0) errmsg = np.zeros(Constants.ERRLEN, "c") - + result = dcomputeseaprs(z, t, p, @@ -243,98 +245,98 @@ def _slp(z, t, p, q, outview=None): level, errstat=errstat, errmsg=errmsg) - + if int(errstat) != 0: raise DiagnosticError("".join(npbytes_to_str(errmsg)).strip()) - + return result -@check_args(0, 3, (3,3)) +@check_args(0, 3, (3, 3)) @left_iteration(3, 3, ref_var_idx=0) -@cast_type(arg_idxs=(0,1)) +@cast_type(arg_idxs=(0, 1)) @extract_and_transpose() def _tk(pressure, theta, outview=None): """Wrapper for dcomputetk. - + Located in wrf_user.f90. - + """ # No need to transpose here since operations on 1D array shape = pressure.shape - if outview is None: + if outview is None: outview = np.empty_like(pressure) result = dcomputetk(outview.ravel(order="A"), - pressure.ravel(order="A"), - theta.ravel(order="A")) + pressure.ravel(order="A"), + theta.ravel(order="A")) result = np.reshape(result, shape, order="F") - - return result + return result -@check_args(0, 2, (2,2)) + +@check_args(0, 2, (2, 2)) @left_iteration(2, 2, ref_var_idx=0) -@cast_type(arg_idxs=(0,1)) +@cast_type(arg_idxs=(0, 1)) @extract_and_transpose() def _td(pressure, qv_in, outview=None): """Wrapper for dcomputetd. - + Located in wrf_user.f90. - + """ shape = pressure.shape if outview is None: outview = np.empty_like(pressure) - + result = dcomputetd(outview.ravel(order="A"), - pressure.ravel(order="A"), + pressure.ravel(order="A"), qv_in.ravel(order="A")) result = np.reshape(result, shape, order="F") - + return result -@check_args(0, 2, (2,2,2)) +@check_args(0, 2, (2, 2, 2)) @left_iteration(2, 2, ref_var_idx=0) -@cast_type(arg_idxs=(0,1,2)) +@cast_type(arg_idxs=(0, 1, 2)) @extract_and_transpose() def _rh(qv, q, t, outview=None): """Wrapper for dcomputerh. - + Located in wrf_user.f90. - + """ shape = qv.shape if outview is None: outview = np.empty_like(qv) result = dcomputerh(qv.ravel(order="A"), - q.ravel(order="A"), - t.ravel(order="A"), - outview.ravel(order="A")) + q.ravel(order="A"), + t.ravel(order="A"), + outview.ravel(order="A")) result = np.reshape(result, shape, order="F") - + return result -# Note: combining the -3 and -2 dimensions from u, then the -1 dimension +# Note: combining the -3 and -2 dimensions from u, then the -1 dimension # from v -@check_args(0, 3, (3,3,2,2,2,2), stagger=(-1,-2,-1,-2,None,None), +@check_args(0, 3, (3, 3, 2, 2, 2, 2), stagger=(-1, -2, -1, -2, None, None), refstagdim=-1) -@left_iteration(3, combine_dims([(0, (-3,-2)), - (1, (-1,))]), - ref_var_idx=0, ignore_args=(6,7)) -@cast_type(arg_idxs=(0,1,2,3,4,5)) +@left_iteration(3, combine_dims([(0, (-3, -2)), + (1, (-1, ))]), + ref_var_idx=0, ignore_args=(6, 7)) +@cast_type(arg_idxs=(0, 1, 2, 3, 4, 5)) @extract_and_transpose() def _avo(u, v, msfu, msfv, msfm, cor, dx, dy, outview=None): """Wrapper for dcomputeabsvort. - + Located in wrf_pvo.f90. - + """ if outview is None: - outshape = (v.shape[0],) + u.shape[1:] + outshape = (v.shape[0], ) + u.shape[1:] outview = np.empty(outshape, np.float64, order="F") - + result = dcomputeabsvort(outview, u, v, @@ -344,25 +346,24 @@ def _avo(u, v, msfu, msfv, msfm, cor, dx, dy, outview=None): cor, dx, dy) - + return result -@check_args(0, 3, (3,3,3,3,2,2,2,2), stagger=(-1,-2,None,None,-1,-2,None, - None), - refstagdim=-1) -@left_iteration(3, 3, ref_var_idx=2, ignore_args=(8,9)) -@cast_type(arg_idxs=(0,1,2,3,4,5,6,7)) +@check_args(0, 3, (3, 3, 3, 3, 2, 2, 2, 2), + stagger=(-1, -2, None, None, -1, -2, None, None), refstagdim=-1) +@left_iteration(3, 3, ref_var_idx=2, ignore_args=(8, 9)) +@cast_type(arg_idxs=(0, 1, 2, 3, 4, 5, 6, 7)) @extract_and_transpose() def _pvo(u, v, theta, prs, msfu, msfv, msfm, cor, dx, dy, outview=None): """Wrapper for dcomputepv. - + Located in wrf_pvo.f90. - + """ if outview is None: outview = np.empty_like(prs) - + result = dcomputepv(outview, u, v, @@ -374,50 +375,52 @@ def _pvo(u, v, theta, prs, msfu, msfv, msfm, cor, dx, dy, outview=None): cor, dx, dy) - + return result -@check_args(0, 3, (3,3,3)) +@check_args(0, 3, (3, 3, 3)) @left_iteration(3, 3, ref_var_idx=0) -@cast_type(arg_idxs=(0,1,2)) +@cast_type(arg_idxs=(0, 1, 2)) @extract_and_transpose() def _eth(qv, tk, p, outview=None): """Wrapper for deqthecalc. - + Located in eqthecalc.f90. - + """ if outview is None: outview = np.empty_like(qv) - + result = deqthecalc(qv, tk, p, outview) - + return result @uvmet_left_iter() -@cast_type(arg_idxs=(0,1,2,3)) +@cast_type(arg_idxs=(0, 1, 2, 3)) @extract_and_transpose() -def _uvmet(u, v, lat, lon, cen_long, cone, isstag=0, has_missing=False, - umissing=default_fill(np.float64), vmissing=default_fill(np.float64), - uvmetmissing=default_fill(np.float64), outview=None): +def _uvmet(u, v, lat, lon, cen_long, cone, isstag=0, has_missing=False, + umissing=default_fill(np.float64), + vmissing=default_fill(np.float64), + uvmetmissing=default_fill(np.float64), + outview=None): """Wrapper for dcomputeuvmet. - + Located in wrf_user.f90. - + """ longca = np.zeros(lat.shape[0:2], np.float64, order="F") longcb = np.zeros(lon.shape[0:2], np.float64, order="F") rpd = Constants.PI/180. - + if outview is None: outdims = u.shape + (2,) outview = np.empty(outdims, np.float64, order="F") - + result = dcomputeuvmet(u, v, outview, @@ -428,73 +431,73 @@ def _uvmet(u, v, lat, lon, cen_long, cone, isstag=0, has_missing=False, cen_long, cone, rpd, - isstag, + isstag, has_missing, umissing, vmissing, uvmetmissing) - + return result -@check_args(0, 3, (3,3,3,3)) +@check_args(0, 3, (3, 3, 3, 3)) @left_iteration(3, 3, ref_var_idx=0) -@cast_type(arg_idxs=(0,1,2,3)) +@cast_type(arg_idxs=(0, 1, 2, 3)) @extract_and_transpose() def _omega(qv, tk, w, p, outview=None): """Wrapper for omgcalc. - + Located in wrf_rip_phys_routines.f90. - + """ if outview is None: outview = np.empty_like(qv) - + result = omgcalc(qv, tk, w, p, outview) - + return result -@check_args(0, 3, (3,3)) +@check_args(0, 3, (3, 3)) @left_iteration(3, 3, ref_var_idx=0) -@cast_type(arg_idxs=(0,1)) +@cast_type(arg_idxs=(0, 1)) @extract_and_transpose() def _tv(tk, qv, outview=None): """Wrapper for virtual_temp. - + Located in wrf_rip_phys_routines.f90. - + """ if outview is None: outview = np.empty_like(tk) - + result = virtual_temp(tk, qv, outview) - + return result -@check_args(0, 3, (3,3,3)) +@check_args(0, 3, (3, 3, 3)) @left_iteration(3, 3, ref_var_idx=0, ignore_args=(3,)) -@cast_type(arg_idxs=(0,1,2)) +@cast_type(arg_idxs=(0, 1, 2)) @extract_and_transpose() def _wetbulb(p, tk, qv, psafile=psafilepath(), outview=None): """Wrapper for wetbulbcalc. - + Located in wrf_rip_phys_routines.f90. - + """ if outview is None: outview = np.empty_like(p) - + errstat = np.array(0) errmsg = np.zeros(Constants.ERRLEN, "c") - + result = wetbulbcalc(p, tk, qv, @@ -502,106 +505,106 @@ def _wetbulb(p, tk, qv, psafile=psafilepath(), outview=None): psafile, errstat, errmsg) - + if int(errstat) != 0: raise DiagnosticError("".join(npbytes_to_str(errmsg)).strip()) - + return result -@check_args(0, 3, (3,3,3,2,2)) -@left_iteration(3, 2, ref_var_idx=0, ignore_args=(5,)) -@cast_type(arg_idxs=(0,1,2,3,4)) +@check_args(0, 3, (3, 3, 3, 2, 2)) +@left_iteration(3, 2, ref_var_idx=0, ignore_args=(5, )) +@cast_type(arg_idxs=(0, 1, 2, 3, 4)) @extract_and_transpose() def _srhel(u, v, z, ter, lats, top, outview=None): """Wrapper for dcalrelhl. - + Located in wrf_relhl.f90. - + """ if outview is None: outview = np.empty_like(ter) - - result = dcalrelhl(u, - v, - z, - ter, + + result = dcalrelhl(u, + v, + z, + ter, lats, top, outview) - + return result -@check_args(2, 3, (3,2,3,3,3), stagger=(-3,None,None,None,-3)) -@left_iteration(3, 2, ref_var_idx=2, ignore_args=(5,6,7,8)) -@cast_type(arg_idxs=(0,1,2,3,4)) +@check_args(2, 3, (3, 2, 3, 3, 3), stagger=(-3, None, None, None, -3)) +@left_iteration(3, 2, ref_var_idx=2, ignore_args=(5, 6, 7, 8)) +@cast_type(arg_idxs=(0, 1, 2, 3, 4)) @extract_and_transpose() def _udhel(zstag, mapfct, u, v, wstag, dx, dy, bottom, top, outview=None): """Wrapper for dcalcuh. - + Located in calc_uh.f90. - + """ if outview is None: outview = np.empty_like(mapfct) - - tem1 = np.zeros((u.shape[0], u.shape[1], u.shape[2]), np.float64, + + tem1 = np.zeros((u.shape[0], u.shape[1], u.shape[2]), np.float64, order="F") - tem2 = np.zeros((u.shape[0], u.shape[1], u.shape[2]), np.float64, + tem2 = np.zeros((u.shape[0], u.shape[1], u.shape[2]), np.float64, order="F") - - result = dcalcuh(zstag, - mapfct, - dx, - dy, - bottom, - top, + + result = dcalcuh(zstag, + mapfct, + dx, + dy, + bottom, + top, u, - v, - wstag, - outview, - tem1, + v, + wstag, + outview, + tem1, tem2) - + return result -@check_args(0, 3, (3,3,3,3), stagger=(None, None, None, -3)) +@check_args(0, 3, (3, 3, 3, 3), stagger=(None, None, None, -3)) @left_iteration(3, 2, ref_var_idx=0) -@cast_type(arg_idxs=(0,1,2,3)) +@cast_type(arg_idxs=(0, 1, 2, 3)) @extract_and_transpose() def _pw(p, tv, qv, ht, outview=None): """Wrapper for dcomputepw. - + Located in wrf_pw.f90. - + """ if outview is None: outview = np.empty(p.shape[0:2], p.dtype, order="F") - + result = dcomputepw(p, tv, qv, ht, outview) - + return result -@check_args(0, 3, (3,3,3,3,3,3)) -@left_iteration(3, 3, ref_var_idx=0, ignore_args=(6,7,8)) -@cast_type(arg_idxs=(0,1,2,3,4,5)) +@check_args(0, 3, (3, 3, 3, 3, 3, 3)) +@left_iteration(3, 3, ref_var_idx=0, ignore_args=(6, 7, 8)) +@cast_type(arg_idxs=(0, 1, 2, 3, 4, 5)) @extract_and_transpose() def _dbz(p, tk, qv, qr, qs, qg, sn0, ivarint, iliqskin, outview=None): """Wrapper for calcdbz. - + Located in wrf_user_dbz.f90. - + """ if outview is None: outview = np.empty_like(p) - + result = calcdbz(p, tk, qv, @@ -612,35 +615,35 @@ def _dbz(p, tk, qv, qr, qs, qg, sn0, ivarint, iliqskin, outview=None): ivarint, iliqskin, outview) - + return result @check_cape_args() @cape_left_iter() -@cast_type(arg_idxs=(0,1,2,3,4,5), outviews=("capeview", "cinview")) +@cast_type(arg_idxs=(0, 1, 2, 3, 4, 5), outviews=("capeview", "cinview")) @extract_and_transpose(outviews=("capeview", "cinview")) def _cape(p_hpa, tk, qv, ht, ter, sfp, missing, i3dflag, ter_follow, psafile=psafilepath(), capeview=None, cinview=None): """Wrapper for dcapecalc3d. - + Located in rip_cape.f90. - + """ if capeview is None: capeview = np.zeros(p_hpa.shape[0:3], p_hpa.dtype, order="F") - + if cinview is None: cinview = np.zeros(p_hpa.shape[0:3], p_hpa.dtype, order="F") - + errstat = np.array(0) errmsg = np.zeros(Constants.ERRLEN, "c") - + if i3dflag: cape_routine = dcapecalc3d else: cape_routine = dcapecalc2d - + # Work arrays k_left_shape = (p_hpa.shape[2], p_hpa.shape[0], p_hpa.shape[1]) prsf = np.empty(k_left_shape, np.float64, order="F") @@ -648,7 +651,7 @@ def _cape(p_hpa, tk, qv, ht, ter, sfp, missing, i3dflag, ter_follow, tmk_new = np.empty(k_left_shape, np.float64, order="F") qvp_new = np.empty(k_left_shape, np.float64, order="F") ght_new = np.empty(k_left_shape, np.float64, order="F") - + # note that p_hpa, tk, qv, and ht have the vertical flipped result = cape_routine(p_hpa, tk, @@ -658,53 +661,55 @@ def _cape(p_hpa, tk, qv, ht, ter, sfp, missing, i3dflag, ter_follow, sfp, capeview, cinview, - prsf, - prs_new, - tmk_new, - qvp_new, + prsf, + prs_new, + tmk_new, + qvp_new, ght_new, missing, ter_follow, psafile, errstat, errmsg) - + if int(errstat) != 0: raise DiagnosticError("".join(npbytes_to_str(errmsg)).strip()) - + return result -@check_args(0, 3, (3,3)) + +@check_args(0, 3, (3, 3)) @cloudfrac_left_iter() @cast_type(arg_idxs=(0, 1), outviews=("lowview", "midview", "highview")) @extract_and_transpose(outviews=("lowview", "midview", "highview")) def _cloudfrac(vert, rh, vert_inc_w_height, low_thresh, mid_thresh, - high_thresh, missing, lowview=None, midview=None, highview=None): + high_thresh, missing, lowview=None, midview=None, + highview=None): """Wrapper for dcloudfrac2. - + Located in wrf_cloud_fracf.f90. - + """ if lowview is None: lowview = np.zeros(vert.shape[0:2], vert.dtype, order="F") - + if midview is None: midview = np.zeros(vert.shape[0:2], vert.dtype, order="F") - + if highview is None: highview = np.zeros(vert.shape[0:2], vert.dtype, order="F") - - result = dcloudfrac2(vert, + + result = dcloudfrac2(vert, rh, vert_inc_w_height, low_thresh, mid_thresh, high_thresh, missing, - lowview, - midview, + lowview, + midview, highview) - + return result @@ -713,16 +718,16 @@ def _lltoxy(map_proj, truelat1, truelat2, stdlon, known_x, known_y, dx, dy, latinc, loninc, lat, lon, outview=None): """Wrapper for dlltoij. - + Located in wrf_user_latlon_routines.f90. - + """ if outview is None: outview = np.zeros((2), dtype=np.float64, order="F") - + errstat = np.array(0) errmsg = np.zeros(Constants.ERRLEN, "c") - + result = dlltoij(map_proj, truelat1, truelat2, @@ -742,27 +747,27 @@ def _lltoxy(map_proj, truelat1, truelat2, stdlon, outview, errstat, errmsg) - + if int(errstat) != 0: raise DiagnosticError("".join(npbytes_to_str(errmsg)).strip()) - + return result def _xytoll(map_proj, truelat1, truelat2, stdlon, lat1, lon1, - pole_lat, pole_lon, known_x, known_y, dx, dy, latinc, - loninc, x, y, outview=None): + pole_lat, pole_lon, known_x, known_y, dx, dy, latinc, + loninc, x, y, outview=None): """Wrapper for dijtoll. - + Located in wrf_user_latlon_routines.f90. - + """ if outview is None: outview = np.zeros((2), dtype=np.float64, order="F") - + errstat = np.array(0) errmsg = np.zeros(Constants.ERRLEN, "c") - + result = dijtoll(map_proj, truelat1, truelat2, @@ -782,29 +787,29 @@ def _xytoll(map_proj, truelat1, truelat2, stdlon, lat1, lon1, outview, errstat, errmsg) - + if int(errstat) != 0: raise DiagnosticError("".join(npbytes_to_str(errmsg)).strip()) - + return result -@check_args(0, 3, (3,3,3,3,3,3,2)) -@left_iteration(3, 2, ref_var_idx=0, ignore_args=(7,8,9,10)) -@cast_type(arg_idxs=(0,1,2,3,4,5,6)) +@check_args(0, 3, (3, 3, 3, 3, 3, 3, 2)) +@left_iteration(3, 2, ref_var_idx=0, ignore_args=(7, 8, 9, 10)) +@cast_type(arg_idxs=(0, 1, 2, 3, 4, 5, 6)) @extract_and_transpose() -def _ctt(p_hpa, tk, qice, qcld, qv, ght, ter, haveqci, fill_nocloud, +def _ctt(p_hpa, tk, qice, qcld, qv, ght, ter, haveqci, fill_nocloud, missing, opt_thresh, outview=None): """Wrapper for wrfcttcalc. - + Located in wrf_fctt.f90. - + """ if outview is None: outview = np.empty_like(ter) - + pf = np.empty(p_hpa.shape[0:3], np.float64, order="F") - + result = wrfcttcalc(p_hpa, tk, qice, @@ -814,65 +819,65 @@ def _ctt(p_hpa, tk, qice, qcld, qv, ght, ter, haveqci, fill_nocloud, ter, outview, pf, - haveqci, - fill_nocloud, + haveqci, + fill_nocloud, missing, opt_thresh) - + return result -@check_args(0, 2, (2,)) -@left_iteration(2, 2, ref_var_idx=0, ignore_args=(1,2)) -@cast_type(arg_idxs=(0,)) +@check_args(0, 2, (2, )) +@left_iteration(2, 2, ref_var_idx=0, ignore_args=(1, 2)) +@cast_type(arg_idxs=(0, )) @extract_and_transpose() def _smooth2d(field, passes, cenweight, outview=None): """Wrapper for dfilter2d. - + Located in wrf_user.f90. - + """ - # Unlike NCL, this routine will not modify the values in place, but + # Unlike NCL, this routine will not modify the values in place, but # copies the original data before modifying it. - + if isinstance(field, np.ma.MaskedArray): missing = field.fill_value else: missing = default_fill(np.float64) - + if outview is None: outview = field.copy(order="A") else: outview[:] = field[:] - - field_tmp = np.zeros(outview.shape, outview.dtype, order="F") - dfilter2d(outview, - field_tmp, + field_tmp = np.zeros(outview.shape, outview.dtype, order="F") + + dfilter2d(outview, + field_tmp, passes, missing, cenweight) - + return outview -@check_args(0, 3, (3,3,2)) -@left_iteration(3, 3, ref_var_idx=0, ignore_args=(3,4,5)) -@cast_type(arg_idxs=(0,1,2)) +@check_args(0, 3, (3, 3, 2)) +@left_iteration(3, 3, ref_var_idx=0, ignore_args=(3, 4, 5)) +@cast_type(arg_idxs=(0, 1, 2)) @extract_and_transpose() def _monotonic(var, lvprs, coriolis, idir, delta, icorsw, outview=None): """Wrapper for wrf_monotonic. - + Located in wrf_vinterp.f90. - + """ - # If icorsw is not 0, then the input variable might get modified by the + # If icorsw is not 0, then the input variable might get modified by the # fortran routine. We don't want this, so make a copy and pass that on. var = var.copy(order="A") if icorsw != 0 else var - + if outview is None: outview = np.empty_like(var) - + result = wrf_monotonic(outview, var, lvprs, @@ -880,34 +885,34 @@ def _monotonic(var, lvprs, coriolis, idir, delta, icorsw, outview=None): idir, delta, icorsw) - + return result # Output shape is interp_levels.shape + field.shape[-2:] -@check_args(0, 3, (3,3,3,3,3,2,2,2,3)) -@left_iteration(3, combine_dims([(9, (-1,)), - (0, (-2,-1))]), - ref_var_idx=0, ignore_args=(9,10,11,12,13,14)) -@cast_type(arg_idxs=(0,1,2,3,4,5,6,7,8,9)) +@check_args(0, 3, (3, 3, 3, 3, 3, 2, 2, 2, 3)) +@left_iteration(3, combine_dims([(9, (-1, )), + (0, (-2, -1))]), + ref_var_idx=0, ignore_args=(9, 10, 11, 12, 13, 14)) +@cast_type(arg_idxs=(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)) @extract_and_transpose() def _vintrp(field, pres, tk, qvp, ght, terrain, sfp, smsfp, vcarray, interp_levels, icase, extrap, vcor, logp, missing, outview=None): """Wrapper for wrf_vintrp. - + Located in wrf_vinterp.f90. - + """ if outview is None: outdims = field.shape[0:2] + interp_levels.shape outview = np.empty(outdims, field.dtype, order="F") - + tempout = np.zeros(field.shape[0:2], np.float64, order="F") - + errstat = np.array(0) errmsg = np.zeros(Constants.ERRLEN, "c") - + result = wrf_vintrp(field, outview, pres, @@ -927,49 +932,50 @@ def _vintrp(field, pres, tk, qvp, ght, terrain, sfp, smsfp, missing, errstat, errmsg) - + if int(errstat) != 0: raise DiagnosticError("".join(npbytes_to_str(errmsg)).strip()) - + return result -@check_args(0, 2, (2,2)) + +@check_args(0, 2, (2, 2)) @left_iteration(2, 2, ref_var_idx=0) -@cast_type(arg_idxs=(0,1)) +@cast_type(arg_idxs=(0, 1)) @extract_and_transpose() def _wspd(u, v, outview=None): """Wrapper for dcomputewspd. - + Located in wrf_wind.f90. - + """ if outview is None: outview = np.empty_like(u) - + result = dcomputewspd(outview, u, v) - + return result -@check_args(0, 2, (2,2)) +@check_args(0, 2, (2, 2)) @left_iteration(2, 2, ref_var_idx=0) -@cast_type(arg_idxs=(0,1)) +@cast_type(arg_idxs=(0, 1)) @extract_and_transpose() def _wdir(u, v, outview=None): """Wrapper for dcomputewdir. - + Located in wrf_wind.f90. - + """ if outview is None: outview = np.empty_like(u) - + result = dcomputewdir(outview, u, v) - + return result @@ -977,47 +983,47 @@ def _wdir(u, v, outview=None): def omp_set_num_threads(num_threads): """Specify the number of threads to use. - - The omp_set_num_threads routine affects the number of threads to be used - for subsequent parallel regions that do not specify a num_threads - clause, by setting the value of the first element of the nthreads-var + + The omp_set_num_threads routine affects the number of threads to be used + for subsequent parallel regions that do not specify a num_threads + clause, by setting the value of the first element of the nthreads-var ICV of the current task. - + Args: - - num_threads (a positive :obj:`int`): The number of threads. Must be + + num_threads (a positive :obj:`int`): The number of threads. Must be positive. - + Returns: - + None. - + """ if num_threads < 0 and fomp_enabled(): raise ValueError("'num_threads' must be a positive integer.") - + fomp_set_num_threads(num_threads) def omp_get_num_threads(): """Return the number of threads in the current team. - - The omp_get_num_threads routine returns the number of threads in the - team executing the parallel region to which the routine region binds. + + The omp_get_num_threads routine returns the number of threads in the + team executing the parallel region to which the routine region binds. If called from the sequential part of a program, this routine returns 1. - + Note: - + This function always returns 1 when called from within Python. - + Returns: - + :obj:`int`: The number of threads in the current team. - + See Also: - + :meth:`wrf.omp_get_max_threads`, :meth:`wrf.omp_set_num_threads` - + """ return fomp_get_num_threads() @@ -1025,20 +1031,20 @@ def omp_get_num_threads(): def omp_get_max_threads(): """Return the maximum number of threads that can be used in a parallel \ region. - - The omp_get_max_threads routine returns an upper bound on the number of - threads that could be used to form a new team if a parallel construct - without a num_threads clause were encountered after execution returns from + + The omp_get_max_threads routine returns an upper bound on the number of + threads that could be used to form a new team if a parallel construct + without a num_threads clause were encountered after execution returns from this routine. - + Returns: - + :obj:`int`: The number of threads in the current team. - + See Also: - + :meth:`wrf.omp_set_num_threads` - + """ return fomp_get_max_threads() @@ -1046,43 +1052,43 @@ def omp_get_max_threads(): def omp_get_thread_num(): """Return the thread number, within the current team, of the \ calling thread. - - The omp_get_thread_num routine returns the thread number of the calling - thread, within the team executing the parallel region to which the routine - region binds. The thread number is an integer between 0 and one less than - the value returned by omp_get_num_threads, inclusive. The thread number of - the master thread of the team is 0. The routine returns 0 if it is called + + The omp_get_thread_num routine returns the thread number of the calling + thread, within the team executing the parallel region to which the routine + region binds. The thread number is an integer between 0 and one less than + the value returned by omp_get_num_threads, inclusive. The thread number of + the master thread of the team is 0. The routine returns 0 if it is called from the sequential part of a program. - + Note: - + This function always returns 0 when called from within Python. - + Returns: - + :obj:`int`: The thread number. - + See Also: - + :meth:`wrf.omp_get_num_procs` - + """ return fomp_get_thread_num() - - + + def omp_get_num_procs(): """Return the number of processors on the device. - - The omp_get_num_procs routine returns the number of processors that are - available to the device at the time the routine is called. This value may - change between the time that it is determined by the omp_get_num_procs - routine and the time that it is read in the calling context due to system + + The omp_get_num_procs routine returns the number of processors that are + available to the device at the time the routine is called. This value may + change between the time that it is determined by the omp_get_num_procs + routine and the time that it is read in the calling context due to system actions outside the control of the OpenMP implementation. - + Returns: - + :obj:`int`: The number of processors. - + """ return fomp_get_num_procs() @@ -1090,21 +1096,21 @@ def omp_get_num_procs(): def omp_in_parallel(): """Return 1 if the active-levels-var ICV is greater than zero; \ otherwise, return 0. - - The effect of the omp_in_parallel routine is to return 1 if the current - task is enclosed by an active parallel region, and the parallel region is - enclosed by the outermost initial task region on the device; otherwise it + + The effect of the omp_in_parallel routine is to return 1 if the current + task is enclosed by an active parallel region, and the parallel region is + enclosed by the outermost initial task region on the device; otherwise it returns 0. - + Note: - + This function always returns 0 when called from within Python. - + Returns: - - :obj:`int`: Returns 1 if the active-levels-var ICV is greater than + + :obj:`int`: Returns 1 if the active-levels-var ICV is greater than zero. Otherwise, it returns 0. - + """ return fomp_in_parallel() @@ -1113,27 +1119,27 @@ def omp_set_dynamic(dynamic_threads): """Enable or disable dynamic adjustment of the number of threads \ available for the execution of subsequent parallel regions by setting the \ value of the dyn-var ICV. - - For implementations that support dynamic adjustment of the number of - threads, if the argument to omp_set_dynamic evaluates to True, dynamic - adjustment is enabled for the current task; otherwise, dynamic adjustment - is disabled for the current task. For implementations that do not support - dynamic adjustment of the number of threads this routine has no effect: + + For implementations that support dynamic adjustment of the number of + threads, if the argument to omp_set_dynamic evaluates to True, dynamic + adjustment is enabled for the current task; otherwise, dynamic adjustment + is disabled for the current task. For implementations that do not support + dynamic adjustment of the number of threads this routine has no effect: the value of dyn-var remains false. - + Args: - - dynamic_threads (:obj:`bool`): Set to True to support the dynamic + + dynamic_threads (:obj:`bool`): Set to True to support the dynamic adjustment of the number of threads. Otherwise, set to False. - + Returns: - + None. - + See Also: - + :meth:`wrf.omp_get_dynamic` - + """ fomp_set_dynamic(dynamic_threads) @@ -1141,47 +1147,47 @@ def omp_set_dynamic(dynamic_threads): def omp_get_dynamic(): """Return the value of the dyn-var ICV, which determines whether \ dynamic adjustment of the number of threads is enabled or disabled. - - This routine returns 1 if dynamic adjustment of the number of threads - is enabled for the current task; it returns 0, otherwise. If an - implementation does not support dynamic adjustment of the + + This routine returns 1 if dynamic adjustment of the number of threads + is enabled for the current task; it returns 0, otherwise. If an + implementation does not support dynamic adjustment of the number of threads, then this routine always returns 0. - + Returns: - - :obj:`int`: Returns 1 if dynamic thread adjustment is enabled, 0 + + :obj:`int`: Returns 1 if dynamic thread adjustment is enabled, 0 if disabled. - + See Also: - + :meth:`wrf.omp_set_dynamic` - + """ return fomp_get_dynamic() def omp_set_nested(nested): """Enable or disable nested parallelism, by setting the nest-var ICV - - For implementations that support nested parallelism, if the argument to - omp_set_nested evaluates to True, nested parallelism is enabled for the - current task; otherwise, nested parallelism is disabled for the current - task. For implementations that do not support nested parallelism, this + + For implementations that support nested parallelism, if the argument to + omp_set_nested evaluates to True, nested parallelism is enabled for the + current task; otherwise, nested parallelism is disabled for the current + task. For implementations that do not support nested parallelism, this routine has no effect: the value of nest-var remains False. - + Args: - - dynamic_threads (:obj:`bool`): Set to True to support nested + + dynamic_threads (:obj:`bool`): Set to True to support nested parallelism, otherwise False. - + Returns: - + None - + See Also: - + :meth:`wrf.omp_get_nested` - + """ fomp_set_nested(nested) @@ -1189,19 +1195,19 @@ def omp_set_nested(nested): def omp_get_nested(): """Return the value of the nest-var ICV, which determines if nested \ parallelism is enabled or disabled - - This routine returns 1 if nested parallelism is enabled for the current - task; it returns 0, otherwise. If an implementation does not support + + This routine returns 1 if nested parallelism is enabled for the current + task; it returns 0, otherwise. If an implementation does not support nested parallelism, this routine always returns 0. - + Returns: - + :obj:`int`: Returns 1 if nested parallelism is enabled, otherwise 0. - + See Also: - + :meth:`wrf.omp_set_nested` - + """ return fomp_get_nested() @@ -1209,80 +1215,80 @@ def omp_get_nested(): def omp_set_schedule(kind, modifier=0): """Set the schedule that is applied when *runtime* is used as \ schedule kind, by setting the value of the run-sched-var ICV. - - The effect of this routine is to set the value of the run-sched-var ICV - of the current task to the values specified in the two arguments. The - schedule is set to the schedule type specified by the first argument kind. - It can be any of the standard schedule types or any other implementation - specific one. For the schedule types static, dynamic, and guided the - chunk_size is set to the value of the second argument, or to the default - chunk_size if the value of the second argument is less than 1; for the - schedule type auto the second argument has no meaning; for implementation - specific schedule types, the values and associated meanings of the second + + The effect of this routine is to set the value of the run-sched-var ICV + of the current task to the values specified in the two arguments. The + schedule is set to the schedule type specified by the first argument kind. + It can be any of the standard schedule types or any other implementation + specific one. For the schedule types static, dynamic, and guided the + chunk_size is set to the value of the second argument, or to the default + chunk_size if the value of the second argument is less than 1; for the + schedule type auto the second argument has no meaning; for implementation + specific schedule types, the values and associated meanings of the second argument are implementation defined. - + Args: - + kind (:obj:`int`): Must be :data:`wrf.OMP_SCHED_STATIC`, - :data:`wrf.OMP_SCHED_DYNAMIC`, :data:`wrf.OMP_SCHED_GUIDED`, + :data:`wrf.OMP_SCHED_DYNAMIC`, :data:`wrf.OMP_SCHED_GUIDED`, or :data:`wrf.OMP_SCHED_AUTO`. - - modifier(:obj:`int`): An implementation specific value, depending on - the choice for *kind*. This parameter is alternatively named - chunk_size in some OpenMP documentation. Default is 0, which + + modifier(:obj:`int`): An implementation specific value, depending on + the choice for *kind*. This parameter is alternatively named + chunk_size in some OpenMP documentation. Default is 0, which means the OpenMP implementation will use its default value. - + Returns: - + None - + See Also: - + :meth:`wrf.omp_get_schedule` - + """ - fomp_set_schedule(kind, modifier) + fomp_set_schedule(kind, modifier) def omp_get_schedule(): """Return the schedule that is applied when the runtime schedule is used. - - This routine returns the run-sched-var ICV in the task to which the routine - binds. The first item is the schedule kind, which will be one of - :data:`wrf.OMP_SCHED_STATIC`, :data:`wrf.OMP_SCHED_DYNAMIC`, - :data:`wrf.OMP_SCHED_GUIDED`, or :data:`wrf.OMP_SCHED_AUTO`. The second - item returned is the modifier, which is often named chunk_size in + + This routine returns the run-sched-var ICV in the task to which the routine + binds. The first item is the schedule kind, which will be one of + :data:`wrf.OMP_SCHED_STATIC`, :data:`wrf.OMP_SCHED_DYNAMIC`, + :data:`wrf.OMP_SCHED_GUIDED`, or :data:`wrf.OMP_SCHED_AUTO`. The second + item returned is the modifier, which is often named chunk_size in OpenMP documentation. - + Returns: - + :obj:`tuple`: The first item is an :obj:`int` for the schedule *kind*. The second items is :obj:`int` for the *modifier* (chunk_size). - + See Also: - + :meth:`wrf.omp_set_schedule` - + """ return fomp_get_schedule() -def omp_get_thread_limit(): +def omp_get_thread_limit(): """Return the maximum number of OpenMP threads available to participate \ in the current contention group. - - The omp_get_thread_limit routine returns the value of the thread-limit-var + + The omp_get_thread_limit routine returns the value of the thread-limit-var ICV. - + Returns: - - :obj:`int`: The number of OpenMP threads available to participate in + + :obj:`int`: The number of OpenMP threads available to participate in the current contention group. - + See Also: - + :meth:`wrf.omp_get_max_threads` - + """ return fomp_get_thread_limit() @@ -1290,96 +1296,96 @@ def omp_get_thread_limit(): def omp_set_max_active_levels(max_levels): """Limit the number of nested active parallel regions on the device, \ by setting the max-active-levels-var ICV. - - The effect of this routine is to set the value of the max-active-levels-var - ICV to the value specified in the argument. If the number of parallel - levels requested exceeds the number of levels of parallelism supported by - the implementation, the value of the max-active-levels-var ICV will be set - to the number of parallel levels supported by the implementation. This - routine has the described effect only when called from a sequential part - of the program. When called from within an explicit parallel region, the + + The effect of this routine is to set the value of the max-active-levels-var + ICV to the value specified in the argument. If the number of parallel + levels requested exceeds the number of levels of parallelism supported by + the implementation, the value of the max-active-levels-var ICV will be set + to the number of parallel levels supported by the implementation. This + routine has the described effect only when called from a sequential part + of the program. When called from within an explicit parallel region, the effect of this routine is implementation defined. - + Args: - + max_levels (:obj:`int`): The maximum number of nested active parallel regions. - + Returns: - + None. - + See Also: - + :meth:`wrf.omp_get_max_active_levels` - + """ - fomp_set_max_active_levels(max_levels) + fomp_set_max_active_levels(max_levels) def omp_get_max_active_levels(): """Return the value of the max-active-levels-var ICV, which determines \ the maximum number of nested active parallel regions on the device - - The omp_get_max_active_levels routine returns the value of the - max-active-levels-var ICV, which determines the maximum number of nested + + The omp_get_max_active_levels routine returns the value of the + max-active-levels-var ICV, which determines the maximum number of nested active parallel regions on the device. - + Returns: - + :obj:`int`: The maximum number of nested active parallel regions. - + See Also: - + :meth:`wrf.omp_set_max_active_levels` - + """ return fomp_get_max_active_levels() def omp_get_level(): """Return the value of the levels-var ICV. - - The effect of the omp_get_level routine is to return the number of nested - parallel regions (whether active or inactive) enclosing the current task - such that all of the parallel regions are enclosed by the outermost initial + + The effect of the omp_get_level routine is to return the number of nested + parallel regions (whether active or inactive) enclosing the current task + such that all of the parallel regions are enclosed by the outermost initial task region on the current device. - + Returns: - + :obj:`int`: The number of nested parallel regions. - + See Also: - + :meth:`wrf.omp_get_active_level` - + """ return fomp_get_level() - - + + def omp_get_ancestor_thread_num(level): """Return, for a given nested level of the current thread, the thread \ number of the ancestor of the current thread. - - The omp_get_ancestor_thread_num routine returns the thread number of the - ancestor at a given nest level of the current thread or the thread number - of the current thread. If the requested nest level is outside the range of - 0 and the nest level of the current thread, as returned by the + + The omp_get_ancestor_thread_num routine returns the thread number of the + ancestor at a given nest level of the current thread or the thread number + of the current thread. If the requested nest level is outside the range of + 0 and the nest level of the current thread, as returned by the omp_get_level routine, the routine returns -1. - + Args: - + level (:obj:`int`): The nested level of the current thread. - + Returns: - - :obj:`int`: The thread number of the ancestor at a given nest level + + :obj:`int`: The thread number of the ancestor at a given nest level of the current thread. - + See Also: - + :meth:`wrf.omp_get_max_active_levels`, :meth:`wrf.omp_get_level` - + """ return fomp_get_ancestor_thread_num(level) @@ -1387,270 +1393,267 @@ def omp_get_ancestor_thread_num(level): def omp_get_team_size(level): """Return, for a given nested level of the current thread, the size \ of the thread team to which the ancestor or the current thread belongs - - The omp_get_team_size routine returns the size of the thread team to which - the ancestor or the current thread belongs. If the requested nested level - is outside the range of 0 and the nested level of the current thread, as - returned by the omp_get_level routine, the routine returns -1. Inactive - parallel regions are regarded like active parallel regions executed with + + The omp_get_team_size routine returns the size of the thread team to which + the ancestor or the current thread belongs. If the requested nested level + is outside the range of 0 and the nested level of the current thread, as + returned by the omp_get_level routine, the routine returns -1. Inactive + parallel regions are regarded like active parallel regions executed with one thread. - + Args: - + level (:obj:`int`): The nested level of the current thread. - + Returns: - + :obj:`int`: The size of the thread team. - + See Also: - + :meth:`wrf.omp_get_ancestor_thread_num` - + """ return fomp_get_team_size(level) def omp_get_active_level(): """Return the value of the active-level-vars ICV. - - The effect of the omp_get_active_level routine is to return the number of - nested, active parallel regions enclosing the current task such that all - of the parallel regions are enclosed by the outermost initial task region + + The effect of the omp_get_active_level routine is to return the number of + nested, active parallel regions enclosing the current task such that all + of the parallel regions are enclosed by the outermost initial task region on the current device. - + Returns: - + :obj:`int`: The number of nested activate parallel regions. - + See Also: - + :meth:`wrf.omp_get_team_size` - + """ - return fomp_get_active_level() + return fomp_get_active_level() def omp_in_final(): """Return 1 (True) if the routine is executed in a final task region; \ otherwise, it returns 0 (False). - + Returns: - - :obj:`int`: Return 1 if the routine is executed in a final task + + :obj:`int`: Return 1 if the routine is executed in a final task region, 0 otherwise. - + """ return fomp_in_final() def omp_init_lock(): """Initialize a simple OpenMP lock. - + Returns: - + :obj:`int`: An integer representing the lock. - + See Also: - + :meth:`wrf.omp_init_nest_lock`, :meth:`wrf.omp_destroy_lock` - + """ return fomp_init_lock() def omp_init_nest_lock(): """Initialize a nestable OpenMP lock. - + Returns: - + :obj:`int`: An integer representing the nestable lock. - + See Also: - + :meth:`wrf.omp_init_lock` - + """ return fomp_init_nest_lock() def omp_destroy_lock(svar): """Destroy a simple OpenMP lock. - + This sets the lock to an uninitialized state. - + Args: - + svar (:obj:`int`): An integer representing the lock. - + See Also: - + :meth:`wrf.omp_destroy_nest_lock`, :meth:`wrf.omp_init_lock` - + """ fomp_destroy_lock(svar) def omp_destroy_nest_lock(nvar): """Destroy a nestable OpenMP lock. - + This sets the lock to an uninitialized state. - + Args: - + nvar (:obj:`int`): An integer representing the nestable lock. - + See Also: - + :meth:`wrf.omp_destroy_lock`, :meth:`wrf.omp_init_nest_lock` - + """ fomp_destroy_nest_lock(nvar) def omp_set_lock(svar): """Set a simple OpenMP lock. - + Args: - + svar (:obj:`int`): An integer representing the lock. - + See Also: - + :meth:`wrf.omp_unset_lock`, :meth:`wrf.omp_set_nest_lock` - + """ fomp_set_lock(svar) def omp_set_nest_lock(nvar): """Set a nestable OpenMP lock. - + Args: - + nvar (:obj:`int`): An integer representing the nestable lock. - + See Also: - + :meth:`wrf.omp_unset_nest_lock`, :meth:`wrf.omp_set_lock` - + """ fomp_set_nest_lock(nvar) def omp_unset_lock(svar): """Unset a simple OpenMP lock. - + Args: - + svar (:obj:`int`): An integer representing the simple lock. - + See Also: - + :meth:`wrf.omp_unset_nest_lock`, :meth:`wrf.omp_set_lock` - + """ fomp_unset_lock(svar) def omp_unset_nest_lock(nvar): """Unset a nestable OpenMP lock. - + Args: - + nvar (:obj:`int`): An integer representing the nestable lock. - + See Also: - + :meth:`wrf.omp_set_nest_lock`, :meth:`wrf.omp_unset_lock` - + """ fomp_unset_nest_lock(nvar) - + def omp_test_lock(svar): """Test a simple OpenMP lock. - + This method attempts to set the lock, but does not suspend execution. - + Args: - + svar (:obj:`int`): An integer representing the simple lock. - + Returns: - - :obj:`int`: Returns 1 (True) if the lock is successfully set, + + :obj:`int`: Returns 1 (True) if the lock is successfully set, otherwise 0 (False). - + See Also: - + :meth:`wrf.test_nest_lock`, :meth:`wrf.omp_set_lock` - + """ return fomp_test_lock(svar) def omp_test_nest_lock(nvar): """Test a nestable OpenMP lock. - + This method attempts to set the lock, but does not suspend execution. - + Args: - + nvar (:obj:`int`): An integer representing the simple lock. - + Returns: - - :obj:`int`: Returns the nesting count if successful, + + :obj:`int`: Returns the nesting count if successful, otherwise 0 (False). - + See Also: - + :meth:`wrf.test_lock`, :meth:`wrf.omp_set_nest_lock` - + """ return fomp_test_nest_lock(nvar) def omp_get_wtime(): """Return elapsed wall clock time in seconds. - - The omp_get_wtime routine returns a value equal to the elapsed wall clock - time in seconds since some "time in the past". The actual - "time in the past" is arbitrary, but it is guaranteed not to change during - the execution of the application program. The time returned is a - "per-thread time", so it is not required to be globally consistent across + + The omp_get_wtime routine returns a value equal to the elapsed wall clock + time in seconds since some "time in the past". The actual + "time in the past" is arbitrary, but it is guaranteed not to change during + the execution of the application program. The time returned is a + "per-thread time", so it is not required to be globally consistent across all threads participating in an application. - + Returns: - + :obj:`float`: Returns the wall clock time in seconds. - + See Also: - + :meth:`wrf.omp_get_wtick` - + """ return fomp_get_wtime() def omp_get_wtick(): """Return the precision of the timer used by :meth:`wrf.omp_get_wtime`. - - The omp_get_wtick routine returns a value equal to the number of - seconds between successive clock ticks of the timer used by + + The omp_get_wtick routine returns a value equal to the number of + seconds between successive clock ticks of the timer used by :meth:`wrf.omp_get_wtime`. - + Returns: - + :obj:`float`: Returns the precision of the timer. - + See Also: - + :meth:`wrf.omp_get_wtime` - + """ return fomp_get_wtick() - - - diff --git a/src/wrf/g_cape.py b/src/wrf/g_cape.py index d2ce0e7..e2f48c7 100755 --- a/src/wrf/g_cape.py +++ b/src/wrf/g_cape.py @@ -9,78 +9,79 @@ from .constants import default_fill, Constants, ConversionFactors from .util import extract_vars from .metadecorators import set_cape_metadata + @set_cape_metadata(is2d=True) -def get_2dcape(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, +def get_2dcape(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, missing=default_fill(np.float64)): """Return the two-dimensional fields of MCAPE, MCIN, LCL, and LFC. - - The leftmost dimension of the returned array represents four different + + The leftmost dimension of the returned array represents four different quantities: - + - return_val[0,...] will contain MCAPE [J kg-1] - return_val[1,...] will contain MCIN [J kg-1] - return_val[2,...] will contain LCL [m] - return_val[3,...] will contain LFC [m] - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - missing (:obj:`float`): The fill value to use for the output. + + missing (:obj:`float`): The fill value to use for the output. Default is :data:`wrf.default_fill(np.float64)`. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - cape, cin, lcl, and lfc values as an array whose - leftmost dimension is 4 (0=CAPE, 1=CIN, 2=LCL, 3=LFC). - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + cape, cin, lcl, and lfc values as an array whose + leftmost dimension is 4 (0=CAPE, 1=CIN, 2=LCL, 3=LFC). + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - varnames = ("T", "P", "PB", "QVAPOR", "PH","PHB", "HGT", "PSFC") + varnames = ("T", "P", "PB", "QVAPOR", "PH", "PHB", "HGT", "PSFC") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) - + t = ncvars["T"] p = ncvars["P"] pb = ncvars["PB"] @@ -89,107 +90,107 @@ def get_2dcape(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, phb = ncvars["PHB"] ter = ncvars["HGT"] psfc = ncvars["PSFC"] - + full_t = t + Constants.T_BASE full_p = p + pb tk = _tk(full_p, full_t) - + geopt = ph + phb geopt_unstag = destagger(geopt, -3) z = geopt_unstag/Constants.G - + # Convert pressure to hPa p_hpa = ConversionFactors.PA_TO_HPA * full_p - psfc_hpa = ConversionFactors.PA_TO_HPA * psfc - + psfc_hpa = ConversionFactors.PA_TO_HPA * psfc + i3dflag = 0 ter_follow = 1 - - cape_cin = _cape(p_hpa, tk, qv, z, ter, psfc_hpa, missing, i3dflag, + + cape_cin = _cape(p_hpa, tk, qv, z, ter, psfc_hpa, missing, i3dflag, ter_follow) - + left_dims = cape_cin.shape[1:-3] right_dims = cape_cin.shape[-2:] - + resdim = (4,) + left_dims + right_dims - + # Make a new output array for the result result = np.zeros(resdim, cape_cin.dtype) - - # Cape 2D output is not flipped in the vertical, so index from the + + # Cape 2D output is not flipped in the vertical, so index from the # end - result[0,...,:,:] = cape_cin[0,...,-1,:,:] - result[1,...,:,:] = cape_cin[1,...,-1,:,:] - result[2,...,:,:] = cape_cin[1,...,-2,:,:] - result[3,...,:,:] = cape_cin[1,...,-3,:,:] - + result[0, ..., :, :] = cape_cin[0, ..., -1, :, :] + result[1, ..., :, :] = cape_cin[1, ..., -1, :, :] + result[2, ..., :, :] = cape_cin[1, ..., -2, :, :] + result[3, ..., :, :] = cape_cin[1, ..., -3, :, :] + return ma.masked_values(result, missing) @set_cape_metadata(is2d=False) -def get_3dcape(wrfin, timeidx=0, method="cat", +def get_3dcape(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, missing=default_fill(np.float64)): """Return the three-dimensional CAPE and CIN. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain CAPE [J kg-1] - return_val[1,...] will contain CIN [J kg-1] - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - missing (:obj:`float`): The fill value to use for the output. + + missing (:obj:`float`): The fill value to use for the output. Default is :data:`wrf.default_fill(np.float64)`. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - CAPE and CIN as an array whose leftmost dimension is 2 (0=CAPE, 1=CIN). - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + CAPE and CIN as an array whose leftmost dimension is 2 (0=CAPE, 1=CIN). + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ varnames = ("T", "P", "PB", "QVAPOR", "PH", "PHB", "HGT", "PSFC") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, @@ -202,433 +203,429 @@ def get_3dcape(wrfin, timeidx=0, method="cat", phb = ncvars["PHB"] ter = ncvars["HGT"] psfc = ncvars["PSFC"] - + full_t = t + Constants.T_BASE full_p = p + pb tk = _tk(full_p, full_t) - + geopt = ph + phb geopt_unstag = destagger(geopt, -3) z = geopt_unstag/Constants.G - + # Convert pressure to hPa p_hpa = ConversionFactors.PA_TO_HPA * full_p - psfc_hpa = ConversionFactors.PA_TO_HPA * psfc - + psfc_hpa = ConversionFactors.PA_TO_HPA * psfc + i3dflag = 1 ter_follow = 1 - - cape_cin = _cape(p_hpa, tk, qv, z, ter, psfc_hpa, missing, i3dflag, + + cape_cin = _cape(p_hpa, tk, qv, z, ter, psfc_hpa, missing, i3dflag, ter_follow) - - + return ma.masked_values(cape_cin, missing) -def get_cape2d_only(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, - meta=True, _key=None, missing=default_fill(np.float64)): - """Return the two-dimensional field of MCAPE (Max Convective Available +def get_cape2d_only(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, + meta=True, _key=None, missing=default_fill(np.float64)): + """Return the two-dimensional field of MCAPE (Max Convective Available Potential Energy). - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - missing (:obj:`float`): The fill value to use for the output. + + missing (:obj:`float`): The fill value to use for the output. Default is :data:`wrf.default_fill(np.float64)`. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - 2D MCAPE field. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + 2D MCAPE field. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_2dcape(wrfin, timeidx, method, squeeze, cache, - meta, _key, missing)[0,:] - + result = get_2dcape(wrfin, timeidx, method, squeeze, cache, + meta, _key, missing)[0, :] + if meta: result.attrs["description"] = "mcape" result.attrs["units"] = "J kg-1" - + return result - - -def get_cin2d_only(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, - meta=True, _key=None, missing=default_fill(np.float64)): + + +def get_cin2d_only(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, + meta=True, _key=None, missing=default_fill(np.float64)): """Return the two-dimensional field of MCIN (Max Convective Inhibition). - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - missing (:obj:`float`): The fill value to use for the output. + + missing (:obj:`float`): The fill value to use for the output. Default is :data:`wrf.default_fill(np.float64)`. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - 2D MCIN field. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + 2D MCIN field. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_2dcape(wrfin, timeidx, method, squeeze, cache, - meta, _key, missing)[1,:] - + result = get_2dcape(wrfin, timeidx, method, squeeze, cache, + meta, _key, missing)[1, :] + if meta: result.attrs["description"] = "mcin" result.attrs["units"] = "J kg-1" - + return result - -def get_lcl(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, - meta=True, _key=None, missing=default_fill(np.float64)): + +def get_lcl(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, + meta=True, _key=None, missing=default_fill(np.float64)): """Return the two-dimensional field of LCL (Lifted Condensation Level). - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - missing (:obj:`float`): The fill value to use for the output. + + missing (:obj:`float`): The fill value to use for the output. Default is :data:`wrf.default_fill(np.float64)`. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - 2D LCL field. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + 2D LCL field. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_2dcape(wrfin, timeidx, method, squeeze, cache, - meta, _key, missing)[2,:] - + result = get_2dcape(wrfin, timeidx, method, squeeze, cache, + meta, _key, missing)[2, :] + if meta: result.attrs["description"] = "lcl" result.attrs["units"] = "m" - + return result - - -def get_lfc(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, - meta=True, _key=None, missing=default_fill(np.float64)): + + +def get_lfc(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, + meta=True, _key=None, missing=default_fill(np.float64)): """Return the two-dimensional field of LFC (Level of Free Convection). - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - missing (:obj:`float`): The fill value to use for the output. + + missing (:obj:`float`): The fill value to use for the output. Default is :data:`wrf.default_fill(np.float64)`. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - 2D LFC field. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + 2D LFC field. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_2dcape(wrfin, timeidx, method, squeeze, cache, - meta, _key, missing)[3,:] - + result = get_2dcape(wrfin, timeidx, method, squeeze, cache, + meta, _key, missing)[3, :] + if meta: result.attrs["description"] = "lfc" result.attrs["units"] = "m" - + return result - -def get_3dcape_only(wrfin, timeidx=0, method="cat", - squeeze=True, cache=None, meta=True, - _key=None, missing=default_fill(np.float64)): - """Return the three-dimensional field of CAPE (Convective Available + +def get_3dcape_only(wrfin, timeidx=0, method="cat", + squeeze=True, cache=None, meta=True, + _key=None, missing=default_fill(np.float64)): + """Return the three-dimensional field of CAPE (Convective Available Potential Energy). - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - missing (:obj:`float`): The fill value to use for the output. + + missing (:obj:`float`): The fill value to use for the output. Default is :data:`wrf.default_fill(np.float64)`. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - 3D CAPE field. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + 3D CAPE field. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ result = get_3dcape(wrfin, timeidx, method, squeeze, cache, meta, - _key, missing)[0,:] - + _key, missing)[0, :] + if meta: result.attrs["description"] = "cape" result.attrs["units"] = "J kg-1" - + return result - - -def get_3dcin_only(wrfin, timeidx=0, method="cat", - squeeze=True, cache=None, meta=True, - _key=None, missing=default_fill(np.float64)): + + +def get_3dcin_only(wrfin, timeidx=0, method="cat", + squeeze=True, cache=None, meta=True, + _key=None, missing=default_fill(np.float64)): """Return the three-dimensional field of CIN (Convective Inhibition). - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - missing (:obj:`float`): The fill value to use for the output. + + missing (:obj:`float`): The fill value to use for the output. Default is :data:`wrf.default_fill(np.float64)`. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - 3D CIN field. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + 3D CIN field. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ result = get_3dcape(wrfin, timeidx, method, squeeze, cache, meta, - _key, missing)[1,:] - + _key, missing)[1, :] + if meta: result.attrs["description"] = "cin" result.attrs["units"] = "J kg-1" - + return result - - - \ No newline at end of file diff --git a/src/wrf/g_cloudfrac.py b/src/wrf/g_cloudfrac.py index 49af329..c585b0f 100644 --- a/src/wrf/g_cloudfrac.py +++ b/src/wrf/g_cloudfrac.py @@ -11,142 +11,142 @@ from .g_geoht import _get_geoht @set_cloudfrac_metadata() -def get_cloudfrac(wrfin, timeidx=0, method="cat", squeeze=True, - cache=None, meta=True, _key=None, - vert_type="height_agl", low_thresh=None, mid_thresh=None, - high_thresh=None, missing=default_fill(np.float64)): +def get_cloudfrac(wrfin, timeidx=0, method="cat", squeeze=True, + cache=None, meta=True, _key=None, + vert_type="height_agl", low_thresh=None, mid_thresh=None, + high_thresh=None, missing=default_fill(np.float64)): """Return the cloud fraction for low, mid, and high level clouds. - - The leftmost dimension of the returned array represents three different + + The leftmost dimension of the returned array represents three different quantities: - + - return_val[0,...] will contain LOW level cloud fraction - return_val[1,...] will contain MID level cloud fraction - return_val[2,...] will contain HIGH level cloud fraction - - If the vertical coordinate type is 'height_agl' or 'height_msl', the + + If the vertical coordinate type is 'height_agl' or 'height_msl', the default cloud levels are defined as: - + 300 m <= low_cloud < 2000 m 2000 m <= mid_cloud < 6000 m 6000 m <= high_cloud - - For 'pressure', the default cloud levels are defined as: - + + For 'pressure', the default cloud levels are defined as: + 97000 Pa <= low_cloud < 80000 Pa 80000 Pa <= mid_cloud < 45000 Pa 45000 Pa <= high_cloud - + Note that the default low cloud levels are chosen to - exclude clouds near the surface (fog). If you want fog included, set - *low_thresh* to ~99500 Pa if *vert_type* is set to 'pressure', or 15 m if - using 'height_msl' or 'height_agl'. Keep in mind that the lowest mass grid - points are slightly above the ground, and in order to find clouds, the - *low_thresh* needs to be set to values that are slightly greater than + exclude clouds near the surface (fog). If you want fog included, set + *low_thresh* to ~99500 Pa if *vert_type* is set to 'pressure', or 15 m if + using 'height_msl' or 'height_agl'. Keep in mind that the lowest mass grid + points are slightly above the ground, and in order to find clouds, the + *low_thresh* needs to be set to values that are slightly greater than (less than) the lowest height (pressure) values. - - When using 'pressure' or 'height_agl' for *vert_type*, there is a - possibility that the lowest WRF level will be higher than the low_cloud or - mid_cloud threshold, particularly for mountainous regions. When this + + When using 'pressure' or 'height_agl' for *vert_type*, there is a + possibility that the lowest WRF level will be higher than the low_cloud or + mid_cloud threshold, particularly for mountainous regions. When this happens, a fill value will be used in the output. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - vert_type (:obj:`str`, optional): The type of vertical coordinate used - to determine cloud type thresholds. Must be 'height_agl', + + vert_type (:obj:`str`, optional): The type of vertical coordinate used + to determine cloud type thresholds. Must be 'height_agl', 'height_msl', or 'pres'. The default is 'height_agl'. - - low_thresh (:obj:`float`, optional): The lower bound for what is - considered a low cloud. If *vert_type* is 'pres', the default is - 97000 Pa. If *vert_type* is 'height_agl' or 'height_msl', then the - default is 300 m. - - mid_thresh (:obj:`float`, optional): The lower bound for what is - considered a mid level cloud. If *vert_type* is 'pres', the - default is 80000 Pa. If *vert_type* is 'height_agl' or - 'height_msl', then the default is 2000 m. - - high_thresh (:obj:`float`, optional): The lower bound for what is - considered a high level cloud. If *vert_type* is 'pres', the - default is 45000 Pa. If *vert_type* is 'height_agl' or - 'height_msl', then the default is 6000 m. - + + low_thresh (:obj:`float`, optional): The lower bound for what is + considered a low cloud. If *vert_type* is 'pres', the default is + 97000 Pa. If *vert_type* is 'height_agl' or 'height_msl', then the + default is 300 m. + + mid_thresh (:obj:`float`, optional): The lower bound for what is + considered a mid level cloud. If *vert_type* is 'pres', the + default is 80000 Pa. If *vert_type* is 'height_agl' or + 'height_msl', then the default is 2000 m. + + high_thresh (:obj:`float`, optional): The lower bound for what is + considered a high level cloud. If *vert_type* is 'pres', the + default is 45000 Pa. If *vert_type* is 'height_agl' or + 'height_msl', then the default is 6000 m. + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - cloud fraction array whose leftmost dimension is 3 (LOW=0, MID=1, - HIGH=2). - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + cloud fraction array whose leftmost dimension is 3 (LOW=0, MID=1, + HIGH=2). + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - - ncvars = extract_vars(wrfin, timeidx, ("P", "PB", "QVAPOR", "T"), + + ncvars = extract_vars(wrfin, timeidx, ("P", "PB", "QVAPOR", "T"), method, squeeze, cache, meta=False, _key=_key) - + p = ncvars["P"] pb = ncvars["PB"] qv = ncvars["QVAPOR"] t = ncvars["T"] - + full_p = p + pb full_t = t + Constants.T_BASE - + tk = _tk(full_p, full_t) rh = _rh(qv, full_p, tk) - + if vert_type.lower() == "pres" or vert_type.lower() == "pressure": v_coord = full_p _low_thresh = 97000. if low_thresh is None else low_thresh _mid_thresh = 80000. if mid_thresh is None else mid_thresh _high_thresh = 45000. if high_thresh is None else high_thresh vert_inc_w_height = 0 - elif (vert_type.lower() == "height_msl" + elif (vert_type.lower() == "height_msl" or vert_type.lower() == "height_agl"): is_msl = vert_type.lower() == "height_msl" - v_coord = _get_geoht(wrfin, timeidx, method, squeeze, - cache, meta=False, _key=_key, height=True, + v_coord = _get_geoht(wrfin, timeidx, method, squeeze, + cache, meta=False, _key=_key, height=True, msl=is_msl) _low_thresh = 300. if low_thresh is None else low_thresh _mid_thresh = 2000. if mid_thresh is None else mid_thresh @@ -155,344 +155,346 @@ def get_cloudfrac(wrfin, timeidx=0, method="cat", squeeze=True, else: raise ValueError("'vert_type' must be 'pres', 'height_msl', " "or 'height_agl'") - - cfrac = _cloudfrac(v_coord, rh, vert_inc_w_height, - _low_thresh, _mid_thresh, _high_thresh, missing) - + + cfrac = _cloudfrac(v_coord, rh, vert_inc_w_height, + _low_thresh, _mid_thresh, _high_thresh, missing) + return ma.masked_values(cfrac, missing) -def get_low_cloudfrac(wrfin, timeidx=0, method="cat", squeeze=True, - cache=None, meta=True, _key=None, - vert_type="height_agl", low_thresh=None, mid_thresh=None, - high_thresh=None, missing=default_fill(np.float64)): +def get_low_cloudfrac(wrfin, timeidx=0, method="cat", squeeze=True, + cache=None, meta=True, _key=None, + vert_type="height_agl", low_thresh=None, + mid_thresh=None, high_thresh=None, + missing=default_fill(np.float64)): """Return the cloud fraction for the low level clouds. - - If the vertical coordinate type is 'height_agl' or 'height_msl', the + + If the vertical coordinate type is 'height_agl' or 'height_msl', the default cloud levels are defined as: - + 300 m <= low_cloud < 2000 m 2000 m <= mid_cloud < 6000 m 6000 m <= high_cloud - - For 'pressure', the default cloud levels are defined as: - + + For 'pressure', the default cloud levels are defined as: + 97000 Pa <= low_cloud < 80000 Pa 80000 Pa <= mid_cloud < 45000 Pa 45000 Pa <= high_cloud - + Note that the default low cloud levels are chosen to - exclude clouds near the surface (fog). If you want fog included, set - *low_thresh* to ~99500 Pa if *vert_type* is set to 'pressure', or 15 m if - using 'height_msl' or 'height_agl'. Keep in mind that the lowest mass grid - points are slightly above the ground, and in order to find clouds, the - *low_thresh* needs to be set to values that are slightly greater than + exclude clouds near the surface (fog). If you want fog included, set + *low_thresh* to ~99500 Pa if *vert_type* is set to 'pressure', or 15 m if + using 'height_msl' or 'height_agl'. Keep in mind that the lowest mass grid + points are slightly above the ground, and in order to find clouds, the + *low_thresh* needs to be set to values that are slightly greater than (less than) the lowest height (pressure) values. - - When using 'pressure' or 'height_agl' for *vert_type*, there is a - possibility that the lowest WRF level will be higher than the low_cloud or - mid_cloud threshold, particularly for mountainous regions. When this + + When using 'pressure' or 'height_agl' for *vert_type*, there is a + possibility that the lowest WRF level will be higher than the low_cloud or + mid_cloud threshold, particularly for mountainous regions. When this happens, a fill value will be used in the output. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - vert_type (:obj:`str`, optional): The type of vertical coordinate used - to determine cloud type thresholds. Must be 'height_agl', + + vert_type (:obj:`str`, optional): The type of vertical coordinate used + to determine cloud type thresholds. Must be 'height_agl', 'height_msl', or 'pres'. The default is 'height_agl'. - - low_thresh (:obj:`float`, optional): The lower bound for what is - considered a low cloud. If *vert_type* is 'pres', the default is - 97000 Pa. If *vert_type* is 'height_agl' or 'height_msl', then the - default is 300 m. - - mid_thresh (:obj:`float`, optional): The lower bound for what is - considered a mid level cloud. If *vert_type* is 'pres', the - default is 80000 Pa. If *vert_type* is 'height_agl' or - 'height_msl', then the default is 2000 m. - - high_thresh (:obj:`float`, optional): The lower bound for what is - considered a high level cloud. If *vert_type* is 'pres', the - default is 45000 Pa. If *vert_type* is 'height_agl' or - 'height_msl', then the default is 6000 m. - + + low_thresh (:obj:`float`, optional): The lower bound for what is + considered a low cloud. If *vert_type* is 'pres', the default is + 97000 Pa. If *vert_type* is 'height_agl' or 'height_msl', then the + default is 300 m. + + mid_thresh (:obj:`float`, optional): The lower bound for what is + considered a mid level cloud. If *vert_type* is 'pres', the + default is 80000 Pa. If *vert_type* is 'height_agl' or + 'height_msl', then the default is 2000 m. + + high_thresh (:obj:`float`, optional): The lower bound for what is + considered a high level cloud. If *vert_type* is 'pres', the + default is 45000 Pa. If *vert_type* is 'height_agl' or + 'height_msl', then the default is 6000 m. + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - cloud fraction array for low level clouds. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + cloud fraction array for low level clouds. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_cloudfrac(wrfin, timeidx, method, squeeze, - cache, meta, _key, - vert_type, low_thresh, mid_thresh, - high_thresh, missing)[0,:] - + result = get_cloudfrac(wrfin, timeidx, method, squeeze, + cache, meta, _key, vert_type, low_thresh, + mid_thresh, high_thresh, missing)[0, :] + if meta: result.attrs["description"] = "low clouds" - + return result - - -def get_mid_cloudfrac(wrfin, timeidx=0, method="cat", squeeze=True, - cache=None, meta=True, _key=None, - vert_type="height_agl", low_thresh=None, mid_thresh=None, - high_thresh=None, missing=default_fill(np.float64)): + + +def get_mid_cloudfrac(wrfin, timeidx=0, method="cat", squeeze=True, + cache=None, meta=True, _key=None, + vert_type="height_agl", low_thresh=None, + mid_thresh=None, high_thresh=None, + missing=default_fill(np.float64)): """Return the cloud fraction for the mid level clouds. - - If the vertical coordinate type is 'height_agl' or 'height_msl', the + + If the vertical coordinate type is 'height_agl' or 'height_msl', the default cloud levels are defined as: - + 300 m <= low_cloud < 2000 m 2000 m <= mid_cloud < 6000 m 6000 m <= high_cloud - - For 'pressure', the default cloud levels are defined as: - + + For 'pressure', the default cloud levels are defined as: + 97000 Pa <= low_cloud < 80000 Pa 80000 Pa <= mid_cloud < 45000 Pa 45000 Pa <= high_cloud - + Note that the default low cloud levels are chosen to - exclude clouds near the surface (fog). If you want fog included, set - *low_thresh* to ~99500 Pa if *vert_type* is set to 'pressure', or 15 m if - using 'height_msl' or 'height_agl'. Keep in mind that the lowest mass grid - points are slightly above the ground, and in order to find clouds, the - *low_thresh* needs to be set to values that are slightly greater than + exclude clouds near the surface (fog). If you want fog included, set + *low_thresh* to ~99500 Pa if *vert_type* is set to 'pressure', or 15 m if + using 'height_msl' or 'height_agl'. Keep in mind that the lowest mass grid + points are slightly above the ground, and in order to find clouds, the + *low_thresh* needs to be set to values that are slightly greater than (less than) the lowest height (pressure) values. - - When using 'pressure' or 'height_agl' for *vert_type*, there is a - possibility that the lowest WRF level will be higher than the low_cloud or - mid_cloud threshold, particularly for mountainous regions. When this + + When using 'pressure' or 'height_agl' for *vert_type*, there is a + possibility that the lowest WRF level will be higher than the low_cloud or + mid_cloud threshold, particularly for mountainous regions. When this happens, a fill value will be used in the output. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - vert_type (:obj:`str`, optional): The type of vertical coordinate used - to determine cloud type thresholds. Must be 'height_agl', + + vert_type (:obj:`str`, optional): The type of vertical coordinate used + to determine cloud type thresholds. Must be 'height_agl', 'height_msl', or 'pres'. The default is 'height_agl'. - - low_thresh (:obj:`float`, optional): The lower bound for what is - considered a low cloud. If *vert_type* is 'pres', the default is - 97000 Pa. If *vert_type* is 'height_agl' or 'height_msl', then the - default is 300 m. - - mid_thresh (:obj:`float`, optional): The lower bound for what is - considered a mid level cloud. If *vert_type* is 'pres', the - default is 80000 Pa. If *vert_type* is 'height_agl' or - 'height_msl', then the default is 2000 m. - - high_thresh (:obj:`float`, optional): The lower bound for what is - considered a high level cloud. If *vert_type* is 'pres', the - default is 45000 Pa. If *vert_type* is 'height_agl' or - 'height_msl', then the default is 6000 m. - + + low_thresh (:obj:`float`, optional): The lower bound for what is + considered a low cloud. If *vert_type* is 'pres', the default is + 97000 Pa. If *vert_type* is 'height_agl' or 'height_msl', then the + default is 300 m. + + mid_thresh (:obj:`float`, optional): The lower bound for what is + considered a mid level cloud. If *vert_type* is 'pres', the + default is 80000 Pa. If *vert_type* is 'height_agl' or + 'height_msl', then the default is 2000 m. + + high_thresh (:obj:`float`, optional): The lower bound for what is + considered a high level cloud. If *vert_type* is 'pres', the + default is 45000 Pa. If *vert_type* is 'height_agl' or + 'height_msl', then the default is 6000 m. + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - cloud fraction array for mid level clouds. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + cloud fraction array for mid level clouds. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_cloudfrac(wrfin, timeidx, method, squeeze, - cache, meta, _key, - vert_type, low_thresh, mid_thresh, - high_thresh, missing)[1,:] - + result = get_cloudfrac(wrfin, timeidx, method, squeeze, + cache, meta, _key, + vert_type, low_thresh, mid_thresh, + high_thresh, missing)[1, :] + if meta: result.attrs["description"] = "mid clouds" - + return result - - -def get_high_cloudfrac(wrfin, timeidx=0, method="cat", squeeze=True, - cache=None, meta=True, _key=None, - vert_type="height_agl", low_thresh=None, mid_thresh=None, - high_thresh=None, missing=default_fill(np.float64)): + + +def get_high_cloudfrac(wrfin, timeidx=0, method="cat", squeeze=True, + cache=None, meta=True, _key=None, + vert_type="height_agl", low_thresh=None, + mid_thresh=None, high_thresh=None, + missing=default_fill(np.float64)): """Return the cloud fraction for the high level clouds. - - If the vertical coordinate type is 'height_agl' or 'height_msl', the + + If the vertical coordinate type is 'height_agl' or 'height_msl', the default cloud levels are defined as: - + 300 m <= low_cloud < 2000 m 2000 m <= mid_cloud < 6000 m 6000 m <= high_cloud - - For 'pressure', the default cloud levels are defined as: - + + For 'pressure', the default cloud levels are defined as: + 97000 Pa <= low_cloud < 80000 Pa 80000 Pa <= mid_cloud < 45000 Pa 45000 Pa <= high_cloud - + Note that the default low cloud levels are chosen to - exclude clouds near the surface (fog). If you want fog included, set - *low_thresh* to ~99500 Pa if *vert_type* is set to 'pressure', or 15 m if - using 'height_msl' or 'height_agl'. Keep in mind that the lowest mass grid - points are slightly above the ground, and in order to find clouds, the - *low_thresh* needs to be set to values that are slightly greater than + exclude clouds near the surface (fog). If you want fog included, set + *low_thresh* to ~99500 Pa if *vert_type* is set to 'pressure', or 15 m if + using 'height_msl' or 'height_agl'. Keep in mind that the lowest mass grid + points are slightly above the ground, and in order to find clouds, the + *low_thresh* needs to be set to values that are slightly greater than (less than) the lowest height (pressure) values. - - When using 'pressure' or 'height_agl' for *vert_type*, there is a - possibility that the lowest WRF level will be higher than the low_cloud or - mid_cloud threshold, particularly for mountainous regions. When this + + When using 'pressure' or 'height_agl' for *vert_type*, there is a + possibility that the lowest WRF level will be higher than the low_cloud or + mid_cloud threshold, particularly for mountainous regions. When this happens, a fill value will be used in the output. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - vert_type (:obj:`str`, optional): The type of vertical coordinate used - to determine cloud type thresholds. Must be 'height_agl', + + vert_type (:obj:`str`, optional): The type of vertical coordinate used + to determine cloud type thresholds. Must be 'height_agl', 'height_msl', or 'pres'. The default is 'height_agl'. - - low_thresh (:obj:`float`, optional): The lower bound for what is - considered a low cloud. If *vert_type* is 'pres', the default is - 97000 Pa. If *vert_type* is 'height_agl' or 'height_msl', then the - default is 300 m. - - mid_thresh (:obj:`float`, optional): The lower bound for what is - considered a mid level cloud. If *vert_type* is 'pres', the - default is 80000 Pa. If *vert_type* is 'height_agl' or - 'height_msl', then the default is 2000 m. - - high_thresh (:obj:`float`, optional): The lower bound for what is - considered a high level cloud. If *vert_type* is 'pres', the - default is 45000 Pa. If *vert_type* is 'height_agl' or - 'height_msl', then the default is 6000 m. - + + low_thresh (:obj:`float`, optional): The lower bound for what is + considered a low cloud. If *vert_type* is 'pres', the default is + 97000 Pa. If *vert_type* is 'height_agl' or 'height_msl', then the + default is 300 m. + + mid_thresh (:obj:`float`, optional): The lower bound for what is + considered a mid level cloud. If *vert_type* is 'pres', the + default is 80000 Pa. If *vert_type* is 'height_agl' or + 'height_msl', then the default is 2000 m. + + high_thresh (:obj:`float`, optional): The lower bound for what is + considered a high level cloud. If *vert_type* is 'pres', the + default is 45000 Pa. If *vert_type* is 'height_agl' or + 'height_msl', then the default is 6000 m. + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - cloud fraction array for high level clouds. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + cloud fraction array for high level clouds. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_cloudfrac(wrfin, timeidx, method, squeeze, - cache, meta, _key, - vert_type, low_thresh, mid_thresh, - high_thresh, missing)[2,:] - + result = get_cloudfrac(wrfin, timeidx, method, squeeze, + cache, meta, _key, + vert_type, low_thresh, mid_thresh, + high_thresh, missing)[2, :] + if meta: result.attrs["description"] = "high clouds" - + return result diff --git a/src/wrf/g_ctt.py b/src/wrf/g_ctt.py index 1003a4e..aa339a7 100644 --- a/src/wrf/g_ctt.py +++ b/src/wrf/g_ctt.py @@ -3,11 +3,10 @@ from __future__ import (absolute_import, division, print_function) import numpy as np import numpy.ma as ma -#from .extension import computectt, computetk from .extension import _ctt, _tk from .constants import Constants, ConversionFactors, default_fill from .destag import destagger -from .decorators import convert_units +from .decorators import convert_units from .metadecorators import copy_and_set_metadata from .util import extract_vars @@ -17,86 +16,86 @@ from .util import extract_vars description="cloud top temperature", MemoryOrder="XY") @convert_units("temp", "c") -def get_ctt(wrfin, timeidx=0, method="cat", +def get_ctt(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, - fill_nocloud=False, missing=default_fill(np.float64), + fill_nocloud=False, missing=default_fill(np.float64), opt_thresh=1.0, units="degC"): """Return the cloud top temperature. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - fill_nocloud (:obj:`bool`, optional): Set to True to use fill values in - regions where clouds are not detected (optical depth less than 1). - Otherwise, the output will contain the surface temperature for + + fill_nocloud (:obj:`bool`, optional): Set to True to use fill values in + regions where clouds are not detected (optical depth less than 1). + Otherwise, the output will contain the surface temperature for areas without clouds. Default is False. - - missing (:obj:`float`, optional): The fill value to use for areas - where no clouds are detected. Only used if *fill_nocloud* is - True. Default is - :data:`wrf.default_fill(numpy.float64)`. - - opt_thresh (:obj:`float`, optional): The amount of optical - depth (integrated from top down) required to trigger a cloud top - temperature calculation. The cloud top temperature is calculated at - the vertical level where this threshold is met. Vertical columns - with less than this threshold will be treated as cloud free areas. - In general, the larger the value is for this - threshold, the lower the altitude will be for the cloud top - temperature calculation, and therefore higher cloud top - temperature values. Default is 1.0, which should be sufficient for + + missing (:obj:`float`, optional): The fill value to use for areas + where no clouds are detected. Only used if *fill_nocloud* is + True. Default is + :data:`wrf.default_fill(numpy.float64)`. + + opt_thresh (:obj:`float`, optional): The amount of optical + depth (integrated from top down) required to trigger a cloud top + temperature calculation. The cloud top temperature is calculated at + the vertical level where this threshold is met. Vertical columns + with less than this threshold will be treated as cloud free areas. + In general, the larger the value is for this + threshold, the lower the altitude will be for the cloud top + temperature calculation, and therefore higher cloud top + temperature values. Default is 1.0, which should be sufficient for most users. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'ctt'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'ctt'. Default is 'degC'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The cloud top temperature. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ varnames = ("T", "P", "PB", "PH", "PHB", "HGT", "QVAPOR") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, @@ -107,40 +106,40 @@ def get_ctt(wrfin, timeidx=0, method="cat", ph = ncvars["PH"] phb = ncvars["PHB"] ter = ncvars["HGT"] - qv = ncvars["QVAPOR"] * 1000.0 # g/kg - + qv = ncvars["QVAPOR"] * 1000.0 # g/kg + haveqci = 1 try: - icevars = extract_vars(wrfin, timeidx, "QICE", + icevars = extract_vars(wrfin, timeidx, "QICE", method, squeeze, cache, meta=False, _key=_key) except KeyError: qice = np.zeros(qv.shape, qv.dtype) haveqci = 0 else: - qice = icevars["QICE"] * 1000.0 #g/kg - + qice = icevars["QICE"] * 1000.0 # g/kg + try: - cldvars = extract_vars(wrfin, timeidx, "QCLOUD", + cldvars = extract_vars(wrfin, timeidx, "QCLOUD", method, squeeze, cache, meta=False, _key=_key) except KeyError: raise RuntimeError("'QCLOUD' not found in NetCDF file") else: - qcld = cldvars["QCLOUD"] * 1000.0 #g/kg - + qcld = cldvars["QCLOUD"] * 1000.0 # g/kg + full_p = p + pb p_hpa = full_p * ConversionFactors.PA_TO_HPA full_t = t + Constants.T_BASE tk = _tk(full_p, full_t) - + geopt = ph + phb geopt_unstag = destagger(geopt, -3) ght = geopt_unstag / Constants.G - + _fill_nocloud = 1 if fill_nocloud else 0 - + ctt = _ctt(p_hpa, tk, qice, qcld, qv, ght, ter, haveqci, _fill_nocloud, missing, opt_thresh) - + return ma.masked_values(ctt, missing) diff --git a/src/wrf/g_dbz.py b/src/wrf/g_dbz.py index 77b2523..caae9ef 100755 --- a/src/wrf/g_dbz.py +++ b/src/wrf/g_dbz.py @@ -2,82 +2,81 @@ from __future__ import (absolute_import, division, print_function) import numpy as np -#from .extension import computedbz,computetk from .extension import _dbz, _tk from .constants import Constants from .util import extract_vars, to_np from .metadecorators import copy_and_set_metadata -@copy_and_set_metadata(copy_varname="T", name="dbz", +@copy_and_set_metadata(copy_varname="T", name="dbz", description="radar reflectivity", units="dBZ") -def get_dbz(wrfin, timeidx=0, method="cat", +def get_dbz(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, use_varint=False, use_liqskin=False): """Return the simulated radar reflectivity. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - use_varint (:obj:`bool`, optional): When set to False, - the intercept parameters are assumed constant - (as in MM5's Reisner-2 bulk microphysical scheme). - When set to True, the variable intercept - parameters are used as in the more recent version of Reisner-2 - (based on Thompson, Rasmussen, and Manning, 2004, Monthly weather - Review, Vol. 132, No. 2, pp. 519-542.). - - use_liqskin (:obj:`bool`, optional): When set to True, frozen particles - that are at a temperature above freezing are assumed to scatter + + use_varint (:obj:`bool`, optional): When set to False, + the intercept parameters are assumed constant + (as in MM5's Reisner-2 bulk microphysical scheme). + When set to True, the variable intercept + parameters are used as in the more recent version of Reisner-2 + (based on Thompson, Rasmussen, and Manning, 2004, Monthly weather + Review, Vol. 132, No. 2, pp. 519-542.). + + use_liqskin (:obj:`bool`, optional): When set to True, frozen particles + that are at a temperature above freezing are assumed to scatter as a liquid particle. Set to False to disable. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The simulated - radar reflectivity. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The simulated + radar reflectivity. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ varnames = ("T", "P", "PB", "QVAPOR", "QRAIN") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, @@ -87,113 +86,112 @@ def get_dbz(wrfin, timeidx=0, method="cat", pb = ncvars["PB"] qv = ncvars["QVAPOR"] qr = ncvars["QRAIN"] - + try: - snowvars = extract_vars(wrfin, timeidx, "QSNOW", + snowvars = extract_vars(wrfin, timeidx, "QSNOW", method, squeeze, cache, meta=False, _key=_key) except KeyError: qs = np.zeros(qv.shape, qv.dtype) else: qs = snowvars["QSNOW"] - + try: - graupvars = extract_vars(wrfin, timeidx, "QGRAUP", + graupvars = extract_vars(wrfin, timeidx, "QGRAUP", method, squeeze, cache, meta=False, _key=_key) except KeyError: qg = np.zeros(qv.shape, qv.dtype) else: qg = graupvars["QGRAUP"] - + full_t = t + Constants.T_BASE full_p = p + pb tk = _tk(full_p, full_t) - + # If qsnow is not all 0, set sn0 to 1 sn0 = 1 if qs.any() else 0 ivarint = 1 if use_varint else 0 iliqskin = 1 if use_liqskin else 0 - + return _dbz(full_p, tk, qv, qr, qs, qg, sn0, ivarint, iliqskin) -@copy_and_set_metadata(copy_varname="T", name="max_dbz", +@copy_and_set_metadata(copy_varname="T", name="max_dbz", remove_dims=("bottom_top",), description="maximum radar reflectivity", units="dBZ", MemoryOrder="XY") -def get_max_dbz(wrfin, timeidx=0, method="cat", +def get_max_dbz(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, use_varint=False, use_liqskin=False): """Return the maximum simulated radar reflectivity. - - This function returns the maximum reflectivity found in the column for + + This function returns the maximum reflectivity found in the column for each grid point. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - use_varint (:obj:`bool`, optional): When set to False, - the intercept parameters are assumed constant - (as in MM5's Reisner-2 bulk microphysical scheme). - When set to True, the variable intercept - parameters are used as in the more recent version of Reisner-2 - (based on Thompson, Rasmussen, and Manning, 2004, Monthly weather - Review, Vol. 132, No. 2, pp. 519-542.). - - use_liqskin (:obj:`bool`, optional): When set to True, frozen particles - that are at a temperature above freezing are assumed to scatter + + use_varint (:obj:`bool`, optional): When set to False, + the intercept parameters are assumed constant + (as in MM5's Reisner-2 bulk microphysical scheme). + When set to True, the variable intercept + parameters are used as in the more recent version of Reisner-2 + (based on Thompson, Rasmussen, and Manning, 2004, Monthly weather + Review, Vol. 132, No. 2, pp. 519-542.). + + use_liqskin (:obj:`bool`, optional): When set to True, frozen particles + that are at a temperature above freezing are assumed to scatter as a liquid particle. Set to False to disable. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The maximum - simulated radar reflectivity. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The maximum + simulated radar reflectivity. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ return np.amax(to_np(get_dbz(wrfin, timeidx, method, squeeze, cache, meta, - _key, use_varint, use_liqskin)), - axis=-3) - + _key, use_varint, use_liqskin)), + axis=-3) diff --git a/src/wrf/g_dewpoint.py b/src/wrf/g_dewpoint.py index 57cd656..bf9fed2 100755 --- a/src/wrf/g_dewpoint.py +++ b/src/wrf/g_dewpoint.py @@ -1,164 +1,163 @@ from __future__ import (absolute_import, division, print_function) -#from .extension import computetd from .extension import _td from .decorators import convert_units from .metadecorators import copy_and_set_metadata from .util import extract_vars -@copy_and_set_metadata(copy_varname="QVAPOR", name="td", +@copy_and_set_metadata(copy_varname="QVAPOR", name="td", description="dew point temperature") @convert_units("temp", "c") -def get_dp(wrfin, timeidx=0, method="cat", squeeze=True, +def get_dp(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="degC"): """Return the dewpoint temperature. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'td'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'td'. Default is 'degC'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The dewpoint temperature. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - - varnames=("P", "PB", "QVAPOR") + + varnames = ("P", "PB", "QVAPOR") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) - + p = ncvars["P"] pb = ncvars["PB"] - # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to + # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to # break with every release qvapor = ncvars["QVAPOR"].copy() - + # Algorithm requires hPa full_p = .01*(p + pb) qvapor[qvapor < 0] = 0 - + td = _td(full_p, qvapor) return td -@copy_and_set_metadata(copy_varname="Q2", name="td2", + +@copy_and_set_metadata(copy_varname="Q2", name="td2", description="2m dew point temperature") @convert_units("temp", "c") -def get_dp_2m(wrfin, timeidx=0, method="cat", squeeze=True, +def get_dp_2m(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="degC"): """Return the 2m dewpoint temperature. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'td2'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'td2'. Default is 'degC'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The 2m dewpoint temperature. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - varnames=("PSFC", "Q2") + varnames = ("PSFC", "Q2") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) # Algorithm requires hPa psfc = .01*(ncvars["PSFC"]) - # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to + # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to # break with every release q2 = ncvars["Q2"].copy() q2[q2 < 0] = 0 - + td = _td(psfc, q2) - - return td + return td diff --git a/src/wrf/g_geoht.py b/src/wrf/g_geoht.py index 6b041ef..7e78e5a 100755 --- a/src/wrf/g_geoht.py +++ b/src/wrf/g_geoht.py @@ -8,79 +8,80 @@ from .decorators import convert_units from .metadecorators import set_height_metadata from .util import extract_vars, either -def _get_geoht(wrfin, timeidx, method="cat", squeeze=True, + +def _get_geoht(wrfin, timeidx, method="cat", squeeze=True, cache=None, meta=True, _key=None, height=True, msl=True, stag=False): """Return the geopotential or geopotential height. - - If *height* is False, then geopotential is returned in units of - [m2 s-2]. If *height* is True, then geopotential height is - returned in units of [m]. If *msl* is True, then geopotential height - is return as Mean Sea Level (MSL). If *msl* is False, then geopotential + + If *height* is False, then geopotential is returned in units of + [m2 s-2]. If *height* is True, then geopotential height is + returned in units of [m]. If *msl* is True, then geopotential height + is return as Mean Sea Level (MSL). If *msl* is False, then geopotential height is returned as Above Ground Level (AGL). - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - height (:obj:`bool`, optional): Set to True to return geopotential + + height (:obj:`bool`, optional): Set to True to return geopotential height instead of geopotential. Default is True. - + msl (:obj:`bool`, optional): Set to True to return geopotential height - as Mean Sea Level (MSL). Set to False to return the - geopotential height as Above Ground Level (AGL) by subtracting + as Mean Sea Level (MSL). Set to False to return the + geopotential height as Above Ground Level (AGL) by subtracting the terrain height. Default is True. - - stag (:obj:`bool`, optional): Set to True to use the vertical + + stag (:obj:`bool`, optional): Set to True to use the vertical staggered grid, rather than the mass grid. Default is False. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The geopotential or geopotential height. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - + varname = either("PH", "GHT")(wrfin) if varname == "PH": ph_vars = extract_vars(wrfin, timeidx, ("PH", "PHB", "HGT"), @@ -100,11 +101,11 @@ def _get_geoht(wrfin, timeidx, method="cat", squeeze=True, _key=_key) geopt_unstag = ght_vars["GHT"] * Constants.G hgt = ght_vars["HGT_M"] - + if stag: warnings.warn("file contains no vertically staggered geopotential " "height variable, returning unstaggered result " - "instead" ) + "instead") if height: if msl: return geopt_unstag / Constants.G @@ -113,70 +114,70 @@ def _get_geoht(wrfin, timeidx, method="cat", squeeze=True, # array needs to be reshaped to a 3D array so the right dims # line up new_dims = list(hgt.shape) - new_dims.insert(-2,1) + new_dims.insert(-2, 1) hgt = hgt.reshape(new_dims) - + return (geopt_unstag / Constants.G) - hgt else: return geopt_unstag @set_height_metadata(geopt=True, stag=False) -def get_geopt(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, +def get_geopt(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return the geopotential. - + The geopotential is returned in units of [m2 s-2]. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The geopotential. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ return _get_geoht(wrfin, timeidx, method, squeeze, cache, meta, _key, False, True) @@ -184,135 +185,135 @@ def get_geopt(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, @set_height_metadata(geopt=False, stag=False) @convert_units("height", "m") -def get_height(wrfin, timeidx=0, method="cat", squeeze=True, +def get_height(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, msl=True, units="m"): """Return the geopotential height. - - If *msl* is True, then geopotential height is returned as Mean Sea Level - (MSL). If *msl* is False, then geopotential height is returned as + + If *msl* is True, then geopotential height is returned as Mean Sea Level + (MSL). If *msl* is False, then geopotential height is returned as Above Ground Level (AGL) by subtracting the terrain height. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + msl (:obj:`bool`, optional): Set to True to return geopotential height - as Mean Sea Level (MSL). Set to False to return the - geopotential height as Above Ground Level (AGL) by subtracting + as Mean Sea Level (MSL). Set to False to return the + geopotential height as Above Ground Level (AGL) by subtracting the terrain height. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'z'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'z'. Default is 'm'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The geopotential height. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - + return _get_geoht(wrfin, timeidx, method, squeeze, cache, meta, _key, True, msl) @set_height_metadata(geopt=True, stag=True) -def get_stag_geopt(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, - meta=True, _key=None): +def get_stag_geopt(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, + meta=True, _key=None): """Return the geopotential for the vertically staggered grid. - + The geopotential is returned in units of [m2 s-2]. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The geopotential. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ return _get_geoht(wrfin, timeidx, method, squeeze, cache, meta, _key, False, True, stag=True) @@ -320,75 +321,73 @@ def get_stag_geopt(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, @set_height_metadata(geopt=False, stag=True) @convert_units("height", "m") -def get_stag_height(wrfin, timeidx=0, method="cat", squeeze=True, - cache=None, meta=True, _key=None, - msl=True, units="m"): +def get_stag_height(wrfin, timeidx=0, method="cat", squeeze=True, + cache=None, meta=True, _key=None, msl=True, units="m"): """Return the geopotential height for the vertically staggered grid. - - If *msl* is True, then geopotential height is returned as Mean Sea Level - (MSL). If *msl* is False, then geopotential height is returned as + + If *msl* is True, then geopotential height is returned as Mean Sea Level + (MSL). If *msl* is False, then geopotential height is returned as Above Ground Level (AGL) by subtracting the terrain height. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + msl (:obj:`bool`, optional): Set to True to return geopotential height - as Mean Sea Level (MSL). Set to False to return the - geopotential height as Above Ground Level (AGL) by subtracting + as Mean Sea Level (MSL). Set to False to return the + geopotential height as Above Ground Level (AGL) by subtracting the terrain height. Default is True. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'z'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'z'. Default is 'm'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The geopotential height. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - + return _get_geoht(wrfin, timeidx, method, squeeze, cache, meta, _key, True, msl, stag=True) - \ No newline at end of file diff --git a/src/wrf/g_helicity.py b/src/wrf/g_helicity.py index 5ae17ab..964c083 100755 --- a/src/wrf/g_helicity.py +++ b/src/wrf/g_helicity.py @@ -9,87 +9,88 @@ from .util import extract_vars, extract_global_attrs, either from .metadecorators import copy_and_set_metadata from .g_latlon import get_lat -@copy_and_set_metadata(copy_varname="HGT", name="srh", + +@copy_and_set_metadata(copy_varname="HGT", name="srh", description="storm relative helicity", units="m2 s-2") -def get_srh(wrfin, timeidx=0, method="cat", squeeze=True, +def get_srh(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, top=3000.0): """Return the storm relative helicity. - + The *top* argument specifies the top of the integration in [m]. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - top (:obj:`float`, optional): The top of the integration in [m]. + + top (:obj:`float`, optional): The top of the integration in [m]. Default is 3000.0. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The storm relative helicity. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ # Top can either be 3000 or 1000 (for 0-1 srh or 0-3 srh) - - lats = get_lat(wrfin, timeidx, method, squeeze, + + lats = get_lat(wrfin, timeidx, method, squeeze, cache, meta=False, _key=_key, stagger=None) - + ncvars = extract_vars(wrfin, timeidx, ("HGT", "PH", "PHB"), method, squeeze, cache, meta=False, _key=_key) - + ter = ncvars["HGT"] ph = ncvars["PH"] phb = ncvars["PHB"] - + # As coded in NCL, but not sure this is possible varname = either("U", "UU")(wrfin) u_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) - u = destagger(u_vars[varname], -1) - + u = destagger(u_vars[varname], -1) + varname = either("V", "VV")(wrfin) v_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) @@ -97,117 +98,113 @@ def get_srh(wrfin, timeidx=0, method="cat", squeeze=True, geopt = ph + phb geopt_unstag = destagger(geopt, -3) - + z = geopt_unstag / Constants.G - + # Re-ordering from high to low u1 = np.ascontiguousarray(u[...,::-1,:,:]) v1 = np.ascontiguousarray(v[...,::-1,:,:]) z1 = np.ascontiguousarray(z[...,::-1,:,:]) - + srh = _srhel(u1, v1, z1, ter, lats, top) - + return srh -@copy_and_set_metadata(copy_varname="MAPFAC_M", name="updraft_helicity", +@copy_and_set_metadata(copy_varname="MAPFAC_M", name="updraft_helicity", description="updraft helicity", units="m2 s-2") -def get_uh(wrfin, timeidx=0, method="cat", squeeze=True, +def get_uh(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, bottom=2000.0, top=5000.0): - + """Return the updraft helicity. - - The *bottom* and *top* arguments specify the bottom and top limits + + The *bottom* and *top* arguments specify the bottom and top limits for the integration in [m]. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - bottom (:obj:`float`, optional): The bottom limit for the integration + + bottom (:obj:`float`, optional): The bottom limit for the integration in [m]. Default is 2000.0. - - top (:obj:`float`, optional): The top limit for the integration in [m]. + + top (:obj:`float`, optional): The top limit for the integration in [m]. Default is 5000.0. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The updraft helicity. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - + ncvars = extract_vars(wrfin, timeidx, ("W", "PH", "PHB", "MAPFAC_M"), method, squeeze, cache, meta=False, _key=_key) - + wstag = ncvars["W"] ph = ncvars["PH"] phb = ncvars["PHB"] mapfct = ncvars["MAPFAC_M"] - + attrs = extract_global_attrs(wrfin, attrs=("DX", "DY")) dx = attrs["DX"] dy = attrs["DY"] - + # As coded in NCL, but not sure this is possible varname = either("U", "UU")(wrfin) u_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) - u = destagger(u_vars[varname], -1) - + u = destagger(u_vars[varname], -1) + varname = either("V", "VV")(wrfin) v_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) - v = destagger(v_vars[varname], -2) - + v = destagger(v_vars[varname], -2) + zp = (ph + phb) / Constants.G - + uh = _udhel(zp, mapfct, u, v, wstag, dx, dy, bottom, top) - - return uh - - - + return uh \ No newline at end of file diff --git a/src/wrf/g_latlon.py b/src/wrf/g_latlon.py index 03aef1f..0e4cfae 100755 --- a/src/wrf/g_latlon.py +++ b/src/wrf/g_latlon.py @@ -15,237 +15,237 @@ if xarray_enabled(): from xarray import DataArray -def get_lat(wrfin, timeidx=0, method="cat", squeeze=True, +def get_lat(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, stagger=None): """Return the two dimensional latitude coordinate variable. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + stagger (:obj:`str`): By default, the latitude is returned on the mass - grid, but a staggered grid can be chosen with the following + grid, but a staggered grid can be chosen with the following options: - + - 'm': Use the mass grid (default). - - 'u': Use the same staggered grid as the u wind component, + - 'u': Use the same staggered grid as the u wind component, which has a staggered west_east (x) dimension. - - 'v': Use the same staggered grid as the v wind component, + - 'v': Use the same staggered grid as the v wind component, which has a staggered south_north (y) dimension. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The two dimensional latitude coordinate variable. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - + varname = _lat_varname(wrfin, stagger) lat_var = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta, _key) - + return lat_var[varname] - -def get_lon(wrfin, timeidx=0, method="cat", squeeze=True, + +def get_lon(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, stagger=None): """Return the two dimensional longitude coordinate variable. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + stagger (:obj:`str`): By default, the longitude is returned on the mass - grid, but a staggered grid can be chosen with the following + grid, but a staggered grid can be chosen with the following options: - + - 'm': Use the mass grid (default). - - 'u': Use the same staggered grid as the u wind component, + - 'u': Use the same staggered grid as the u wind component, which has a staggered west_east (x) dimension. - - 'v': Use the same staggered grid as the v wind component, + - 'v': Use the same staggered grid as the v wind component, which has a staggered south_north (y) dimension. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The two dimensional longitude coordinate variable. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - + varname = _lon_varname(wrfin, stagger) lon_var = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta, _key) - + return lon_var[varname] -def _llxy_mapping(wrfin, x_or_lat, y_or_lon, func, timeidx, stagger, +def _llxy_mapping(wrfin, x_or_lat, y_or_lon, func, timeidx, stagger, squeeze, meta, as_int=None): - + """Return the x,y/lat,lon coordinates for a dictionary input. - + The leftmost dimension(s) for the result is: - + - return_val[key,...,0,...] will contain the x/lat values. - return_val[key,...,1,...] will contain the y/lon values. - + Nested dictionaries are allowed. - + Args: - - wrfin (:obj:`dict`): A mapping of key name to a WRF NetCDF file object + + wrfin (:obj:`dict`): A mapping of key name to a WRF NetCDF file object or sequence of WRF NetCDF file objects. - - x_or_lat (:obj:`float` or sequence): A single latitude/x value or a + + x_or_lat (:obj:`float` or sequence): A single latitude/x value or a sequence of latitude/x values to be converted. - - y_or_lon (:obj:`float` or sequence): A single longitude/y value or a + + y_or_lon (:obj:`float` or sequence): A single longitude/y value or a sequence of longitude/y values to be converted. - + func (function): Either the xy_to_ll or ll_to_xy function. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - + stagger (:obj:`str`): By default, the values are returned on the mass - grid, but a staggered grid can be chosen with the following + grid, but a staggered grid can be chosen with the following options: - + - 'm': Use the mass grid (default). - - 'u': Use the same staggered grid as the u wind component, + - 'u': Use the same staggered grid as the u wind component, which has a staggered west_east (x) dimension. - - 'v': Use the same staggered grid as the v wind component, + - 'v': Use the same staggered grid as the v wind component, which has a staggered south_north (y) dimension. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - as_int (:obj:`bool`, optional): Set to True to return the x,y values as + as_int (:obj:`bool`, optional): Set to True to return the x,y values as :obj:`int`, otherwise they will be returned as :obj:`float`. This is only used when *func* is ll_to_xy. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - lat,lon/x,y coordinate value(s) whose leftmost dimensions are the - dictionary keys, followed by a dimension of size + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + lat,lon/x,y coordinate value(s) whose leftmost dimensions are the + dictionary keys, followed by a dimension of size 2 (0=X, 1=Y)/(0=lat, 1=lon). - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - + keynames = [] # This might not work once mapping iterators are implemented - numkeys = len(wrfin) - + numkeys = len(wrfin) + key_iter = iter(viewkeys(wrfin)) first_key = next(key_iter) keynames.append(first_key) - + first_args = [wrfin[first_key], x_or_lat, y_or_lon, timeidx, squeeze, meta, stagger] if as_int is not None: first_args.append(as_int) - + first_array = func(*first_args) - + # Create the output data numpy array based on the first array outdims = [numkeys] outdims += first_array.shape outdata = np.empty(outdims, first_array.dtype) - outdata[0,:] = first_array[:] - + outdata[0, :] = first_array[:] + idx = 1 while True: try: @@ -254,25 +254,25 @@ def _llxy_mapping(wrfin, x_or_lat, y_or_lon, func, timeidx, stagger, break else: keynames.append(key) - + args = [wrfin[first_key], x_or_lat, y_or_lon, timeidx, squeeze, meta, stagger] if as_int is not None: args.append(as_int) - + result_array = func(*args) - + if outdata.shape[1:] != result_array.shape: raise ValueError("data sequences must have the " "same size for all dictionary keys") - outdata[idx,:] = to_np(result_array)[:] + outdata[idx, :] = to_np(result_array)[:] idx += 1 - + if xarray_enabled() and meta: outname = str(first_array.name) # Note: assumes that all entries in dict have same coords outcoords = OrderedDict(first_array.coords) - + # First find and store all the existing key coord names/values # This is applicable only if there are nested dictionaries. key_coordnames = [] @@ -280,164 +280,162 @@ def _llxy_mapping(wrfin, x_or_lat, y_or_lon, func, timeidx, stagger, existing_cnt = 0 while True: key_coord_name = "key_{}".format(existing_cnt) - + if key_coord_name not in first_array.dims: break - + key_coordnames.append(key_coord_name) coord_vals.append(to_np(first_array.coords[key_coord_name])) - + existing_cnt += 1 - + # Now add the key coord name and values for THIS dictionary. - # Put the new key_n name at the bottom, but the new values will + # Put the new key_n name at the bottom, but the new values will # be at the top to be associated with key_0 (left most). This - # effectively shifts the existing 'key_n' coordinate values to the - # right one dimension so *this* dicionary's key coordinate values + # effectively shifts the existing 'key_n' coordinate values to the + # right one dimension so *this* dicionary's key coordinate values # are at 'key_0'. key_coordnames.append(key_coord_name) coord_vals.insert(0, keynames) - + # make it so that key_0 is leftmost outdims = key_coordnames + list(first_array.dims[existing_cnt:]) - - + # Create the new 'key_n', value pairs for coordname, coordval in zip(key_coordnames, coord_vals): outcoords[coordname] = coordval - - + outattrs = OrderedDict(first_array.attrs) - - outarr = DataArray(outdata, name=outname, coords=outcoords, + + outarr = DataArray(outdata, name=outname, coords=outcoords, dims=outdims, attrs=outattrs) else: outarr = outdata - + return outarr -@set_latlon_metadata(xy=True) -def ll_to_xy(wrfin, latitude, longitude, timeidx=0, +@set_latlon_metadata(xy=True) +def ll_to_xy(wrfin, latitude, longitude, timeidx=0, squeeze=True, meta=True, stagger=None, as_int=True): """Return the x,y coordinates for a specified latitude and longitude. - - The *latitude* and *longitude* arguments can be a single value or a + + The *latitude* and *longitude* arguments can be a single value or a sequence of values. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain the X (west_east) values. - return_val[1,...] will contain the Y (south_north) values. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - latitude (:obj:`float` or sequence): A single latitude or a sequence + + latitude (:obj:`float` or sequence): A single latitude or a sequence of latitude values to be converted. - - longitude (:obj:`float` or sequence): A single longitude or a sequence + + longitude (:obj:`float` or sequence): A single longitude or a sequence of latitude values to be converted. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + stagger (:obj:`str`): By default, the latitude is returned on the mass - grid, but a staggered grid can be chosen with the following + grid, but a staggered grid can be chosen with the following options: - + - 'm': Use the mass grid (default). - - 'u': Use the same staggered grid as the u wind component, + - 'u': Use the same staggered grid as the u wind component, which has a staggered west_east (x) dimension. - - 'v': Use the same staggered grid as the v wind component, + - 'v': Use the same staggered grid as the v wind component, which has a staggered south_north (y) dimension. - - as_int (:obj:`bool`): Set to False to return the x,y values as + + as_int (:obj:`bool`): Set to False to return the x,y values as :obj:`float`, otherwise they will be returned as :obj:`int`. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The x,y coordinate value(s) whose leftmost dimension is 2 (0=X, 1=Y). - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ if is_mapping(wrfin): - return _llxy_mapping(wrfin, latitude, longitude, ll_to_xy, + return _llxy_mapping(wrfin, latitude, longitude, ll_to_xy, timeidx, stagger, squeeze, meta, as_int) _key = get_id(wrfin) _wrfin = get_iterable(wrfin) - return _ll_to_xy(latitude, longitude, _wrfin, timeidx, stagger, "cat", + return _ll_to_xy(latitude, longitude, _wrfin, timeidx, stagger, "cat", squeeze, None, _key, as_int, **{}) def _set_defaults(projparams): """Check projection parameters and set defaults. - - Throws an exception if projection parameters required by WPS are not + + Throws an exception if projection parameters required by WPS are not provided, along with any other parameters required by the map projection - transformation routines. - - For parameters not used by the projection type, defaults are used so that + transformation routines. + + For parameters not used by the projection type, defaults are used so that the None values don't pass through to fortran downstream. - + Args: - + projparams (:obj:`dict`): Projection parameters dictionary. - + Returns: - :obj:`dict`: The projection parameters with default values inserted + :obj:`dict`: The projection parameters with default values inserted where applicable. - + """ _params = dict(projparams) - + map_proj = _params.get("map_proj") # All projections require these arguments if map_proj is None: raise ValueError("'map_proj' cannot be None") - + if _params.get("ref_lat") is None: raise ValueError("'ref_lat' cannot be None") - + if _params.get("ref_lon") is None: raise ValueError("'ref_lon' cannot be None") - + if _params.get("known_x") is None: raise ValueError("'known_x' cannot be None") - + if _params.get("known_y") is None: raise ValueError("'known_y' cannot be None") - + if _params.get("dx") is None: raise ValueError("'dx' cannot be None") - + # Requires truelat1,stand_lon, truelat2, dx, dy if map_proj == ProjectionTypes.LAMBERT_CONFORMAL: if _params.get("truelat1") is None: raise ValueError("'truelat1' cannot be None") - + if _params.get("stand_lon") is None: raise ValueError("'stand_lon' cannot be None") - + if _params.get("truelat2") is None: _params["truelat2"] = _params["truelat1"] @@ -445,347 +443,341 @@ def _set_defaults(projparams): elif map_proj == ProjectionTypes.POLAR_STEREOGRAPHIC: if _params.get("truelat1") is None: raise ValueError("'truelat1' cannot be None") - + if _params.get("stand_lon") is None: raise ValueError("'stand_lon' cannot be None") - + # Requires truelat1 elif map_proj == ProjectionTypes.MERCATOR: if _params.get("truelat1") is None: raise ValueError("'truelat1' cannot be None") - + if _params.get("stand_lon") is None: _params["stand_lon"] = 0.0 - + # Requires pole_lat, pole_lon, stand_lon - elif map_proj == ProjectionTypes.LAT_LON: + elif map_proj == ProjectionTypes.LAT_LON: if _params.get("stand_lon") is None: raise ValueError("'stand_lon' cannot be None") - + if _params.get("dy") is None: raise ValueError("'dy' cannot be None") - + if _params.get("pole_lat") is None: raise ValueError("'pole_lat' cannot be None") - + if _params.get("pole_lon") is None: raise ValueError("'pole_lon' cannot be None") - + if _params.get("latinc") is None: - _params["latinc"] = ((_params["dy"]*360.0)/2.0 / - Constants.PI/Constants.WRF_EARTH_RADIUS) - + _params["latinc"] = ((_params["dy"]*360.0)/2.0 / + Constants.PI/Constants.WRF_EARTH_RADIUS) + if _params.get("loninc") is None: - _params["loninc"] = ((_params["dx"]*360.0)/2.0 / + _params["loninc"] = ((_params["dx"]*360.0)/2.0 / Constants.PI/Constants.WRF_EARTH_RADIUS) - + else: raise ValueError("invalid 'map_proj' value of {}".format(map_proj)) - + # Set these to defaults if not used so that the Fortran routines # don't crash if _params.get("truelat1") is None: _params["truelat1"] = 0. - + if _params.get("truelat2") is None: _params["truelat2"] = 0. - + if _params.get("pole_lat") is None: _params["pole_lat"] = 90.0 - + if _params.get("pole_lon") is None: _params["pole_lon"] = 0.0 - + if _params.get("dx") is None: _params["dx"] = 0.0 - + if _params.get("dy") is None: _params["dy"] = 0.0 - + if _params.get("latinc") is None: _params["latinc"] = 0. - + if _params.get("loninc") is None: _params["loninc"] = 0. - + return _params -@set_latlon_metadata(xy=True) +@set_latlon_metadata(xy=True) def ll_to_xy_proj(latitude, longitude, meta=True, squeeze=True, as_int=True, - map_proj=None, truelat1=None, truelat2=None, stand_lon=None, - ref_lat=None, ref_lon=None, pole_lat=None, pole_lon=None, - known_x=None, known_y=None, dx=None, dy=None, + map_proj=None, truelat1=None, truelat2=None, stand_lon=None, + ref_lat=None, ref_lon=None, pole_lat=None, pole_lon=None, + known_x=None, known_y=None, dx=None, dy=None, latinc=None, loninc=None): """Return the x, y coordinates for a specified latitude and longitude. - - The *latitude* and *longitude* arguments can be a single value or a - sequence of values. This version of the ll_to_xy routine allows users - to manually specify projection parameters. - - The leftmost dimension of the returned array represents two different + + The *latitude* and *longitude* arguments can be a single value or a + sequence of values. This version of the ll_to_xy routine allows users + to manually specify projection parameters. + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain the X (west_east) values. - return_val[1,...] will contain the Y (south_north) values. - + Args: - - latitude (:obj:`float` or sequence): A single latitude or a sequence + + latitude (:obj:`float` or sequence): A single latitude or a sequence of latitude values to be converted. - - longitude (:obj:`float` or sequence): A single longitude or a sequence + + longitude (:obj:`float` or sequence): A single longitude or a sequence of latitude values to be converted. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - as_int (:obj:`bool`): Set to False to return the x,y values as - :obj:`float`, otherwise they will be returned as :obj:`int`. + + as_int (:obj:`bool`): Set to False to return the x,y values as + :obj:`float`, otherwise they will be returned as :obj:`int`. Default is True. - - map_proj (:obj:`int`): Model projection [1=Lambert Conformal, + + map_proj (:obj:`int`): Model projection [1=Lambert Conformal, 2=Polar Stereographic, 3=Mercator, 6=Lat-Lon]. Required. - - truelat1 (:obj:`float`): Latitude of true scale 1. Required for + + truelat1 (:obj:`float`): Latitude of true scale 1. Required for map_proj = 1, 2, 3 (defaults to 0 otherwise). - - truelat2 (:obj:`float`): Latitude of true scale 2. Optional for + + truelat2 (:obj:`float`): Latitude of true scale 2. Optional for map_proj = 1 (defaults to 0 otherwise). - - stand_lon (:obj:`float`): Standard longitude. Required for *map_proj* = + + stand_lon (:obj:`float`): Standard longitude. Required for *map_proj* = 1, 2, 6 (defaults to 0 otherwise). - - ref_lat (:obj:`float`): A reference latitude. Required. - + + ref_lat (:obj:`float`): A reference latitude. Required. + ref_lon (:obj:`float`): A reference longitude. Required. - - known_x (:obj:`float`): The known x-coordinate associated with + + known_x (:obj:`float`): The known x-coordinate associated with *ref_lon*. Required. - - known_y (:obj:`float`): The known y-coordinate associated with + + known_y (:obj:`float`): The known y-coordinate associated with *ref_lat*. Required. - - pole_lat (:obj:`float`): Pole latitude. Required for + + pole_lat (:obj:`float`): Pole latitude. Required for *map_proj* = 6 (use 90 for no rotation). - - pole_lon (:obj:`float`): Pole longitude. Required for + + pole_lon (:obj:`float`): Pole longitude. Required for *map_proj* = 6 (use 0 for no rotation). - - dx (:obj:`float`): The x spacing in meters at the true latitude. + + dx (:obj:`float`): The x spacing in meters at the true latitude. Required for all map projections. - - dy (:obj:`float`) - The y spacing in meters at the true latitude. + + dy (:obj:`float`) - The y spacing in meters at the true latitude. Required for *map_proj* = 6 (defaults to 0 otherwise). - + latinc (:obj:`float`): Optional for *map_proj* = 6. Default is: - + .. code-block:: python - + latinc = (dy*360.0)/2.0/Constants.PI/Constants.WRF_EARTH_RADIUS - + loninc (:obj:`float`): Optional for *map_proj* = 6. Default is: - + .. code-block:: python - + loninc = (dx*360.0)/2.0/Constants.PI/Constants.WRF_EARTH_RADIUS Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The x,y coordinate value(s) whose leftmost dimension is 2 (0=X, 1=Y). - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ loc = locals() - _projparams = {name : loc[name] for name in ("map_proj", "truelat1", - "truelat2", "stand_lon", "ref_lat", - "ref_lon", "pole_lat", "pole_lon", - "known_x", "known_y", "dx", "dy", - "latinc", "loninc")} - + _projparams = {name: loc[name] for name in ("map_proj", "truelat1", + "truelat2", "stand_lon", + "ref_lat", "ref_lon", + "pole_lat", "pole_lon", + "known_x", "known_y", "dx", + "dy", "latinc", "loninc")} + projparams = _set_defaults(_projparams) return _ll_to_xy(latitude, longitude, None, 0, True, "cat", squeeze, None, None, as_int, **projparams) -@set_latlon_metadata(xy=False) +@set_latlon_metadata(xy=False) def xy_to_ll(wrfin, x, y, timeidx=0, squeeze=True, meta=True, stagger=None): """Return the latitude and longitude for specified x,y coordinates. - + The *x* and *y* arguments can be a single value or a sequence of values. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain the latitude values. - return_val[1,...] will contain the longitude values. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - x (:obj:`float` or sequence): A single x-coordinate or a sequence + + x (:obj:`float` or sequence): A single x-coordinate or a sequence of x-coordinate values to be converted. - - y (:obj:`float` or sequence): A single y-coordinate or a sequence + + y (:obj:`float` or sequence): A single y-coordinate or a sequence of y-coordinate values to be converted. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - + stagger (:obj:`str`): By default, the latitude is returned on the mass - grid, but a staggered grid can be chosen with the following + grid, but a staggered grid can be chosen with the following options: - + - 'm': Use the mass grid (default). - - 'u': Use the same staggered grid as the u wind component, + - 'u': Use the same staggered grid as the u wind component, which has a staggered west_east (x) dimension. - - 'v': Use the same staggered grid as the v wind component, + - 'v': Use the same staggered grid as the v wind component, which has a staggered south_north (y) dimension. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - latitude and longitude values whose leftmost dimension is 2 + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + latitude and longitude values whose leftmost dimension is 2 (0=latitude, 1=longitude). - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ if is_mapping(wrfin): - return _llxy_mapping(wrfin, x, y, xy_to_ll, + return _llxy_mapping(wrfin, x, y, xy_to_ll, timeidx, stagger, squeeze, meta) - + _key = get_id(wrfin) _wrfin = get_iterable(wrfin) - return _xy_to_ll(x, y, _wrfin, timeidx, stagger, "cat", True, None, + return _xy_to_ll(x, y, _wrfin, timeidx, stagger, "cat", True, None, _key, **{}) - - -@set_latlon_metadata(xy=False) -def xy_to_ll_proj(x, y, meta=True, squeeze=True, map_proj=None, truelat1=None, - truelat2=None, stand_lon=None, ref_lat=None, ref_lon=None, - pole_lat=None, pole_lon=None, known_x=None, known_y=None, + + +@set_latlon_metadata(xy=False) +def xy_to_ll_proj(x, y, meta=True, squeeze=True, map_proj=None, truelat1=None, + truelat2=None, stand_lon=None, ref_lat=None, ref_lon=None, + pole_lat=None, pole_lon=None, known_x=None, known_y=None, dx=None, dy=None, latinc=None, loninc=None): """Return the latitude and longitude for the specified x,y coordinates. - - The *x* and *y* arguments can be a single value or a - sequence of values. This version of the xy_to_ll routine allows users - to manually specify map projection parameters. - - The leftmost dimension of the returned array represents two different + + The *x* and *y* arguments can be a single value or a + sequence of values. This version of the xy_to_ll routine allows users + to manually specify map projection parameters. + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain the latitude values. - return_val[1,...] will contain the longitude values. - + Args: - - x (:obj:`float` or sequence): A single x-coordinate or a sequence + + x (:obj:`float` or sequence): A single x-coordinate or a sequence of x-coordinate values to be converted. - - y (:obj:`float` or sequence): A single y-coordinate or a sequence + + y (:obj:`float` or sequence): A single y-coordinate or a sequence of y-coordinate values to be converted. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - map_proj (:obj:`int`): Model projection [1=Lambert Conformal, + + map_proj (:obj:`int`): Model projection [1=Lambert Conformal, 2=Polar Stereographic, 3=Mercator, 6=Lat-Lon]. Required. - - truelat1 (:obj:`float`): Latitude of true scale 1. Required for + + truelat1 (:obj:`float`): Latitude of true scale 1. Required for map_proj = 1, 2, 3 (defaults to 0 otherwise). - - truelat2 (:obj:`float`): Latitude of true scale 2. Optional for + + truelat2 (:obj:`float`): Latitude of true scale 2. Optional for map_proj = 1 (defaults to 0 otherwise). - - stand_lon (:obj:`float`): Standard longitude. Required for *map_proj* = + + stand_lon (:obj:`float`): Standard longitude. Required for *map_proj* = 1, 2, 6 (defaults to 0 otherwise). - - ref_lat (:obj:`float`): A reference latitude. Required. - + + ref_lat (:obj:`float`): A reference latitude. Required. + ref_lon (:obj:`float`): A reference longitude. Required. - - known_x (:obj:`float`): The known x-coordinate associated with + + known_x (:obj:`float`): The known x-coordinate associated with *ref_lon*. Required. - - known_y (:obj:`float`): The known y-coordinate associated with + + known_y (:obj:`float`): The known y-coordinate associated with *ref_lat*. Required. - - pole_lat (:obj:`float`): Pole latitude. Required for + + pole_lat (:obj:`float`): Pole latitude. Required for *map_proj* = 6 (use 90 for no rotation). - - pole_lon (:obj:`float`): Pole longitude. Required for + + pole_lon (:obj:`float`): Pole longitude. Required for *map_proj* = 6 (use 0 for no rotation). - - dx (:obj:`float`): The x spacing in meters at the true latitude. + + dx (:obj:`float`): The x spacing in meters at the true latitude. Required for all map projections. - - dy (:obj:`float`) - The y spacing in meters at the true latitude. + + dy (:obj:`float`) - The y spacing in meters at the true latitude. Required for *map_proj* = 6 (defaults to 0 otherwise). - + latinc (:obj:`float`): Optional for *map_proj* = 6. Default is: - + .. code-block:: python - + latinc = (dy*360.0)/2.0/Constants.PI/Constants.WRF_EARTH_RADIUS - + loninc (:obj:`float`): Optional for *map_proj* = 6. Default is: - + .. code-block:: python - + loninc = (dx*360.0)/2.0/Constants.PI/Constants.WRF_EARTH_RADIUS Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The - latitude and longitude values whose leftmost dimension is 2 + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + latitude and longitude values whose leftmost dimension is 2 (0=latitude, 1=longitude). - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. """ loc = locals() - _projparams = {name : loc[name] for name in ("map_proj", "truelat1", - "truelat2", "stand_lon", "ref_lat", - "ref_lon", "pole_lat", "pole_lon", - "known_x", "known_y", "dx", "dy", - "latinc", "loninc")} - + _projparams = {name: loc[name] for name in ("map_proj", "truelat1", + "truelat2", "stand_lon", + "ref_lat", "ref_lon", + "pole_lat", "pole_lon", + "known_x", "known_y", "dx", + "dy", "latinc", "loninc")} + projparams = _set_defaults(_projparams) return _xy_to_ll(x, y, None, 0, None, "cat", squeeze, None, None, **projparams) - - - - - - - - \ No newline at end of file diff --git a/src/wrf/g_omega.py b/src/wrf/g_omega.py index 6bddfa3..f2f70ba 100755 --- a/src/wrf/g_omega.py +++ b/src/wrf/g_omega.py @@ -7,64 +7,64 @@ from .util import extract_vars from .metadecorators import copy_and_set_metadata -@copy_and_set_metadata(copy_varname="T", name="omega", +@copy_and_set_metadata(copy_varname="T", name="omega", description="omega", units="Pa s-1") def get_omega(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return Omega. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: Omega. - If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + :class:`xarray.DataArray` or :class:`numpy.ndarray`: Omega. + If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - varnames=("T", "P", "W", "PB", "QVAPOR") + varnames = ("T", "P", "W", "PB", "QVAPOR") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) t = ncvars["T"] @@ -72,13 +72,12 @@ def get_omega(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, w = ncvars["W"] pb = ncvars["PB"] qv = ncvars["QVAPOR"] - + wa = destagger(w, -3) full_t = t + Constants.T_BASE full_p = p + pb tk = _tk(full_p, full_t) - + omega = _omega(qv, tk, wa, full_p) - + return omega - \ No newline at end of file diff --git a/src/wrf/g_precip.py b/src/wrf/g_precip.py index aa75a80..0d5dbc8 100755 --- a/src/wrf/g_precip.py +++ b/src/wrf/g_precip.py @@ -2,29 +2,29 @@ from __future__ import (absolute_import, division, print_function) from .util import extract_vars -__all__ = ["get_accum_precip", "get_precip_diff"] def get_accum_precip(wrfin, timeidx=0): ncvars = extract_vars(wrfin, timeidx, varnames=("RAINC", "RAINNC")) rainc = ncvars["RAINC"] rainnc = ncvars["RAINNC"] - + rainsum = rainc + rainnc - + return rainsum + def get_precip_diff(wrfin1, wrfin2, timeidx=0): vars1 = extract_vars(wrfin1, timeidx, varnames=("RAINC", "RAINNC")) vars2 = extract_vars(wrfin2, timeidx, varnames=("RAINC", "RAINNC")) rainc1 = vars1["RAINC"] rainnc1 = vars1["RAINNC"] - + rainc2 = vars2["RAINC"] rainnc2 = vars2["RAINNC"] - + rainsum1 = rainc1 + rainnc1 rainsum2 = rainc2 + rainnc2 - + return (rainsum1 - rainsum2) # TODO: Handle bucket flipping diff --git a/src/wrf/g_pressure.py b/src/wrf/g_pressure.py index 44676ad..e93d807 100755 --- a/src/wrf/g_pressure.py +++ b/src/wrf/g_pressure.py @@ -5,144 +5,141 @@ from .metadecorators import copy_and_set_metadata from .util import extract_vars, either -@copy_and_set_metadata(copy_varname=either("P", "PRES"), name="pressure", +@copy_and_set_metadata(copy_varname=either("P", "PRES"), name="pressure", description="pressure") @convert_units("pressure", "pa") -def get_pressure(wrfin, timeidx=0, method="cat", squeeze=True, +def get_pressure(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="Pa"): - + """Return the pressure in the specified units. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'pres'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'pres'. Default is 'Pa'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The pressure in - the specified units. - If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The pressure in + the specified units. + If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ varname = either("P", "PRES")(wrfin) if varname == "P": - p_vars = extract_vars(wrfin, timeidx, ("P", "PB"), + p_vars = extract_vars(wrfin, timeidx, ("P", "PB"), method, squeeze, cache, meta=False, _key=_key) p = p_vars["P"] pb = p_vars["PB"] pres = p + pb else: - pres = extract_vars(wrfin, timeidx, "PRES", + pres = extract_vars(wrfin, timeidx, "PRES", method, squeeze, cache, meta=False, _key=_key)["PRES"] - + return pres -def get_pressure_hpa(wrfin, timeidx=0, method="cat", squeeze=True, + +def get_pressure_hpa(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return the pressure in [hPa]. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The pressure in - [hPa]. - If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The pressure in + [hPa]. + If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ return get_pressure(wrfin, timeidx, method, squeeze, cache, meta, _key, units="hPa") - - - - \ No newline at end of file diff --git a/src/wrf/g_pw.py b/src/wrf/g_pw.py index 73d6f74..b63d252 100755 --- a/src/wrf/g_pw.py +++ b/src/wrf/g_pw.py @@ -1,91 +1,86 @@ from __future__ import (absolute_import, division, print_function) -#from .extension import computepw,computetv,computetk from .extension import _pw, _tv, _tk from .constants import Constants from .util import extract_vars from .metadecorators import copy_and_set_metadata -@copy_and_set_metadata(copy_varname="T", name="pw", +@copy_and_set_metadata(copy_varname="T", name="pw", remove_dims=("bottom_top",), description="precipitable water", MemoryOrder="XY", units="kg m-2") -def get_pw(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, +def get_pw(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return the preciptiable water. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The preciptable - water. If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The preciptable + water. If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - varnames=("T", "P", "PB", "PH", "PHB", "QVAPOR") + varnames = ("T", "P", "PB", "PH", "PHB", "QVAPOR") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) - + t = ncvars["T"] p = ncvars["P"] pb = ncvars["PB"] ph = ncvars["PH"] phb = ncvars["PHB"] qv = ncvars["QVAPOR"] - + full_p = p + pb ht = (ph + phb)/Constants.G full_t = t + Constants.T_BASE - + tk = _tk(full_p, full_t) tv = _tv(tk, qv) - + return _pw(full_p, tv, qv, ht) - - - - \ No newline at end of file diff --git a/src/wrf/g_rh.py b/src/wrf/g_rh.py index 40f1263..21dd4aa 100755 --- a/src/wrf/g_rh.py +++ b/src/wrf/g_rh.py @@ -1,156 +1,154 @@ from __future__ import (absolute_import, division, print_function) -from .constants import Constants -#from .extension import computerh, computetk +from .constants import Constants from .extension import _rh, _tk from .util import extract_vars from .metadecorators import copy_and_set_metadata -@copy_and_set_metadata(copy_varname="T", name="rh", +@copy_and_set_metadata(copy_varname="T", name="rh", description="relative humidity", units="%") -def get_rh(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, +def get_rh(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return the relative humidity. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The relative - humidity. If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The relative + humidity. If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - varnames=("T", "P", "PB", "QVAPOR") + varnames = ("T", "P", "PB", "QVAPOR") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) t = ncvars["T"] p = ncvars["P"] pb = ncvars["PB"] - # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to + # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to # break with every release qvapor = ncvars["QVAPOR"].copy() - + full_t = t + Constants.T_BASE full_p = p + pb qvapor[qvapor < 0] = 0 tk = _tk(full_p, full_t) rh = _rh(qvapor, full_p, tk) - + return rh -@copy_and_set_metadata(copy_varname="T2", name="rh2", +@copy_and_set_metadata(copy_varname="T2", name="rh2", description="2m relative humidity", units="%") def get_rh_2m(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return the 2m relative humidity. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: :class:`xarray.DataArray` or :class:`numpy.ndarray`: The 2m relative - humidity. If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + humidity. If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - varnames=("T2", "PSFC", "Q2") + varnames = ("T2", "PSFC", "Q2") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) t2 = ncvars["T2"] psfc = ncvars["PSFC"] - # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to + # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to # break with every release q2 = ncvars["Q2"].copy() - + q2[q2 < 0] = 0 rh = _rh(q2, psfc, t2) - - return rh + return rh diff --git a/src/wrf/g_slp.py b/src/wrf/g_slp.py index a8f0e03..f422bed 100755 --- a/src/wrf/g_slp.py +++ b/src/wrf/g_slp.py @@ -1,6 +1,5 @@ from __future__ import (absolute_import, division, print_function) -#from .extension import computeslp, computetk from .extension import _slp, _tk from .constants import Constants from .destag import destagger @@ -10,94 +9,93 @@ from .util import extract_vars @copy_and_set_metadata(copy_varname="T", name="slp", - remove_dims=("bottom_top",), + remove_dims=("bottom_top",), description="sea level pressure", MemoryOrder="XY") @convert_units("pressure", "hpa") -def get_slp(wrfin, timeidx=0, method="cat", squeeze=True, +def get_slp(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="hPa"): - + """Return the sea level pressure in the specified units. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'slp'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'slp'. Default is 'Pa'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The sea level - pressure in the specified units. If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The sea level + pressure in the specified units. If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - varnames=("T", "P", "PB", "QVAPOR", "PH", "PHB") + varnames = ("T", "P", "PB", "QVAPOR", "PH", "PHB") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) t = ncvars["T"] p = ncvars["P"] pb = ncvars["PB"] - # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to + # Copy needed for the mmap nonsense of scipy.io.netcdf, which seems to # break with every release qvapor = ncvars["QVAPOR"].copy() ph = ncvars["PH"] phb = ncvars["PHB"] - + full_t = t + Constants.T_BASE full_p = p + pb qvapor[qvapor < 0] = 0. - + full_ph = (ph + phb) / Constants.G - + destag_ph = destagger(full_ph, -3) - + tk = _tk(full_p, full_t) slp = _slp(destag_ph, tk, full_p, qvapor) - - return slp + return slp diff --git a/src/wrf/g_temp.py b/src/wrf/g_temp.py index f29969c..a4c6d93 100755 --- a/src/wrf/g_temp.py +++ b/src/wrf/g_temp.py @@ -7,70 +7,70 @@ from .metadecorators import copy_and_set_metadata from .util import extract_vars -@copy_and_set_metadata(copy_varname="T", name="theta", +@copy_and_set_metadata(copy_varname="T", name="theta", description="potential temperature") @convert_units("temp", "k") -def get_theta(wrfin, timeidx=0, method="cat", squeeze=True, +def get_theta(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="K"): """Return the potential temperature. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'theta'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'theta'. Default is 'K'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The potential temperature. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - varnames = ("T",) - + varnames = ("T", ) + ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) t = ncvars["T"] @@ -79,438 +79,435 @@ def get_theta(wrfin, timeidx=0, method="cat", squeeze=True, return full_t -@copy_and_set_metadata(copy_varname="T", name="temp", +@copy_and_set_metadata(copy_varname="T", name="temp", description="temperature") @convert_units("temp", "k") -def get_temp(wrfin, timeidx=0, method="cat", squeeze=True, +def get_temp(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="K"): """Return the temperature in the specified units. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'temp'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'temp'. Default is 'K'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The temperature in the specified units. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - - varnames=("T", "P", "PB") + + varnames = ("T", "P", "PB") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) t = ncvars["T"] p = ncvars["P"] pb = ncvars["PB"] - + full_t = t + Constants.T_BASE full_p = p + pb tk = _tk(full_p, full_t) - + return tk -@copy_and_set_metadata(copy_varname="T", name="theta_e", +@copy_and_set_metadata(copy_varname="T", name="theta_e", description="equivalent potential temperature") @convert_units("temp", "K") -def get_eth(wrfin, timeidx=0, method="cat", squeeze=True, +def get_eth(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="K"): """Return the equivalent potential temperature. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'eth'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'eth'. Default is 'K'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The equivalent potential temperature. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - - varnames=("T", "P", "PB", "QVAPOR") + + varnames = ("T", "P", "PB", "QVAPOR") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) t = ncvars["T"] p = ncvars["P"] pb = ncvars["PB"] qv = ncvars["QVAPOR"] - + full_t = t + Constants.T_BASE full_p = p + pb tk = _tk(full_p, full_t) - + eth = _eth(qv, tk, full_p) - + return eth -@copy_and_set_metadata(copy_varname="T", name="tv", +@copy_and_set_metadata(copy_varname="T", name="tv", description="virtual temperature") @convert_units("temp", "k") -def get_tv(wrfin, timeidx=0, method="cat", squeeze=True, +def get_tv(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="K"): """Return the virtual temperature. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'tv'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'tv'. Default is 'K'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The virtual temperature. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - - varnames=("T", "P", "PB", "QVAPOR") + + varnames = ("T", "P", "PB", "QVAPOR") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) - + t = ncvars["T"] p = ncvars["P"] pb = ncvars["PB"] qv = ncvars["QVAPOR"] - + full_t = t + Constants.T_BASE full_p = p + pb tk = _tk(full_p, full_t) - + tv = _tv(tk, qv) - + return tv - - -@copy_and_set_metadata(copy_varname="T", name="twb", + + +@copy_and_set_metadata(copy_varname="T", name="twb", description="wetbulb temperature") @convert_units("temp", "k") -def get_tw(wrfin, timeidx=0, method="cat", squeeze=True, +def get_tw(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="K"): """Return the wetbulb temperature. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'twb'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'twb'. Default is 'K'. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wetbulb temperature. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - - varnames=("T", "P", "PB", "QVAPOR") + + varnames = ("T", "P", "PB", "QVAPOR") ncvars = extract_vars(wrfin, timeidx, varnames, method, squeeze, cache, meta=False, _key=_key) t = ncvars["T"] p = ncvars["P"] pb = ncvars["PB"] qv = ncvars["QVAPOR"] - + full_t = t + Constants.T_BASE full_p = p + pb - + tk = _tk(full_p, full_t) tw = _wetbulb(full_p, tk, qv) - + return tw -def get_tk(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, +def get_tk(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return the temperature in [K]. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The temperature in [K]. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - return get_temp(wrfin, timeidx, method, squeeze, cache, meta, _key, + return get_temp(wrfin, timeidx, method, squeeze, cache, meta, _key, units="K") def get_tc(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return the temperature in [degC]. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The temperature in [degC]. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ return get_temp(wrfin, timeidx, method, squeeze, cache, meta, _key, units="degC") - - - diff --git a/src/wrf/g_terrain.py b/src/wrf/g_terrain.py index 80910ed..c70110a 100755 --- a/src/wrf/g_terrain.py +++ b/src/wrf/g_terrain.py @@ -6,73 +6,70 @@ from .util import extract_vars, either # Need to handle either -@copy_and_set_metadata(copy_varname=either("HGT", "HGT_M"), name="terrain", +@copy_and_set_metadata(copy_varname=either("HGT", "HGT_M"), name="terrain", description="terrain height") @convert_units("height", "m") -def get_terrain(wrfin, timeidx=0, method="cat", squeeze=True, - cache=None, meta=False, _key=None, units="m"): +def get_terrain(wrfin, timeidx=0, method="cat", squeeze=True, + cache=None, meta=False, _key=None, units="m"): """Return the terrain height in the specified units. - - This functions extracts the necessary variables from the NetCDF file + + This functions extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'ter'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'ter'. Default is 'm'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The terrain - height in the specified units. If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The terrain + height in the specified units. If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ varname = either("HGT", "HGT_M")(wrfin) - - return extract_vars(wrfin, timeidx, varname, + + return extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key)[varname] - - - \ No newline at end of file diff --git a/src/wrf/g_times.py b/src/wrf/g_times.py index 3c46b19..7523a58 100755 --- a/src/wrf/g_times.py +++ b/src/wrf/g_times.py @@ -3,119 +3,118 @@ from __future__ import (absolute_import, division, print_function) from .util import extract_times -def get_times(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, +def get_times(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return a sequence of time objects. - - This function reads the 'Times' variable and creates a sequence of + + This function reads the 'Times' variable and creates a sequence of :class:`datetime.datetime` objects. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - + meta (:obj:`bool`, optional): Set to False to disable metadata. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: A sequence of - :class:`datetime.datetime` objects. If *meta* is True, the sequence - will be of type :class:`xarray.DataArray`, otherwise the sequence is + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: A sequence of + :class:`datetime.datetime` objects. If *meta* is True, the sequence + will be of type :class:`xarray.DataArray`, otherwise the sequence is :class:`numpy.ndarray`. - + """ - return extract_times(wrfin, timeidx, method, squeeze, cache, + return extract_times(wrfin, timeidx, method, squeeze, cache, meta=meta, do_xtime=False) -def get_xtimes(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, +def get_xtimes(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return a sequence of time objects. - - This function reads the 'XTIME' variable and creates a sequence of - :obj:`float` objects. - + + This function reads the 'XTIME' variable and creates a sequence of + :obj:`float` objects. + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - + meta (:obj:`bool`, optional): Set to False to disable metadata. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: A sequence of - :obj:`float` objects. If *meta* is True, the sequence will be of type - :class:`xarray.DataArray`, otherwise the sequence is + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: A sequence of + :obj:`float` objects. If *meta* is True, the sequence will be of type + :class:`xarray.DataArray`, otherwise the sequence is :class:`numpy.ndarray`. - + Raises: - - :class:`KeyError`: Raised if the 'XTIME' variable is not present + + :class:`KeyError`: Raised if the 'XTIME' variable is not present in the NetCDF file. - + """ - return extract_times(wrfin, timeidx, method, squeeze, cache, + return extract_times(wrfin, timeidx, method, squeeze, cache, meta=meta, do_xtime=True) - diff --git a/src/wrf/g_uvmet.py b/src/wrf/g_uvmet.py index dc1d0e0..b748120 100755 --- a/src/wrf/g_uvmet.py +++ b/src/wrf/g_uvmet.py @@ -4,7 +4,6 @@ from math import fabs, log, tan, sin, cos import numpy as np -#from .extension import computeuvmet from .extension import _uvmet from .destag import destagger from .constants import Constants @@ -15,83 +14,83 @@ from .util import extract_vars, extract_global_attrs, either @convert_units("wind", "m s-1") -def _get_uvmet(wrfin, timeidx=0, method="cat", squeeze=True, +def _get_uvmet(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, ten_m=False, units="m s-1"): """Return the u,v wind components rotated to earth coordinates. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain U_EARTH - return_val[1,...] will contain V_EARTH - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - ten_m (:obj:`bool`, optional): Set to True to use the 10m surface - winds, rather than the three-dimensional wind field. Default is + + ten_m (:obj:`bool`, optional): Set to True to use the 10m surface + winds, rather than the three-dimensional wind field. Default is False. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet'. Default is 'm s-1'. - + Returns: - - :class:`numpy.ndarray`: The u,v components of the wind rotated to - earth coordinates, whose leftmost dimensions is 2 (0=U, 1=V). The - *meta* parameter is ignored for this function, so only a + + :class:`numpy.ndarray`: The u,v components of the wind rotated to + earth coordinates, whose leftmost dimensions is 2 (0=U, 1=V). The + *meta* parameter is ignored for this function, so only a :class:`numpy.ndarray` is returned. - + """ - + if not ten_m: varname = either("U", "UU")(wrfin) u_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) - + u = destagger(u_vars[varname], -1) - + varname = either("V", "VV")(wrfin) v_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) @@ -100,40 +99,40 @@ def _get_uvmet(wrfin, timeidx=0, method="cat", squeeze=True, varname = either("U10", "UU")(wrfin) u_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) - u = (u_vars[varname] if varname == "U10" else - destagger(u_vars[varname][...,0,:,:], -1)) - + u = (u_vars[varname] if varname == "U10" else + destagger(u_vars[varname][..., 0, :, :], -1)) + varname = either("V10", "VV")(wrfin) v_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) - v = (v_vars[varname] if varname == "V10" else - destagger(v_vars[varname][...,0,:,:], -2)) - + v = (v_vars[varname] if varname == "V10" else + destagger(v_vars[varname][..., 0, :, :], -2)) + map_proj_attrs = extract_global_attrs(wrfin, attrs="MAP_PROJ") map_proj = map_proj_attrs["MAP_PROJ"] - + # 1 - Lambert # 2 - Polar Stereographic # 3 - Mercator # 6 - Lat/Lon - # Note: NCL has no code to handle other projections (0,4,5) as they + # Note: NCL has no code to handle other projections (0,4,5) as they # don't appear to be supported any longer - - if map_proj in (0,3,6): + + if map_proj in (0, 3, 6): # No rotation needed for Mercator and Lat/Lon, but still need # u,v aggregated in to one array - + end_idx = -3 if not ten_m else -2 resdim = (2,) + u.shape[0:end_idx] + u.shape[end_idx:] - + # Make a new output array for the result result = np.empty(resdim, u.dtype) - + # For 2D array, this makes (0,...,:,:) and (1,...,:,:) # For 3D array, this makes (0,...,:,:,:) and (1,...,:,:,:) idx0 = (0,) + (Ellipsis,) + (slice(None),)*(-end_idx) idx1 = (1,) + (Ellipsis,) + (slice(None),)*(-end_idx) - + try: fill = u.fill_value except AttributeError: @@ -143,16 +142,16 @@ def _get_uvmet(wrfin, timeidx=0, method="cat", squeeze=True, result[idx0] = np.ma.filled(u[:], fill) result[idx1] = np.ma.filled(v[:], fill) result = np.ma.masked_values(result, fill) - + return result - elif map_proj in (1,2): + elif map_proj in (1, 2): lat_attrs = extract_global_attrs(wrfin, attrs=("TRUELAT1", "TRUELAT2")) radians_per_degree = Constants.PI/180.0 # Rotation needed for Lambert and Polar Stereographic true_lat1 = lat_attrs["TRUELAT1"] true_lat2 = lat_attrs["TRUELAT2"] - + try: lon_attrs = extract_global_attrs(wrfin, attrs="STAND_LON") except AttributeError: @@ -164,643 +163,641 @@ def _get_uvmet(wrfin, timeidx=0, method="cat", squeeze=True, cen_lon = cen_lon_attrs["CEN_LON"] else: cen_lon = lon_attrs["STAND_LON"] - - + varname = either("XLAT_M", "XLAT")(wrfin) - xlat_var = extract_vars(wrfin, timeidx, varname, + xlat_var = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) lat = xlat_var[varname] - + varname = either("XLONG_M", "XLONG")(wrfin) - xlon_var = extract_vars(wrfin, timeidx, varname, + xlon_var = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) lon = xlon_var[varname] - + if map_proj == 1: if((fabs(true_lat1 - true_lat2) > 0.1) and - (fabs(true_lat2 - 90.) > 0.1)): - cone = (log(cos(true_lat1*radians_per_degree)) - - log(cos(true_lat2*radians_per_degree))) - cone = (cone / - (log(tan((45.-fabs(true_lat1/2.))*radians_per_degree)) - - log(tan((45.-fabs(true_lat2/2.))*radians_per_degree)))) + (fabs(true_lat2 - 90.) > 0.1)): + cone = (log(cos(true_lat1*radians_per_degree)) - + log(cos(true_lat2*radians_per_degree))) + cone = (cone / + (log(tan((45.-fabs(true_lat1/2.))*radians_per_degree)) + - log(tan((45.-fabs(true_lat2/2.)) * + radians_per_degree)))) else: cone = sin(fabs(true_lat1)*radians_per_degree) else: cone = 1 - + result = _uvmet(u, v, lat, lon, cen_lon, cone) - + if squeeze: result = result.squeeze() - + return result - -@set_wind_metadata(copy_varname=either("P", "PRES"), + +@set_wind_metadata(copy_varname=either("P", "PRES"), name="uvmet", description="earth rotated u,v", - two_d=False, - wspd_wdir=False) -def get_uvmet(wrfin, timeidx=0, method="cat", squeeze=True, + two_d=False, + wspd_wdir=False) +def get_uvmet(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): """Return the u,v wind components rotated to earth coordinates. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain U_EARTH - return_val[1,...] will contain V_EARTH - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet'. Default + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The u,v components - of the wind rotated to earth coordinates, whose leftmost dimensions is - 2 (0=U_EARTH, 1=V_EARTH). - If xarray is enabled and the *meta* parameter is True, - then the result will be a :class:`xarray.DataArray` object. Otherwise, + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The u,v components + of the wind rotated to earth coordinates, whose leftmost dimensions is + 2 (0=U_EARTH, 1=V_EARTH). + If xarray is enabled and the *meta* parameter is True, + then the result will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - + return _get_uvmet(wrfin, timeidx, method, squeeze, cache, meta, _key, False, units) -@set_wind_metadata(copy_varname=either("PSFC", "F"), +@set_wind_metadata(copy_varname=either("PSFC", "F"), name="uvmet10", description="10m earth rotated u,v", - two_d=True, + two_d=True, wspd_wdir=False) -def get_uvmet10(wrfin, timeidx=0, method="cat", squeeze=True, +def get_uvmet10(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): - """Return the u,v components for the 10m winds rotated to earth + """Return the u,v components for the 10m winds rotated to earth coordinates. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain U10_EARTH - return_val[1,...] will contain V10_EARTH - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet10'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet10'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The u,v components - of the 10m wind rotated to earth coordinates, whose leftmost dimensions - is 2 (0=U10_EARTH, 1=V10_EARTH). - If xarray is enabled and the *meta* parameter is - True, then the result will be a :class:`xarray.DataArray` object. - Otherwise, the result will be a :class:`numpy.ndarray` object with no + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The u,v components + of the 10m wind rotated to earth coordinates, whose leftmost dimensions + is 2 (0=U10_EARTH, 1=V10_EARTH). + If xarray is enabled and the *meta* parameter is + True, then the result will be a :class:`xarray.DataArray` object. + Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - - return _get_uvmet(wrfin, timeidx, method, squeeze, cache, meta, _key, + + return _get_uvmet(wrfin, timeidx, method, squeeze, cache, meta, _key, True, units) -@set_wind_metadata(copy_varname=either("P", "PRES"), +@set_wind_metadata(copy_varname=either("P", "PRES"), name="uvmet_wspd_wdir", description="earth rotated wspd,wdir", - two_d=False, + two_d=False, wspd_wdir=True) -def get_uvmet_wspd_wdir(wrfin, timeidx=0, method="cat", squeeze=True, +def get_uvmet_wspd_wdir(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): - """Return the wind speed and wind direction for the wind rotated to + """Return the wind speed and wind direction for the wind rotated to earth coordinates. - + This function should be used when comparing with observations. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain WSPD_EARTH - return_val[1,...] will contain WDIR_EARTH - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet_wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet_wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed and - wind direction for the wind rotated to earth coordinates, whose - leftmost dimensions is 2 (0=WSPD_EARTH, 1=WDIR_EARTH). If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed and + wind direction for the wind rotated to earth coordinates, whose + leftmost dimensions is 2 (0=WSPD_EARTH, 1=WDIR_EARTH). If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - - uvmet = _get_uvmet(wrfin, timeidx, method, squeeze, + + uvmet = _get_uvmet(wrfin, timeidx, method, squeeze, cache, meta, _key, False, units="m s-1") - - return _calc_wspd_wdir(uvmet[0,...,:,:,:], uvmet[1,...,:,:,:], + + return _calc_wspd_wdir(uvmet[0, ..., :, :, :], uvmet[1, ..., :, :, :], False, units) - -@set_wind_metadata(copy_varname=either("PSFC", "F"), + +@set_wind_metadata(copy_varname=either("PSFC", "F"), name="uvmet10_wspd_wdir", description="10m earth rotated wspd,wdir", - two_d=True, + two_d=True, wspd_wdir=True) -def get_uvmet10_wspd_wdir(wrfin, timeidx=0, method="cat", squeeze=True, +def get_uvmet10_wspd_wdir(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): - """Return the wind speed and wind direction for the 10m wind rotated to + """Return the wind speed and wind direction for the 10m wind rotated to earth coordinates. - + This function should be used when comparing with observations. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain WSPD10_EARTH - return_val[1,...] will contain WDIR10_EARTH - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet10_wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed and - wind direction for the 10m wind rotated to earth coordinates, whose - leftmost dimensions is 2 (0=WSPD10_EARTH, 1=WDIR10_EARTH). If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed and + wind direction for the 10m wind rotated to earth coordinates, whose + leftmost dimensions is 2 (0=WSPD10_EARTH, 1=WDIR10_EARTH). If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - - uvmet10 = _get_uvmet(wrfin, timeidx, method, squeeze, cache, meta, _key, + + uvmet10 = _get_uvmet(wrfin, timeidx, method, squeeze, cache, meta, _key, True, units="m s-1") - - return _calc_wspd_wdir(uvmet10[0,...,:,:], uvmet10[1,...,:,:], True, units) - -def get_uvmet_wspd(wrfin, timeidx=0, method="cat", squeeze=True, + return _calc_wspd_wdir(uvmet10[0, ..., :, :], uvmet10[1, ..., :, :], + True, units) + + +def get_uvmet_wspd(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): """Return the wind speed for the wind rotated to earth coordinates. - + This function should be used when comparing with observations. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet_wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet_wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed - for the wind rotated to earth coordinates. If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed + for the wind rotated to earth coordinates. If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_uvmet_wspd_wdir(wrfin, timeidx, method, squeeze, - cache, meta, _key, units)[0,:] - + result = get_uvmet_wspd_wdir(wrfin, timeidx, method, squeeze, + cache, meta, _key, units)[0, :] + if meta: result.attrs["description"] = "earth rotated wspd" - + return result - - -def get_uvmet_wdir(wrfin, timeidx=0, method="cat", squeeze=True, + + +def get_uvmet_wdir(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): """Return the wind direction for the wind rotated to earth coordinates. - + This function should be used when comparing with observations. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet_wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet_wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind direction - for the wind rotated to earth coordinates. If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind direction + for the wind rotated to earth coordinates. If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_uvmet_wspd_wdir(wrfin, timeidx, method, squeeze, - cache, meta, _key, units)[1,:] - + result = get_uvmet_wspd_wdir(wrfin, timeidx, method, squeeze, + cache, meta, _key, units)[1, :] + if meta: result.attrs["description"] = "earth rotated wdir" - + return result - - -def get_uvmet10_wspd(wrfin, timeidx=0, method="cat", squeeze=True, - cache=None, meta=True, _key=None, - units="m s-1"): + + +def get_uvmet10_wspd(wrfin, timeidx=0, method="cat", squeeze=True, + cache=None, meta=True, _key=None, + units="m s-1"): """Return the wind speed for the 10m wind rotated to earth coordinates. - + This function should be used when comparing with observations. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet_wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet_wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed - for the 10m wind rotated to earth coordinates. If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed + for the 10m wind rotated to earth coordinates. If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_uvmet10_wspd_wdir(wrfin, timeidx, method, squeeze, - cache, meta, _key, units)[0,:] + result = get_uvmet10_wspd_wdir(wrfin, timeidx, method, squeeze, + cache, meta, _key, units)[0, :] if meta: result.attrs["description"] = "10m earth rotated wspd" - + return result - - -def get_uvmet10_wdir(wrfin, timeidx=0, method="cat", squeeze=True, - cache=None, meta=True, _key=None, - units="m s-1"): + + +def get_uvmet10_wdir(wrfin, timeidx=0, method="cat", squeeze=True, + cache=None, meta=True, _key=None, + units="m s-1"): """Return the wind direction for the 10m wind rotated to earth coordinates. - + This function should be used when comparing with observations. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet_wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet_wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind direction - for the 10m wind rotated to earth coordinates. If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind direction + for the 10m wind rotated to earth coordinates. If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_uvmet10_wspd_wdir(wrfin, timeidx, method, squeeze, - cache, meta, _key, units)[1,:] - + result = get_uvmet10_wspd_wdir(wrfin, timeidx, method, squeeze, + cache, meta, _key, units)[1, :] + if meta: result.attrs["description"] = "10m earth rotated wdir" - + return result - - - \ No newline at end of file diff --git a/src/wrf/g_vorticity.py b/src/wrf/g_vorticity.py index 660f688..0d00a12 100755 --- a/src/wrf/g_vorticity.py +++ b/src/wrf/g_vorticity.py @@ -5,69 +5,69 @@ from .util import extract_vars, extract_global_attrs from .metadecorators import copy_and_set_metadata -@copy_and_set_metadata(copy_varname="T", name="avo", +@copy_and_set_metadata(copy_varname="T", name="avo", description="absolute vorticity", units="10-5 s-1") -def get_avo(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, +def get_avo(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return the absolute vorticity. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The absolute - vorticity. If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The absolute + vorticity. If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ ncvars = extract_vars(wrfin, timeidx, ("U", "V", "MAPFAC_U", "MAPFAC_V", "MAPFAC_M", "F"), method, squeeze, cache, meta=False, _key=_key) - + attrs = extract_global_attrs(wrfin, attrs=("DX", "DY")) u = ncvars["U"] v = ncvars["V"] @@ -75,70 +75,70 @@ def get_avo(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, msfv = ncvars["MAPFAC_V"] msfm = ncvars["MAPFAC_M"] cor = ncvars["F"] - + dx = attrs["DX"] dy = attrs["DY"] - + return _avo(u, v, msfu, msfv, msfm, cor, dx, dy) -@copy_and_set_metadata(copy_varname="T", name="pvo", +@copy_and_set_metadata(copy_varname="T", name="pvo", description="potential vorticity", units="PVU") -def get_pvo(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, +def get_pvo(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None): """Return the potential vorticity. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The potential - vorticity. If xarray is - enabled and the *meta* parameter is True, then the result will be a - :class:`xarray.DataArray` object. Otherwise, the result will be a + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The potential + vorticity. If xarray is + enabled and the *meta* parameter is True, then the result will be a + :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ ncvars = extract_vars(wrfin, timeidx, ("U", "V", "T", "P", "PB", "MAPFAC_U", @@ -146,7 +146,7 @@ def get_pvo(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, "F"), method, squeeze, cache, meta=False, _key=_key) attrs = extract_global_attrs(wrfin, attrs=("DX", "DY")) - + u = ncvars["U"] v = ncvars["V"] t = ncvars["T"] @@ -156,12 +156,11 @@ def get_pvo(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, msfv = ncvars["MAPFAC_V"] msfm = ncvars["MAPFAC_M"] cor = ncvars["F"] - + dx = attrs["DX"] dy = attrs["DY"] - + full_t = t + 300 full_p = p + pb - + return _pvo(u, v, full_t, full_p, msfu, msfv, msfm, cor, dx, dy) - \ No newline at end of file diff --git a/src/wrf/g_wind.py b/src/wrf/g_wind.py index 9edaeea..bdfbca1 100755 --- a/src/wrf/g_wind.py +++ b/src/wrf/g_wind.py @@ -12,776 +12,773 @@ from .metadecorators import set_wind_metadata @convert_units("wind", "m s-1") def _calc_wspd(u, v, units="m s-1"): """Return the wind speed. - + Args: - + u (:class:`numpy.ndarray`): The u component of the wind. - + v (:class:`numpy.ndarray`): The v component of the wind. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet_wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet_wspd_wdir'. Default is 'm s-1'. - + Returns: - + :class:`numpy.ndarray`: The wind speed. - + """ return _wspd(u, v) def _calc_wdir(u, v): """Return the wind direction. - + Args: - + u (:class:`numpy.ndarray`): The u component of the wind. - + v (:class:`numpy.ndarray`): The v component of the wind. - + Returns: - + :class:`numpy.ndarray`: The wind direction. - + """ return _wdir(u, v) def _calc_wspd_wdir(u, v, two_d, units): """Return the wind speed and wind direction. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain WSPD - return_val[1,...] will contain WDIR - + Args: - + u (:class:`numpy.ndarray`): The u component of the wind. - + v (:class:`numpy.ndarray`): The v component of the wind. - - two_d (:obj:`bool`): Set to True if the u,v wind components are + + two_d (:obj:`bool`): Set to True if the u,v wind components are for a two-dimensional array (no height dimension). Otherwise, set to False. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'uvmet_wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'uvmet_wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`numpy.ndarray`: The wind speed and wind direction, whose + + :class:`numpy.ndarray`: The wind speed and wind direction, whose leftmost dimension is 2 (0=WSPD, 1=WDIR). - + """ wspd = _calc_wspd(u, v, units) wdir = _calc_wdir(u, v) - + try: fill = wspd.fill_value except AttributeError: fill = None idx_end = -2 if two_d else -3 - + outdims = [2] + list(wspd.shape[0:idx_end]) + list(wspd.shape[idx_end:]) - + result = np.zeros(outdims, wspd.dtype) - - idxs0 = ((0,Ellipsis, slice(None), slice(None), slice(None)) - if not two_d else - (0, Ellipsis, slice(None), slice(None))) - - idxs1 = ((1, Ellipsis, slice(None), slice(None), slice(None)) - if not two_d else - (1, Ellipsis, slice(None), slice(None))) - + + idxs0 = ((0, Ellipsis, slice(None), slice(None), slice(None)) + if not two_d else (0, Ellipsis, slice(None), slice(None))) + + idxs1 = ((1, Ellipsis, slice(None), slice(None), slice(None)) + if not two_d else (1, Ellipsis, slice(None), slice(None))) + result[idxs0] = wspd[:] result[idxs1] = wdir[:] - + if fill is not None: result = np.ma.masked_equal(result, fill) - + return result -@set_wind_metadata(copy_varname=either("P", "PRES"), +@set_wind_metadata(copy_varname=either("P", "PRES"), name="ua", description="destaggered u-wind component", - wind_ncvar=True, - two_d=False, + wind_ncvar=True, + two_d=False, wspd_wdir=False) @convert_units("wind", "m s-1") -def get_u_destag(wrfin, timeidx=0, method="cat", squeeze=True, +def get_u_destag(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): """Return the u-component of the wind on mass points. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The u-component - of the wind. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The u-component + of the wind. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ varname = either("U", "UU")(wrfin) u_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) u = destagger(u_vars[varname], -1) - + return u -@set_wind_metadata(copy_varname=either("P", "PRES"), +@set_wind_metadata(copy_varname=either("P", "PRES"), name="va", description="destaggered v-wind component", two_d=False, - wind_ncvar=True, + wind_ncvar=True, wspd_wdir=False) @convert_units("wind", "m s-1") -def get_v_destag(wrfin, timeidx=0, method="cat", squeeze=True, +def get_v_destag(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): """Return the v-component of the wind on mass points. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The v-component - of the wind. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The v-component + of the wind. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ varname = either("V", "VV")(wrfin) v_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) v = destagger(v_vars[varname], -2) - + return v -@set_wind_metadata(copy_varname=either("P", "PRES"), +@set_wind_metadata(copy_varname=either("P", "PRES"), name="wa", description="destaggered w-wind component", two_d=False, - wind_ncvar=True, + wind_ncvar=True, wspd_wdir=False) @convert_units("wind", "m s-1") -def get_w_destag(wrfin, timeidx=0, method="cat", squeeze=True, +def get_w_destag(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): """Return the w-component of the wind on mass points. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The w-component - of the wind. - If xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The w-component + of the wind. + If xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - w_vars = extract_vars(wrfin, timeidx, "W", method, squeeze, cache, + w_vars = extract_vars(wrfin, timeidx, "W", method, squeeze, cache, meta=False, _key=_key) w = destagger(w_vars["W"], -3) return w -@set_wind_metadata(copy_varname=either("P", "PRES"), +@set_wind_metadata(copy_varname=either("P", "PRES"), name="wspd_wdir", description="wspd,wdir in projection space", - two_d=False, + two_d=False, wspd_wdir=True) -def get_destag_wspd_wdir(wrfin, timeidx=0, method="cat", +def get_destag_wspd_wdir(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): """Return the wind speed and wind direction for the wind in the projected - coordinate (i.e. grid) space. - - The wind speed and direction from this function will be relative to the - grid. This function should not be used to compare with observations, - instead use :meth:`wrf.uvmet10_wspd_wdir` to get the earth relative wind + coordinate (i.e. grid) space. + + The wind speed and direction from this function will be relative to the + grid. This function should not be used to compare with observations, + instead use :meth:`wrf.uvmet10_wspd_wdir` to get the earth relative wind speed and direction. - - The leftmost dimension of the returned array represents two different + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain WSPD - return_val[1,...] will contain WDIR - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed and - wind direction for the wind in projected space, whose - leftmost dimensions is 2 (0=WSPD, 1=WDIR). If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed and + wind direction for the wind in projected space, whose + leftmost dimensions is 2 (0=WSPD, 1=WDIR). If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ varname = either("U", "UU")(wrfin) u_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) u = destagger(u_vars[varname], -1) - + varname = either("V", "VV")(wrfin) v_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) v = destagger(v_vars[varname], -2) - + return _calc_wspd_wdir(u, v, False, units) -@set_wind_metadata(copy_varname=either("PSFC", "F"), +@set_wind_metadata(copy_varname=either("PSFC", "F"), name="wspd_wdir10", description="10m wspd,wdir in projection space", - two_d=False, + two_d=False, wspd_wdir=True) -def get_destag_wspd_wdir10(wrfin, timeidx=0, method="cat", - squeeze=True, cache=None, meta=True, _key=None, +def get_destag_wspd_wdir10(wrfin, timeidx=0, method="cat", + squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): - """Return the wind speed and wind direction for the 10m wind in + """Return the wind speed and wind direction for the 10m wind in projected coordinate (i.e. grid) space. - - The wind speed and direction from this function will be relative to the - grid. This function should not be used to compare with observations, - instead use :meth:`wrf.uvmet10_wspd_wdir` to get the earth relative wind - speed and direction. - - The leftmost dimension of the returned array represents two different + + The wind speed and direction from this function will be relative to the + grid. This function should not be used to compare with observations, + instead use :meth:`wrf.uvmet10_wspd_wdir` to get the earth relative wind + speed and direction. + + The leftmost dimension of the returned array represents two different quantities: - + - return_val[0,...] will contain WSPD10 - return_val[1,...] will contain WDIR10 - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'wspd_wdir10'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed and - wind direction for the 10m wind in projected space, whose - leftmost dimensions is 2 (0=WSPD10, 1=WDIR10). If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed and + wind direction for the 10m wind in projected space, whose + leftmost dimensions is 2 (0=WSPD10, 1=WDIR10). If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - + varname = either("U10", "UU")(wrfin) u_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) - u = (u_vars[varname] if varname == "U10" else - destagger(u_vars[varname][...,0,:,:], -1)) - + u = (u_vars[varname] if varname == "U10" else + destagger(u_vars[varname][..., 0, :, :], -1)) + varname = either("V10", "VV")(wrfin) v_vars = extract_vars(wrfin, timeidx, varname, method, squeeze, cache, meta=False, _key=_key) - v = (v_vars[varname] if varname == "V10" else - destagger(v_vars[varname][...,0,:,:], -2)) - + v = (v_vars[varname] if varname == "V10" else + destagger(v_vars[varname][..., 0, :, :], -2)) + return _calc_wspd_wdir(u, v, True, units) -def get_destag_wspd(wrfin, timeidx=0, method="cat", +def get_destag_wspd(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): - """Return the wind speed in the projected coordinate (i.e. grid) space. - - This function extracts the necessary variables from the NetCDF file + """Return the wind speed in the projected coordinate (i.e. grid) space. + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind - speed in projected space. If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind + speed in projected space. If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_destag_wspd_wdir(wrfin, timeidx, method, squeeze, cache, - meta, _key, units)[0,:] - + result = get_destag_wspd_wdir(wrfin, timeidx, method, squeeze, cache, + meta, _key, units)[0, :] + if meta: result.attrs["description"] = "wspd in projection space" - + return result - - -def get_destag_wdir(wrfin, timeidx=0, method="cat", + + +def get_destag_wdir(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): """Return the wind direction in the projected coordinate (i.e. grid) space. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for 'wspd_wdir'. + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'wspd_wdir'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind - direction in projected space. If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind + direction in projected space. If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_destag_wspd_wdir(wrfin, timeidx, method, squeeze, cache, - meta, _key, units)[1,:] - + result = get_destag_wspd_wdir(wrfin, timeidx, method, squeeze, cache, + meta, _key, units)[1, :] + if meta: result.attrs["description"] = "wdir in projection space" - + return result - - -def get_destag_wspd10(wrfin, timeidx=0, method="cat", - squeeze=True, cache=None, meta=True, _key=None, + + +def get_destag_wspd10(wrfin, timeidx=0, method="cat", + squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): - """Return the wind speed for the 10m wind in projected coordinate + """Return the wind speed for the 10m wind in projected coordinate (i.e. grid) space. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'wspd_wdir10'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed - for the 10m wind in projected space. If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind speed + for the 10m wind in projected space. If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_destag_wspd_wdir10(wrfin, timeidx, method, - squeeze, cache, meta, _key, units)[0,:] - + result = get_destag_wspd_wdir10(wrfin, timeidx, method, + squeeze, cache, meta, _key, units)[0, :] + if meta: result.attrs["description"] = "10m wspd in projection space" - + return result - - -def get_destag_wdir10(wrfin, timeidx=0, method="cat", - squeeze=True, cache=None, meta=True, _key=None, + + +def get_destag_wdir10(wrfin, timeidx=0, method="cat", + squeeze=True, cache=None, meta=True, _key=None, units="m s-1"): - """Return the wind direction for the 10m wind in projected coordinate + """Return the wind direction for the 10m wind in projected coordinate (i.e. grid) space. - - This function extracts the necessary variables from the NetCDF file + + This function extracts the necessary variables from the NetCDF file object in order to perform the calculation. - + Args: - + wrfin (:class:`netCDF4.Dataset`, :class:`Nio.NioFile`, or an \ - iterable): WRF-ARW NetCDF - data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` + iterable): WRF-ARW NetCDF + data as a :class:`netCDF4.Dataset`, :class:`Nio.NioFile` or an iterable sequence of the aforementioned types. - - timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The - desired time index. This value can be a positive integer, - negative integer, or - :data:`wrf.ALL_TIMES` (an alias for None) to return + + timeidx (:obj:`int` or :data:`wrf.ALL_TIMES`, optional): The + desired time index. This value can be a positive integer, + negative integer, or + :data:`wrf.ALL_TIMES` (an alias for None) to return all times in the file or sequence. The default is 0. - - method (:obj:`str`, optional): The aggregation method to use for - sequences. Must be either 'cat' or 'join'. - 'cat' combines the data along the Time dimension. - 'join' creates a new dimension for the file index. + + method (:obj:`str`, optional): The aggregation method to use for + sequences. Must be either 'cat' or 'join'. + 'cat' combines the data along the Time dimension. + 'join' creates a new dimension for the file index. The default is 'cat'. - - squeeze (:obj:`bool`, optional): Set to False to prevent dimensions - with a size of 1 from being automatically removed from the shape + + squeeze (:obj:`bool`, optional): Set to False to prevent dimensions + with a size of 1 from being automatically removed from the shape of the output. Default is True. - - cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) - that can be used to supply pre-extracted NetCDF variables to the - computational routines. It is primarily used for internal - purposes, but can also be used to improve performance by - eliminating the need to repeatedly extract the same variables - used in multiple diagnostics calculations, particularly when using - large sequences of files. + + cache (:obj:`dict`, optional): A dictionary of (varname, ndarray) + that can be used to supply pre-extracted NetCDF variables to the + computational routines. It is primarily used for internal + purposes, but can also be used to improve performance by + eliminating the need to repeatedly extract the same variables + used in multiple diagnostics calculations, particularly when using + large sequences of files. Default is None. - - meta (:obj:`bool`, optional): Set to False to disable metadata and - return :class:`numpy.ndarray` instead of + + meta (:obj:`bool`, optional): Set to False to disable metadata and + return :class:`numpy.ndarray` instead of :class:`xarray.DataArray`. Default is True. - - _key (:obj:`int`, optional): A caching key. This is used for internal + + _key (:obj:`int`, optional): A caching key. This is used for internal purposes only. Default is None. - - units (:obj:`str`): The desired units. Refer to the :meth:`getvar` - product table for a list of available units for + + units (:obj:`str`): The desired units. Refer to the :meth:`getvar` + product table for a list of available units for 'wspd_wdir10'. Default is 'm s-1'. - + Returns: - - :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind direction - for the 10m wind in projected space. If - xarray is enabled and the *meta* parameter is True, then the result - will be a :class:`xarray.DataArray` object. Otherwise, the result will + + :class:`xarray.DataArray` or :class:`numpy.ndarray`: The wind direction + for the 10m wind in projected space. If + xarray is enabled and the *meta* parameter is True, then the result + will be a :class:`xarray.DataArray` object. Otherwise, the result will be a :class:`numpy.ndarray` object with no metadata. - + """ - result = get_destag_wspd_wdir10(wrfin, timeidx, method, - squeeze, cache, meta, _key, units)[1,:] - + result = get_destag_wspd_wdir10(wrfin, timeidx, method, + squeeze, cache, meta, _key, units)[1, :] + if meta: result.attrs["description"] = "10m wdir in projection space" - + return result -