diff --git a/doc/source/_static/images/basemap_500.png b/doc/source/_static/images/basemap_500.png index 5d9d86e..71c8ce9 100644 Binary files a/doc/source/_static/images/basemap_500.png and b/doc/source/_static/images/basemap_500.png differ diff --git a/doc/source/_static/images/basemap_front.png b/doc/source/_static/images/basemap_front.png index c2eb6a6..3282dc4 100644 Binary files a/doc/source/_static/images/basemap_front.png and b/doc/source/_static/images/basemap_front.png differ diff --git a/doc/source/_static/images/basemap_slp.png b/doc/source/_static/images/basemap_slp.png index afd8258..5977ce7 100644 Binary files a/doc/source/_static/images/basemap_slp.png and b/doc/source/_static/images/basemap_slp.png differ diff --git a/doc/source/_static/images/cartopy_500.png b/doc/source/_static/images/cartopy_500.png index cc012f8..fec8167 100644 Binary files a/doc/source/_static/images/cartopy_500.png and b/doc/source/_static/images/cartopy_500.png differ diff --git a/doc/source/_static/images/cartopy_cross.png b/doc/source/_static/images/cartopy_cross.png index fc7297e..f558ba3 100644 Binary files a/doc/source/_static/images/cartopy_cross.png and b/doc/source/_static/images/cartopy_cross.png differ diff --git a/doc/source/_static/images/cartopy_slp.png b/doc/source/_static/images/cartopy_slp.png index 9195c61..5d86502 100644 Binary files a/doc/source/_static/images/cartopy_slp.png and b/doc/source/_static/images/cartopy_slp.png differ diff --git a/doc/source/_static/images/cross_mtns.png b/doc/source/_static/images/cross_mtns.png new file mode 100644 index 0000000..967b460 Binary files /dev/null and b/doc/source/_static/images/cross_mtns.png differ diff --git a/doc/source/_static/images/matthew.png b/doc/source/_static/images/matthew.png index 2224b15..a989be6 100644 Binary files a/doc/source/_static/images/matthew.png and b/doc/source/_static/images/matthew.png differ diff --git a/doc/source/_static/images/matthew_cross.png b/doc/source/_static/images/matthew_cross.png index 81fe199..b86f5ec 100644 Binary files a/doc/source/_static/images/matthew_cross.png and b/doc/source/_static/images/matthew_cross.png differ diff --git a/doc/source/_templates/product_table.txt b/doc/source/_templates/product_table.txt index b2ee337..e3fe65b 100644 --- a/doc/source/_templates/product_table.txt +++ b/doc/source/_templates/product_table.txt @@ -9,9 +9,9 @@ | | | | | | | | degF | | +--------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| cape_2d | 2D cape (mcape/mcin/lcl/lfc) | J kg-1 ; J kg-1 ; m ; m | **missing** (float): Fill value for output only | +| cape_2d | 2D CAPE (MCAPE/MCIN/LCL/LFC) | J kg-1 ; J kg-1 ; m ; m | **missing** (float): Fill value for output only | +--------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ -| cape_3d | 3D cape and cin | J kg-1 | **missing** (float): Fill value for output only | +| cape_3d | 3D CAPE and CIN | J kg-1 | **missing** (float): Fill value for output only | +--------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ | ctt | Cloud Top Temperature | degC | **fill_nocloud** (boolean): Set to True to use fill values for cloud free regions rather than surface temperature. Default is *False*. | | | | | | diff --git a/doc/source/_templates/subproducts.txt b/doc/source/_templates/subproducts.txt new file mode 100644 index 0000000..a13b2db --- /dev/null +++ b/doc/source/_templates/subproducts.txt @@ -0,0 +1,119 @@ ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Variable Name | Calculated From | Description | Available Units | Additional Keyword Arguments | ++====================+======================+===============================================================+=============================+=========================================================================================================================================================+ +| mcape | cape_2d | 2D Max CAPE | J kg-1 | **missing** (float): Fill value for output only | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| mcin | cape_2d | 2D Max CIN | J kg-1 | **missing** (float): Fill value for output only | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lcl | cape_2d | 2D Lifted Condensation Level | J kg-1 | **missing** (float): Fill value for output only | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lfc | cape_2d | 2D Level of Free Convection | J kg-1 | **missing** (float): Fill value for output only | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| cape3d_only | cape_3d | 3D CAPE | J kg-1 | **missing** (float): Fill value for output only | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| cin3d_only | cape_3d | 3D CIN | J kg-1 | **missing** (float): Fill value for output only | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| low_cloudfrac | cloudfrac | Cloud Fraction for Low Clouds | % | **vert_type** (str): The vertical coordinate type for the cloud thresholds. Must be 'height_agl', 'height_msl', or 'pres'. Default is 'height_agl'. | +| | | | | | +| | | | | **low_thresh** (float): The low cloud threshold (meters for 'height_agl' and 'height_msl', pascals for 'pres'). Default is 300 m (97000 Pa) | +| | | | | | +| | | | | **mid_thresh** (float): The mid cloud threshold (meters for 'height_agl' and 'height_msl', pascals for 'pres'). Default is 2000 m (80000 Pa) | +| | | | | | +| | | | | **high_thresh** (float): The high cloud threshold (meters for 'height_agl' and 'height_msl', pascals for 'pres'). Default is 6000 m (45000 Pa) | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| mid_cloudfrac | cloudfrac | Cloud Fraction for Mid Clouds | % | **vert_type** (str): The vertical coordinate type for the cloud thresholds. Must be 'height_agl', 'height_msl', or 'pres'. Default is 'height_agl'. | +| | | | | | +| | | | | **low_thresh** (float): The low cloud threshold (meters for 'height_agl' and 'height_msl', pascals for 'pres'). Default is 300 m (97000 Pa) | +| | | | | | +| | | | | **mid_thresh** (float): The mid cloud threshold (meters for 'height_agl' and 'height_msl', pascals for 'pres'). Default is 2000 m (80000 Pa) | +| | | | | | +| | | | | **high_thresh** (float): The high cloud threshold (meters for 'height_agl' and 'height_msl', pascals for 'pres'). Default is 6000 m (45000 Pa) | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| high_cloudfrac | cloudfrac | Cloud Fraction for High Clouds | % | **vert_type** (str): The vertical coordinate type for the cloud thresholds. Must be 'height_agl', 'height_msl', or 'pres'. Default is 'height_agl'. | +| | | | | | +| | | | | **low_thresh** (float): The low cloud threshold (meters for 'height_agl' and 'height_msl', pascals for 'pres'). Default is 300 m (97000 Pa) | +| | | | | | +| | | | | **mid_thresh** (float): The mid cloud threshold (meters for 'height_agl' and 'height_msl', pascals for 'pres'). Default is 2000 m (80000 Pa) | +| | | | | | +| | | | | **high_thresh** (float): The high cloud threshold (meters for 'height_agl' and 'height_msl', pascals for 'pres'). Default is 6000 m (45000 Pa) | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uvmet_wspd | uvmet_wspd_wdir | Wind Speed | m s-1 | **units** (str) : Set to desired units. Default is *'m s-1'*. | +| | | | | | +| | | Rotated to Earth Coordinates | km h-1 | | +| | | | | | +| | | | mi h-1 | | +| | | | | | +| | | | kt | | +| | | | | | +| | | | ft s-1 | | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uvmet_wdir | uvmet_wspd_wdir | Wind Direction (wind_from_direction) | m s-1 | **units** (str) : Set to desired units. Default is *'m s-1'*. | +| | | | | | +| | | Rotated to Earth Coordinates | km h-1 | | +| | | | | | +| | | | mi h-1 | | +| | | | | | +| | | | kt | | +| | | | | | +| | | | ft s-1 | | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uvmet10_wspd | uvmet10_wspd_wdir | 10m Wind Speed | m s-1 | **units** (str) : Set to desired units. Default is *'m s-1'*. | +| | | | | | +| | | Rotated to Earth Coordinates | km h-1 | | +| | | | | | +| | | | mi h-1 | | +| | | | | | +| | | | kt | | +| | | | | | +| | | | ft s-1 | | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| uvmet10_wdir | uvmet10_wspd_wdir | 10m Wind Direction (wind_from_direction) | m s-1 | **units** (str) : Set to desired units. Default is *'m s-1'*. | +| | | | | | +| | | Rotated to Earth Coordinates | km h-1 | | +| | | | | | +| | | | mi h-1 | | +| | | | | | +| | | | kt | | +| | | | | | +| | | | ft s-1 | | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| wspd | wspd_wdir | Wind Speed | m s-1 | **units** (str) : Set to desired units. Default is *'m s-1'*. | +| | | | | | +| | | in Grid Coordinates | km h-1 | | +| | | | | | +| | | | mi h-1 | | +| | | | | | +| | | | kt | | +| | | | | | +| | | | ft s-1 | | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| wdir | wspd_wdir | Wind Direction (wind_from_direction) | m s-1 | **units** (str) : Set to desired units. Default is *'m s-1'*. | +| | | | | | +| | | in Grid Coordinates | km h-1 | | +| | | | | | +| | | | mi h-1 | | +| | | | | | +| | | | kt | | +| | | | | | +| | | | ft s-1 | | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| wspd10 | wspd_wdir10 | 10m Wind Speed | m s-1 | **units** (str) : Set to desired units. Default is *'m s-1'*. | +| | | | | | +| | | in Grid Coordinates | km h-1 | | +| | | | | | +| | | | mi h-1 | | +| | | | | | +| | | | kt | | +| | | | | | +| | | | ft s-1 | | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ +| wdir10 | wspd_wdir10 | 10m Wind Direction (wind_from_direction) | m s-1 | **units** (str) : Set to desired units. Default is *'m s-1'*. | +| | | | | | +| | | in Grid Coordinates | km h-1 | | +| | | | | | +| | | | mi h-1 | | +| | | | | | +| | | | kt | | +| | | | | | +| | | | ft s-1 | | ++--------------------+----------------------+---------------------------------------------------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ \ No newline at end of file diff --git a/doc/source/diagnostics.rst b/doc/source/diagnostics.rst index 88e364b..c706ee6 100644 --- a/doc/source/diagnostics.rst +++ b/doc/source/diagnostics.rst @@ -5,3 +5,17 @@ Table of Available Diagnostics .. include:: _templates/product_table.txt + +.. _subdiagnostic-table: + +Table of Subproduct Diagnostics +---------------------------------- + +Some diagnostics (e.g. cape_2d) include multiple products in its +output. These products have been broken out in to individual diagnostics +to help those utilities that are unable to work with multiple outputs. +These individual diagnostics can be requested like any other diagnostic +using :meth:`wrf.getvar`. These are summarized in the table below. + + +.. include:: _templates/subproducts.txt diff --git a/doc/source/internal_api/index.rst b/doc/source/internal_api/index.rst index a41775b..cfd3c7c 100644 --- a/doc/source/internal_api/index.rst +++ b/doc/source/internal_api/index.rst @@ -53,6 +53,23 @@ The routines below are called internally by :meth:`wrf.getvar`. wrf.g_wind.get_w_destag wrf.g_wind.get_destag_wspd_wdir wrf.g_wind.get_destag_wspd_wdir10 + wrf.g_wind.get_destag_wspd + wrf.g_wind.get_destag_wdir + wrf.g_wind.get_destag_wspd10 + wrf.g_wind.get_destag_wdir10 + wrf.g_uvmet.get_uvmet_wspd + wrf.g_uvmet.get_uvmet_wdir + wrf.g_uvmet.get_uvmet10_wspd + wrf.g_uvmet.get_uvmet10_wdir + wrf.g_cloudfrac.get_low_cloudfrac + wrf.g_cloudfrac.get_mid_cloudfrac + wrf.g_cloudfrac.get_high_cloudfrac + wrf.g_cape.get_cape2d_only + wrf.g_cape.get_cin2d_only + wrf.g_cape.get_lcl + wrf.g_cape.get_lfc + wrf.g_cape.get_3dcape_only + wrf.g_cape.get_3dcin_only ------------------------- diff --git a/doc/source/new.rst b/doc/source/new.rst index 7e2d87f..2bc87d0 100644 --- a/doc/source/new.rst +++ b/doc/source/new.rst @@ -4,8 +4,52 @@ What's New Releases ------------- -v1.2.0 -^^^^^^^^^^^^^^ +v1.3.0 (December 2018) +^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Release 1.3.0 +- Fixed FutureWarning issue with destag routine (thank you honnorat!) +- Fixed computational problems with updraft_helicity, and values are no longer + scaled by 1000. +- Removed version constraints for wrapt and setuptools. +- Fixed xarray being a hard dependency. +- Fixed unit issues with vinterp when pressure values are extracted below + ground. Also added support for height fields in km and pressure fields in + hPa. The documentation has been improved. +- Fixed the smooth2d routine so that it actually works. It never worked + correctly before (nor did it work in NCL). Users can now specify the + center weight of the kernel and the documentation has been updated to + describe how it works. +- Fixed the storm relative helicity algorithm so that it works in the southern + hemisphere. The raw algorithm now requires latitude input if used + in the southern hemisphere, otherwise the northern hemisphere is assumed. +- Fixed an issue with the latest version of cartopy 0.17 (thanks honnorat!) +- Fixed an issue where invalid keyword arguments weren't throwing errors when + extracting standard WRF variables. +- Fixed minor issues related to moving nests when using line interpolation and + vertical cross sections. It is still an error to request all times when + using lat/lon coordinates with a moving nest, but otherwise knows how to + run when all times are requested. This never really worked quite right. +- Removed the pyf file from setup.py since it is generated via the build + system. +- Added an autolevels parameter for the vertical cross section so that users + can specify the number of vertical levels to use if they don't want to + specify them manually. +- The interplevel routine has been improved. Users can now specify a single + level, multiple levels, or a 2D array (e.g. PBLH) to interpolate to. + Performance has been improved when interpolating a multiple product + field like wspd_wdir. +- Products that produce multiple outputs can now have the outputs requested + individually. See :ref:`subdiagnostic-table` for a list of what is available. +- Much of this version of wrf-python has been back ported to NCL in the + upcoming 6.6.0 release. The diagnostics should produce the same results + in both packages. +- Now released under the Apache 2.0 license. + + + +v1.2.0 (May 2018) +^^^^^^^^^^^^^^^^^^^^^^^^^ - Release 1.2.0 - Previous versions of wrf-python promoted the strings used in xarray (e.g. @@ -17,8 +61,8 @@ v1.2.0 errors, so we've decided to bump the major version number. -v1.1.3 -^^^^^^^^^^^^^^ +v1.1.3 (March 2018) +^^^^^^^^^^^^^^^^^^^^^^^^^ - Release 1.1.3 - Fixed/Enhanced the cloud top temperature diagnostic. @@ -39,15 +83,15 @@ v1.1.3 cape_3d. -v1.1.2 -^^^^^^^^^^^^^^ +v1.1.2 (February 2018) +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Release 1.1.2 - Fix OpenMP directive issue with cloud top temperature. -v1.1.1 -^^^^^^^^^^^^^^ +v1.1.1 (February 2018) +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Release 1.1.1 - Added script for building on Cheyenne with maxed out Intel settings, which @@ -59,8 +103,8 @@ v1.1.1 - Fix cape_2d private variable bug when running with multiple CPUs. -v1.1.0 -^^^^^^^^^^^^^^ +v1.1.0 (January 2018) +^^^^^^^^^^^^^^^^^^^^^^^^^ - Release 1.1.0 - Computational routines now support multiple cores using OpenMP. See @@ -107,15 +151,15 @@ v1.1.0 services like AppVeyor. -v1.0.5 -^^^^^^^^^^^^^^ +v1.0.5 (September 2017) +^^^^^^^^^^^^^^^^^^^^^^^^^^ - Release 1.0.5 - Reduced the CI test file sizes by half. -v1.0.4 -^^^^^^^^^^^^^^ +v1.0.4 (September 2017) +^^^^^^^^^^^^^^^^^^^^^^^^ - Release 1.0.4 - Fix warnings with CI tests which were caused by fill values being written @@ -123,23 +167,25 @@ v1.0.4 - Added the __eq__ operator to the WrfProj projection base class. - Fixed array order issue when using the raw CAPE routine with 1D arrays. -v1.0.3 -^^^^^^^^^^^^^^ + +v1.0.3 (June 2017) +^^^^^^^^^^^^^^^^^^^^^ - Relase 1.0.3 - Fixed an issue with the cartopy Mercator subclass where the xlimits were being calculated to the same value (or very close), causing blank plots. -v1.0.2 -^^^^^^^^^^^^^^ + +v1.0.2 (May 2017) +^^^^^^^^^^^^^^^^^^^^^ - Release 1.0.2 - Fixed issue with the wspd_wdir product types when sequences of files are used. -v1.0.1 -^^^^^^^^^^^^^ +v1.0.1 (March 2017) +^^^^^^^^^^^^^^^^^^^^^ - Release 1.0.1 - Fixed issue with initialization of PolarStereographic and LatLon map @@ -149,8 +195,8 @@ v1.0.1 so wrf-python should as well. -v1.0.0 -^^^^^^^^^^^^^ +v1.0.0 (March 2017) +^^^^^^^^^^^^^^^^^^^^^ - Release 1.0.0. - Fixed issue with not being able to set the thread-local coordinate cache to @@ -163,80 +209,6 @@ v1.0.0 column of data. -Beta Releases --------------- - -v1.0b3 -^^^^^^^^^^^^^ - -- Beta release 3. -- Improvements made for conda-forge integration testing. -- Fixed an incorrectly initialized variable issue with vinterp. This issue - mainly impacts the unit tests for continuous integration testing with - conda-forge, since the data set used for these tests is heavily cropped. -- Back-ported the inspect.BoundArguments.apply_defaults so that Python 3.4 - works. Windows users that want to try out wrf-python with Python 3.4 - can use the bladwig conda channel to get it. - -v1.0b2 -^^^^^^^^^^^^^^ - -- Beta release 2. -- xarray 0.9 no longer includes default index dimensions in the coordinate - mappings. This was causing a crash in the routines that cause a reduction - in dimension shape, mainly the interpolation routines. This has been - fixed. -- Documentation updated to show the new output from xarray. - -v1.0b1 -^^^^^^^^^^^^^ - -- Beta release 1. -- Added more packaging boilerplate. -- Note: Currently unable to build with Python 3.5 on Windows, due to - issues with distutils, numpy distutils, and mingw compiler. Will attempt - to find a workaround before the next release. Windows users should use - Python 2.7 or Python 3.4 for now. - - ----------------- - -Alpha Releases ----------------- - -v1.0a3 -^^^^^^^^^^^^ - -- Alpha release 3. -- Added docstrings. -- The mapping API has changed. - - The projection attributes are no longer arrays for moving domains. - - Utility functions have been added for extracting geobounds. It is now - easier to get map projection objects from sliced variables. - - Utility functions have been added for getting cartopy, basemap, and pyngl - objects. - - Users should no longer need to use xarray attributes directly -- Now uses CoordPair for cross sections so that lat/lon can be used instead of - raw x,y grid coordinates. -- Renamed npvalues to to_np which is more intuitive. -- Fixed issue with generator expressions. -- Renamed some functions and arguments. - - -------------- - - -Known Issues --------------- - -v1.0.0 -^^^^^^^^ - -- Currently unable to build on Windows with Python 3.5+ using open source - mingw compiler. The mingwpy project is working on resolving the - incompatibilities between mingw and Visual Studio 2015 that was used to - build Python 3.5+. Numpy 1.13 also has improved f2py support for - Python 3.5+ on Windows, so this will be revisited when it is released. diff --git a/doc/source/plot.rst b/doc/source/plot.rst index 13f229d..139d763 100644 --- a/doc/source/plot.rst +++ b/doc/source/plot.rst @@ -10,11 +10,11 @@ for a future release. Matplotlib With Cartopy ------------------------- -Cartopy is becoming the main tool for base mapping with matplotlib, but you should -be aware of a few shortcomings when working with WRF data. +Cartopy is becoming the main tool for base mapping with matplotlib, but you +should be aware of a few shortcomings when working with WRF data. -- The builtin transformations of coordinates when calling the contouring functions - do not work correctly with the rotated pole projection. The +- The builtin transformations of coordinates when calling the contouring + functions do not work correctly with the rotated pole projection. The transform_points method needs to be called manually on the latitude and longitude arrays. @@ -40,7 +40,8 @@ Plotting a Two-dimensional Field import cartopy.crs as crs from cartopy.feature import NaturalEarthFeature - from wrf import to_np, getvar, smooth2d, get_cartopy, cartopy_xlim, cartopy_ylim, latlon_coords + from wrf import (to_np, getvar, smooth2d, get_cartopy, cartopy_xlim, + cartopy_ylim, latlon_coords) # Open the NetCDF file ncfile = Dataset("wrfout_d01_2016-10-07_00_00_00") @@ -48,8 +49,9 @@ Plotting a Two-dimensional Field # Get the sea level pressure slp = getvar(ncfile, "slp") - # Smooth the sea level pressure since it tends to be noisy near the mountains - smooth_slp = smooth2d(slp, 3) + # Smooth the sea level pressure since it tends to be noisy near the + # mountains + smooth_slp = smooth2d(slp, 3, cenweight=4) # Get the latitude and longitude points lats, lons = latlon_coords(slp) @@ -58,26 +60,29 @@ Plotting a Two-dimensional Field cart_proj = get_cartopy(slp) # Create a figure - fig = plt.figure(figsize=(12,9)) + fig = plt.figure(figsize=(12,6)) # Set the GeoAxes to the projection used by WRF ax = plt.axes(projection=cart_proj) # Download and add the states and coastlines - states = NaturalEarthFeature(category='cultural', scale='50m', facecolor='none', - name='admin_1_states_provinces_shp') - ax.add_feature(states, linewidth=.5) + states = NaturalEarthFeature(category="cultural", scale="50m", + facecolor="none", + name="admin_1_states_provinces_shp") + ax.add_feature(states, linewidth=.5, edgecolor="black") ax.coastlines('50m', linewidth=0.8) - # Make the contour outlines and filled contours for the smoothed sea level pressure. + # Make the contour outlines and filled contours for the smoothed sea level + # pressure. plt.contour(to_np(lons), to_np(lats), to_np(smooth_slp), 10, colors="black", transform=crs.PlateCarree()) - plt.contourf(to_np(lons), to_np(lats), to_np(smooth_slp), 10, transform=crs.PlateCarree(), + plt.contourf(to_np(lons), to_np(lats), to_np(smooth_slp), 10, + transform=crs.PlateCarree(), cmap=get_cmap("jet")) # Add a color bar - plt.colorbar(ax=ax, shrink=.62) + plt.colorbar(ax=ax, shrink=.98) - # Set the map limits. Not really necessary, but used for demonstration. + # Set the map bounds ax.set_xlim(cartopy_xlim(smooth_slp)) ax.set_ylim(cartopy_ylim(smooth_slp)) @@ -105,7 +110,8 @@ Horizontal Interpolation to a Pressure Level import cartopy.crs as crs from cartopy.feature import NaturalEarthFeature - from wrf import getvar, interplevel, to_np, latlon_coords, get_cartopy, cartopy_xlim, cartopy_ylim + from wrf import (getvar, interplevel, to_np, latlon_coords, get_cartopy, + cartopy_xlim, cartopy_ylim) # Open the NetCDF file ncfile = Dataset("wrfout_d01_2016-10-07_00_00_00") @@ -134,27 +140,31 @@ Horizontal Interpolation to a Pressure Level ax = plt.axes(projection=cart_proj) # Download and add the states and coastlines - states = NaturalEarthFeature(category='cultural', scale='50m', facecolor='none', - name='admin_1_states_provinces_shp') - ax.add_feature(states, linewidth=0.5) + states = NaturalEarthFeature(category="cultural", scale="50m", + facecolor="none", + name="admin_1_states_provinces_shp") + ax.add_feature(states, linewidth=0.5, edgecolor="black") ax.coastlines('50m', linewidth=0.8) # Add the 500 hPa geopotential height contours levels = np.arange(520., 580., 6.) - contours = plt.contour(to_np(lons), to_np(lats), to_np(ht_500), levels=levels, colors="black", + contours = plt.contour(to_np(lons), to_np(lats), to_np(ht_500), + levels=levels, colors="black", transform=crs.PlateCarree()) plt.clabel(contours, inline=1, fontsize=10, fmt="%i") # Add the wind speed contours levels = [25, 30, 35, 40, 50, 60, 70, 80, 90, 100, 110, 120] - wspd_contours = plt.contourf(to_np(lons), to_np(lats), to_np(wspd_500), levels=levels, + wspd_contours = plt.contourf(to_np(lons), to_np(lats), to_np(wspd_500), + levels=levels, cmap=get_cmap("rainbow"), transform=crs.PlateCarree()) plt.colorbar(wspd_contours, ax=ax, orientation="horizontal", pad=.05) # Add the 500 hPa wind barbs, only plotting every 125th data point. - plt.barbs(to_np(lons[::125,::125]), to_np(lats[::125,::125]), to_np(u_500[::125, ::125]), - to_np(v_500[::125, ::125]), transform=crs.PlateCarree(), length=6) + plt.barbs(to_np(lons[::125,::125]), to_np(lats[::125,::125]), + to_np(u_500[::125, ::125]), to_np(v_500[::125, ::125]), + transform=crs.PlateCarree(), length=6) # Set the map bounds ax.set_xlim(cartopy_xlim(ht_500)) @@ -187,8 +197,8 @@ plot, see :ref:`cross_example`. import cartopy.feature as cfeature from netCDF4 import Dataset - from wrf import (getvar, to_np, vertcross, smooth2d, CoordPair, GeoBounds, get_cartopy, - latlon_coords, cartopy_xlim, cartopy_ylim) + from wrf import (getvar, to_np, vertcross, smooth2d, CoordPair, GeoBounds, + get_cartopy, latlon_coords, cartopy_xlim, cartopy_ylim) # Open the NetCDF file ncfile = Dataset("wrfout_d01_2016-10-07_00_00_00") @@ -206,12 +216,13 @@ plot, see :ref:`cross_example`. start_point = CoordPair(lat=26.76, lon=-80.0) end_point = CoordPair(lat=26.76, lon=-77.8) - # Compute the vertical cross-section interpolation. Also, include the lat/lon - # points along the cross-section in the metadata by setting latlon to True. - z_cross = vertcross(Z, z, wrfin=ncfile, start_point=start_point, end_point=end_point, - latlon=True, meta=True) - wspd_cross = vertcross(wspd, z, wrfin=ncfile, start_point=start_point, end_point=end_point, - latlon=True, meta=True) + # Compute the vertical cross-section interpolation. Also, include the + # lat/lon points along the cross-section in the metadata by setting latlon + # to True. + z_cross = vertcross(Z, z, wrfin=ncfile, start_point=start_point, + end_point=end_point, latlon=True, meta=True) + wspd_cross = vertcross(wspd, z, wrfin=ncfile, start_point=start_point, + end_point=end_point, latlon=True, meta=True) dbz_cross = 10.0 * np.log10(z_cross) # Get the lat/lon points @@ -221,31 +232,37 @@ plot, see :ref:`cross_example`. cart_proj = get_cartopy(slp) # Create a figure that will have 3 subplots - fig = plt.figure(figsize=(10,7)) + fig = plt.figure(figsize=(12,9)) ax_ctt = fig.add_subplot(1,2,1,projection=cart_proj) ax_wspd = fig.add_subplot(2,2,2) ax_dbz = fig.add_subplot(2,2,4) # Download and create the states, land, and oceans using cartopy features - states = cfeature.NaturalEarthFeature(category='cultural', scale='50m', facecolor='none', + states = cfeature.NaturalEarthFeature(category='cultural', scale='50m', + facecolor='none', name='admin_1_states_provinces_shp') - land = cfeature.NaturalEarthFeature(category='physical', name='land', scale='50m', + land = cfeature.NaturalEarthFeature(category='physical', name='land', + scale='50m', facecolor=cfeature.COLORS['land']) - ocean = cfeature.NaturalEarthFeature(category='physical', name='ocean', scale='50m', + ocean = cfeature.NaturalEarthFeature(category='physical', name='ocean', + scale='50m', facecolor=cfeature.COLORS['water']) # Make the pressure contours contour_levels = [960, 965, 970, 975, 980, 990] - c1 = ax_ctt.contour(lons, lats, to_np(smooth_slp), levels=contour_levels, colors="white", - transform=crs.PlateCarree(), zorder=3, linewidths=1.0) + c1 = ax_ctt.contour(lons, lats, to_np(smooth_slp), levels=contour_levels, + colors="white", transform=crs.PlateCarree(), zorder=3, + linewidths=1.0) # Create the filled cloud top temperature contours contour_levels = [-80.0, -70.0, -60, -50, -40, -30, -20, -10, 0, 10] - ctt_contours = ax_ctt.contourf(to_np(lons), to_np(lats), to_np(ctt), contour_levels, - cmap=get_cmap("Greys"), transform=crs.PlateCarree(), zorder=2) + ctt_contours = ax_ctt.contourf(to_np(lons), to_np(lats), to_np(ctt), + contour_levels, cmap=get_cmap("Greys"), + transform=crs.PlateCarree(), zorder=2) - ax_ctt.plot([start_point.lon, end_point.lon], [start_point.lat, end_point.lat], - color="yellow", marker="o", transform=crs.PlateCarree(), zorder=3) + ax_ctt.plot([start_point.lon, end_point.lon], + [start_point.lat, end_point.lat], color="yellow", marker="o", + transform=crs.PlateCarree(), zorder=3) # Create the color bar for cloud top temperature cb_ctt = fig.colorbar(ctt_contours, ax=ax_ctt, shrink=.60) @@ -271,7 +288,8 @@ plot, see :ref:`cross_example`. # Make the contour plot for dbz levels = [5 + 5*n for n in range(15)] - dbz_contours = ax_dbz.contourf(to_np(dbz_cross), levels=levels, cmap=get_cmap("jet")) + dbz_contours = ax_dbz.contourf(to_np(dbz_cross), levels=levels, + cmap=get_cmap("jet")) cb_dbz = fig.colorbar(dbz_contours, ax=ax_dbz) cb_dbz.ax.tick_params(labelsize=5) @@ -308,9 +326,9 @@ plot, see :ref:`cross_example`. Matplotlib with Basemap ----------------------- -Although basemap is in maintenance mode only and becoming deprecated, it is still -widely used by many programmers. Cartopy is becoming the preferred package for -mapping, however it suffers from growing pains in some areas +Although basemap is in maintenance mode only and becoming deprecated, it is +still widely used by many programmers. Cartopy is becoming the preferred +package for mapping, however it suffers from growing pains in some areas (can't use latitude/longitude labels for many map projections). If you run in to these issues, basemap is likely to accomplish what you need. @@ -337,8 +355,9 @@ Plotting a Two-Dimensional Field # Get the sea level pressure slp = getvar(ncfile, "slp") - # Smooth the sea level pressure since it tends to be noisy near the mountains - smooth_slp = smooth2d(slp, 3) + # Smooth the sea level pressure since it tends to be noisy near the + # mountains + smooth_slp = smooth2d(slp, 3, cenweight=4) # Get the latitude and longitude points lats, lons = latlon_coords(slp) @@ -354,8 +373,9 @@ Plotting a Two-Dimensional Field bm.drawstates(linewidth=0.25) bm.drawcountries(linewidth=0.25) - # Convert the lats and lons to x and y. Make sure you convert the lats and lons to - # numpy arrays via to_np, or basemap crashes with an undefined RuntimeError. + # Convert the lats and lons to x and y. Make sure you convert the lats and + # lons to numpy arrays via to_np, or basemap crashes with an undefined + # RuntimeError. x, y = bm(to_np(lons), to_np(lats)) # Draw the contours and filled contours @@ -458,7 +478,8 @@ plot, see :ref:`cross_example`. from matplotlib.cm import get_cmap from netCDF4 import Dataset - from wrf import getvar, to_np, vertcross, smooth2d, CoordPair, get_basemap, latlon_coords + from wrf import (getvar, to_np, vertcross, smooth2d, CoordPair, + get_basemap, latlon_coords) # Open the NetCDF file ncfile = Dataset("wrfout_d01_2016-10-07_00_00_00") @@ -476,19 +497,20 @@ plot, see :ref:`cross_example`. start_point = CoordPair(lat=26.76, lon=-80.0) end_point = CoordPair(lat=26.76, lon=-77.8) - # Compute the vertical cross-section interpolation. Also, include the lat/lon points - # along the cross-section in the metadata by setting latlon to True. - z_cross = vertcross(Z, z, wrfin=ncfile, start_point=start_point, end_point=end_point, - latlon=True, meta=True) - wspd_cross = vertcross(wspd, z, wrfin=ncfile, start_point=start_point, end_point=end_point, - latlon=True, meta=True) + # Compute the vertical cross-section interpolation. Also, include the + # lat/lon points along the cross-section in the metadata by setting latlon + # to True. + z_cross = vertcross(Z, z, wrfin=ncfile, start_point=start_point, + end_point=end_point, latlon=True, meta=True) + wspd_cross = vertcross(wspd, z, wrfin=ncfile, start_point=start_point, + end_point=end_point, latlon=True, meta=True) dbz_cross = 10.0 * np.log10(z_cross) # Get the latitude and longitude points lats, lons = latlon_coords(slp) # Create the figure that will have 3 subplots - fig = plt.figure(figsize=(10,7)) + fig = plt.figure(figsize=(12,9)) ax_ctt = fig.add_subplot(1,2,1) ax_wspd = fig.add_subplot(2,2,2) ax_dbz = fig.add_subplot(2,2,4) @@ -501,15 +523,16 @@ plot, see :ref:`cross_example`. # Make the pressure contours contour_levels = [960, 965, 970, 975, 980, 990] - c1 = bm.contour(x, y, to_np(smooth_slp), levels=contour_levels, colors="white", - zorder=3, linewidths=1.0, ax=ax_ctt) + c1 = bm.contour(x, y, to_np(smooth_slp), levels=contour_levels, + colors="white", zorder=3, linewidths=1.0, ax=ax_ctt) # Create the filled cloud top temperature contours contour_levels = [-80.0, -70.0, -60, -50, -40, -30, -20, -10, 0, 10] - ctt_contours = bm.contourf(x, y, to_np(ctt), contour_levels, cmap=get_cmap("Greys"), - zorder=2, ax=ax_ctt) + ctt_contours = bm.contourf(x, y, to_np(ctt), contour_levels, + cmap=get_cmap("Greys"), zorder=2, ax=ax_ctt) - point_x, point_y = bm([start_point.lon, end_point.lon], [start_point.lat, end_point.lat]) + point_x, point_y = bm([start_point.lon, end_point.lon], + [start_point.lat, end_point.lat]) bm.plot([point_x[0], point_x[1]], [point_y[0], point_y[1]], color="yellow", marker="o", zorder=3, ax=ax_ctt) @@ -522,8 +545,12 @@ plot, see :ref:`cross_example`. bm.drawstates(linewidth=0.25, ax=ax_ctt) bm.drawcountries(linewidth=0.25, ax=ax_ctt) bm.fillcontinents(color=np.array([ 0.9375 , 0.9375 , 0.859375]), - ax=ax_ctt, lake_color=np.array([ 0.59375 , 0.71484375, 0.8828125 ])) - bm.drawmapboundary(fill_color=np.array([ 0.59375 , 0.71484375, 0.8828125 ]), ax=ax_ctt) + ax=ax_ctt, + lake_color=np.array([0.59375 , + 0.71484375, + 0.8828125 ])) + bm.drawmapboundary(fill_color=np.array([ 0.59375 , 0.71484375, 0.8828125 ]), + ax=ax_ctt) # Draw Parallels parallels = np.arange(np.amin(lats), 30., 2.5) @@ -547,7 +574,8 @@ plot, see :ref:`cross_example`. # Make the contour plot for dbz levels = [5 + 5*n for n in range(15)] - dbz_contours = ax_dbz.contourf(to_np(dbz_cross), levels=levels, cmap=get_cmap("jet")) + dbz_contours = ax_dbz.contourf(to_np(dbz_cross), levels=levels, + cmap=get_cmap("jet")) cb_dbz = fig.colorbar(dbz_contours, ax=ax_dbz) cb_dbz.ax.tick_params(labelsize=5) @@ -583,6 +611,7 @@ plot, see :ref:`cross_example`. .. _cross_example: + Vertical Cross Section ------------------------------- @@ -616,10 +645,10 @@ plotted using the standard matplotlib API. start_point = CoordPair(lat=26.76, lon=-80.0) end_point = CoordPair(lat=26.76, lon=-77.8) - # Compute the vertical cross-section interpolation. Also, include the lat/lon - # points along the cross-section. - wspd_cross = vertcross(wspd, z, wrfin=ncfile, start_point=start_point, end_point=end_point, - latlon=True, meta=True) + # Compute the vertical cross-section interpolation. Also, include the + # lat/lon points along the cross-section. + wspd_cross = vertcross(wspd, z, wrfin=ncfile, start_point=start_point, + end_point=end_point, latlon=True, meta=True) # Create the figure fig = plt.figure(figsize=(12,6)) @@ -634,7 +663,8 @@ plotted using the standard matplotlib API. # Set the x-ticks to use latitude and longitude labels. coord_pairs = to_np(wspd_cross.coords["xy_loc"]) x_ticks = np.arange(coord_pairs.shape[0]) - x_labels = [pair.latlon_str(fmt="{:.2f}, {:.2f}") for pair in to_np(coord_pairs)] + x_labels = [pair.latlon_str(fmt="{:.2f}, {:.2f}") + for pair in to_np(coord_pairs)] ax.set_xticks(x_ticks[::20]) ax.set_xticklabels(x_labels[::20], rotation=45, fontsize=8) @@ -651,4 +681,142 @@ plotted using the standard matplotlib API. plt.title("Vertical Cross Section of Wind Speed (kt)") plt.show() + + +Cross Section with Mountains +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The example below shows how to make a cross section with the mountainous +terrain filled. + +.. image:: _static/images/cross_mtns.png + :scale: 100% + :align: center + +.. code-block:: python + + import numpy as np + from matplotlib import pyplot + from matplotlib.cm import get_cmap + from matplotlib.colors import from_levels_and_colors + from cartopy import crs + from cartopy.feature import NaturalEarthFeature, COLORS + from netCDF4 import Dataset + from wrf import (getvar, to_np, get_cartopy, latlon_coords, vertcross, + cartopy_xlim, cartopy_ylim, interpline, CoordPair) + + wrf_file = Dataset("wrfout_d01_2010-06-04_00:00:00") + + # Define the cross section start and end points + cross_start = CoordPair(lat=43.5, lon=-116.5) + cross_end = CoordPair(lat=43.5, lon=-114) + + # Get the WRF variables + ht = getvar(wrf_file, "z", timeidx=-1) + ter = getvar(wrf_file, "ter", timeidx=-1) + dbz = getvar(wrf_file, "dbz", timeidx=-1) + max_dbz = getvar(wrf_file, "mdbz", timeidx=-1) + Z = 10**(dbz/10.) # Use linear Z for interpolation + + # Compute the vertical cross-section interpolation. Also, include the + # lat/lon points along the cross-section in the metadata by setting latlon + # to True. + z_cross = vertcross(Z, ht, wrfin=wrf_file, + start_point=cross_start, + end_point=cross_end, + latlon=True, meta=True) + + # Convert back to dBz after interpolation + dbz_cross = 10.0 * np.log10(z_cross) + + # Add back the attributes that xarray dropped from the operations above + dbz_cross.attrs.update(z_cross.attrs) + dbz_cross.attrs["description"] = "radar reflectivity cross section" + dbz_cross.attrs["units"] = "dBZ" + + # To remove the slight gap between the dbz contours and terrain due to the + # contouring of gridded data, a new vertical grid spacing, and model grid + # staggering, fill in the lower grid cells with the first non-missing value + # for each column. + + # Make a copy of the z cross data. Let's use regular numpy arrays for this. + dbz_cross_filled = np.ma.copy(to_np(dbz_cross)) + + # For each cross section column, find the first index with non-missing + # values and copy these to the missing elements below. + for i in range(dbz_cross_filled.shape[-1]): + column_vals = dbz_cross_filled[:,i] + # Let's find the lowest index that isn't filled. The nonzero function + # finds all unmasked values greater than 0. Since 0 is a valid value + # for dBZ, let's change that threshold to be -200 dBZ instead. + first_idx = int(np.transpose((column_vals > -200).nonzero())[0]) + dbz_cross_filled[0:first_idx, i] = dbz_cross_filled[first_idx, i] + + # Get the terrain heights along the cross section line + ter_line = interpline(ter, wrfin=wrf_file, start_point=cross_start, + end_point=cross_end) + + # Get the lat/lon points + lats, lons = latlon_coords(dbz) + + # Get the cartopy projection object + cart_proj = get_cartopy(dbz) + + # Create the figure + fig = pyplot.figure(figsize=(8,6)) + ax_cross = pyplot.axes() + + dbz_levels = np.arange(5., 80., 5.) + + # Create the color table found on NWS pages. + dbz_rgb = np.array([[4,233,231], + [1,159,244], [3,0,244], + [2,253,2], [1,197,1], + [0,142,0], [253,248,2], + [229,188,0], [253,149,0], + [253,0,0], [212,0,0], + [188,0,0],[248,0,253], + [152,84,198]], np.float32) / 255.0 + + dbz_map, dbz_norm = from_levels_and_colors(dbz_levels, dbz_rgb, + extend="max") + + # Make the cross section plot for dbz + dbz_levels = np.arange(5.,75.,5.) + xs = np.arange(0, dbz_cross.shape[-1], 1) + ys = to_np(dbz_cross.coords["vertical"]) + dbz_contours = ax_cross.contourf(xs, + ys, + to_np(dbz_cross_filled), + levels=dbz_levels, + cmap=dbz_map, + norm=dbz_norm, + extend="max") + # Add the color bar + cb_dbz = fig.colorbar(dbz_contours, ax=ax_cross) + cb_dbz.ax.tick_params(labelsize=8) + + # Fill in the mountain area + ht_fill = ax_cross.fill_between(xs, 0, to_np(ter_line), + facecolor="saddlebrown") + + # Set the x-ticks to use latitude and longitude labels + coord_pairs = to_np(dbz_cross.coords["xy_loc"]) + x_ticks = np.arange(coord_pairs.shape[0]) + x_labels = [pair.latlon_str() for pair in to_np(coord_pairs)] + + # Set the desired number of x ticks below + num_ticks = 5 + thin = int((len(x_ticks) / num_ticks) + .5) + ax_cross.set_xticks(x_ticks[::thin]) + ax_cross.set_xticklabels(x_labels[::thin], rotation=45, fontsize=8) + + # Set the x-axis and y-axis labels + ax_cross.set_xlabel("Latitude, Longitude", fontsize=12) + ax_cross.set_ylabel("Height (m)", fontsize=12) + + # Add a title + ax_cross.set_title("Cross-Section of Reflectivity (dBZ)", {"fontsize" : 14}) + + pyplot.show() diff --git a/src/wrf/computation.py b/src/wrf/computation.py index 8abadaf..f75ae87 100644 --- a/src/wrf/computation.py +++ b/src/wrf/computation.py @@ -701,7 +701,7 @@ def smooth2d(field, passes, cenweight=2.0, meta=True): 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 + :class:`numpy.ma.MaskedArray` or a :class:`xarray.DataArray` with a *_FillValue* attribute. passes (:obj:`int`): The number of smoothing passes. diff --git a/src/wrf/g_cape.py b/src/wrf/g_cape.py index 062d28f..d2ce0e7 100755 --- a/src/wrf/g_cape.py +++ b/src/wrf/g_cape.py @@ -12,7 +12,7 @@ from .metadecorators import set_cape_metadata @set_cape_metadata(is2d=True) def get_2dcape(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, meta=True, _key=None, missing=default_fill(np.float64)): - """Return the 2d fields of MCAPE, MCIN, LCL, and LFC. + """Return the two-dimensional fields of MCAPE, MCIN, LCL, and LFC. The leftmost dimension of the returned array represents four different quantities: @@ -227,6 +227,62 @@ def get_3dcape(wrfin, timeidx=0, method="cat", 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + purposes only. Default is None. + + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_2dcape(wrfin, timeidx, method, squeeze, cache, meta, _key, missing)[0,:] @@ -239,6 +295,61 @@ def get_cape2d_only(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + purposes only. Default is None. + + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_2dcape(wrfin, timeidx, method, squeeze, cache, meta, _key, missing)[1,:] @@ -251,6 +362,61 @@ def get_cin2d_only(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + purposes only. Default is None. + + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_2dcape(wrfin, timeidx, method, squeeze, cache, meta, _key, missing)[2,:] @@ -263,6 +429,61 @@ def get_lcl(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + purposes only. Default is None. + + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_2dcape(wrfin, timeidx, method, squeeze, cache, meta, _key, missing)[3,:] @@ -276,6 +497,62 @@ def get_lfc(wrfin, timeidx=0, method="cat", squeeze=True, cache=None, 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + purposes only. Default is None. + + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_3dcape(wrfin, timeidx, method, squeeze, cache, meta, _key, missing)[0,:] @@ -289,6 +566,61 @@ def get_3dcape_only(wrfin, timeidx=0, method="cat", 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + purposes only. Default is None. + + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_3dcape(wrfin, timeidx, method, squeeze, cache, meta, _key, missing)[1,:] diff --git a/src/wrf/g_cloudfrac.py b/src/wrf/g_cloudfrac.py index a0458f6..49af329 100644 --- a/src/wrf/g_cloudfrac.py +++ b/src/wrf/g_cloudfrac.py @@ -166,6 +166,103 @@ 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 + 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: + + 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 + (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 + happens, a fill value will be used in the output. + + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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', + '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. + + 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 + 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, @@ -181,6 +278,103 @@ 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 + 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: + + 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 + (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 + happens, a fill value will be used in the output. + + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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', + '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. + + 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 + 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, @@ -196,6 +390,103 @@ 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 + 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: + + 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 + (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 + happens, a fill value will be used in the output. + + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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', + '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. + + 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 + 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, diff --git a/src/wrf/g_uvmet.py b/src/wrf/g_uvmet.py index 9a058be..dc1d0e0 100755 --- a/src/wrf/g_uvmet.py +++ b/src/wrf/g_uvmet.py @@ -523,6 +523,65 @@ def get_uvmet10_wspd_wdir(wrfin, timeidx=0, method="cat", squeeze=True, 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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'. + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_uvmet_wspd_wdir(wrfin, timeidx, method, squeeze, cache, meta, _key, units)[0,:] @@ -535,6 +594,65 @@ def get_uvmet_wspd(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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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'. + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_uvmet_wspd_wdir(wrfin, timeidx, method, squeeze, cache, meta, _key, units)[1,:] @@ -547,6 +665,65 @@ def get_uvmet_wdir(wrfin, timeidx=0, method="cat", squeeze=True, 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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'. + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_uvmet10_wspd_wdir(wrfin, timeidx, method, squeeze, cache, meta, _key, units)[0,:] if meta: @@ -558,6 +735,65 @@ def get_uvmet10_wspd(wrfin, timeidx=0, method="cat", squeeze=True, 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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'. + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_uvmet10_wspd_wdir(wrfin, timeidx, method, squeeze, cache, meta, _key, units)[1,:] diff --git a/src/wrf/g_wind.py b/src/wrf/g_wind.py index f91ead8..9edaeea 100755 --- a/src/wrf/g_wind.py +++ b/src/wrf/g_wind.py @@ -332,7 +332,7 @@ 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 space. + 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, @@ -423,7 +423,7 @@ 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 - projected coordinate space. + 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, @@ -511,6 +511,63 @@ def get_destag_wspd_wdir10(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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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'. + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_destag_wspd_wdir(wrfin, timeidx, method, squeeze, cache, meta, _key, units)[0,:] @@ -518,10 +575,68 @@ def get_destag_wspd(wrfin, timeidx=0, method="cat", result.attrs["description"] = "wspd in projection space" return result + 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 + 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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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'. + 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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_destag_wspd_wdir(wrfin, timeidx, method, squeeze, cache, meta, _key, units)[1,:] @@ -534,6 +649,64 @@ def get_destag_wdir(wrfin, timeidx=0, method="cat", 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 + (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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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_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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_destag_wspd_wdir10(wrfin, timeidx, method, squeeze, cache, meta, _key, units)[0,:] @@ -546,6 +719,64 @@ def get_destag_wspd10(wrfin, timeidx=0, method="cat", 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 + (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` + 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 + 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. + 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 + 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. + Default is None. + + 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 + 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_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 + be a :class:`numpy.ndarray` object with no metadata. + + """ result = get_destag_wspd_wdir10(wrfin, timeidx, method, squeeze, cache, meta, _key, units)[1,:] diff --git a/src/wrf/version.py b/src/wrf/version.py index c1afe52..1794957 100644 --- a/src/wrf/version.py +++ b/src/wrf/version.py @@ -1,2 +1,2 @@ -__version__ = "1.2.0" +__version__ = "1.3.0" diff --git a/test/ipynb/Doc_Examples.ipynb b/test/ipynb/Doc_Examples.ipynb index 81ba5bd..3c9c02f 100644 --- a/test/ipynb/Doc_Examples.ipynb +++ b/test/ipynb/Doc_Examples.ipynb @@ -108,8 +108,6 @@ "metadata": {}, "outputs": [], "source": [ - "%matplotlib inline\n", - "\n", "from __future__ import (absolute_import, division, print_function, unicode_literals)\n", "\n", "import numpy as np\n", @@ -146,11 +144,11 @@ "levels = [5 + 5*n for n in range(15)]\n", "\n", "# Make the contour plot\n", - "a = axes[0].contourf(to_np(wspd_cross))\n", + "a = axes[0].contourf(to_np(wspd_cross), cmap=get_cmap(\"jet\"))\n", "# Add the color bar\n", "fig.colorbar(a, ax=axes[0])\n", "\n", - "b = axes[1].contourf(to_np(dbz_cross), levels=levels)\n", + "b = axes[1].contourf(to_np(dbz_cross), levels=levels, cmap=get_cmap(\"jet\"))\n", "fig.colorbar(b, ax=axes[1])\n", "\n", "# Set the x-ticks to use latitude and longitude labels.\n", @@ -185,6 +183,13 @@ "plt.show()" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Cartopy Panel Plot" + ] + }, { "cell_type": "code", "execution_count": null, @@ -193,8 +198,6 @@ }, "outputs": [], "source": [ - "%matplotlib inline\n", - "\n", "from __future__ import (absolute_import, division, print_function, unicode_literals)\n", "\n", "import numpy as np\n", @@ -236,7 +239,7 @@ "cart_proj = get_cartopy(slp)\n", "\n", "# Create a figure that will have 3 subplots\n", - "fig = plt.figure(figsize=(10,7))\n", + "fig = plt.figure(figsize=(12,9))\n", "ax_ctt = fig.add_subplot(1,2,1,projection=cart_proj)\n", "ax_wspd = fig.add_subplot(2,2,2)\n", "ax_dbz = fig.add_subplot(2,2,4)\n", @@ -282,13 +285,13 @@ "wspd_contours = ax_wspd.contourf(to_np(wspd_cross), cmap=get_cmap(\"jet\"))\n", "# Add the color bar\n", "cb_wspd = fig.colorbar(wspd_contours, ax=ax_wspd)\n", - "cb_wspd.ax.tick_params(labelsize=5)\n", + "cb_wspd.ax.tick_params(labelsize=6)\n", "\n", "# Make the contour plot for dbz\n", "levels = [5 + 5*n for n in range(15)]\n", "dbz_contours = ax_dbz.contourf(to_np(dbz_cross), levels=levels, cmap=get_cmap(\"jet\"))\n", "cb_dbz = fig.colorbar(dbz_contours, ax=ax_dbz)\n", - "cb_dbz.ax.tick_params(labelsize=5)\n", + "cb_dbz.ax.tick_params(labelsize=6)\n", "\n", "# Set the x-ticks to use latitude and longitude labels\n", "coord_pairs = to_np(dbz_cross.coords[\"xy_loc\"])\n", @@ -297,25 +300,25 @@ "ax_wspd.set_xticks(x_ticks[::20])\n", "ax_wspd.set_xticklabels([], rotation=45)\n", "ax_dbz.set_xticks(x_ticks[::20])\n", - "ax_dbz.set_xticklabels(x_labels[::20], rotation=45, fontsize=4) \n", + "ax_dbz.set_xticklabels(x_labels[::20], rotation=45, fontsize=6) \n", "\n", "# Set the y-ticks to be height\n", "vert_vals = to_np(dbz_cross.coords[\"vertical\"])\n", "v_ticks = np.arange(vert_vals.shape[0])\n", "ax_wspd.set_yticks(v_ticks[::20])\n", - "ax_wspd.set_yticklabels(vert_vals[::20], fontsize=4) \n", + "ax_wspd.set_yticklabels(vert_vals[::20], fontsize=6) \n", "ax_dbz.set_yticks(v_ticks[::20])\n", - "ax_dbz.set_yticklabels(vert_vals[::20], fontsize=4) \n", + "ax_dbz.set_yticklabels(vert_vals[::20], fontsize=6) \n", "\n", "# Set the x-axis and y-axis labels\n", - "ax_dbz.set_xlabel(\"Latitude, Longitude\", fontsize=5)\n", - "ax_wspd.set_ylabel(\"Height (m)\", fontsize=5)\n", - "ax_dbz.set_ylabel(\"Height (m)\", fontsize=5)\n", + "ax_dbz.set_xlabel(\"Latitude, Longitude\", fontsize=8)\n", + "ax_wspd.set_ylabel(\"Height (m)\", fontsize=8)\n", + "ax_dbz.set_ylabel(\"Height (m)\", fontsize=8)\n", "\n", "# Add a title\n", - "ax_ctt.set_title(\"Cloud Top Temperature (degC)\", {\"fontsize\" : 7})\n", - "ax_wspd.set_title(\"Cross-Section of Wind Speed (kt)\", {\"fontsize\" : 7})\n", - "ax_dbz.set_title(\"Cross-Section of Reflectivity (dBZ)\", {\"fontsize\" : 7})\n", + "ax_ctt.set_title(\"Cloud Top Temperature (degC)\", {\"fontsize\" : 10})\n", + "ax_wspd.set_title(\"Cross-Section of Wind Speed (kt)\", {\"fontsize\" : 10})\n", + "ax_dbz.set_title(\"Cross-Section of Reflectivity (dBZ)\", {\"fontsize\" : 10})\n", "\n", "plt.savefig(\"/Users/ladwig/Documents/workspace/wrf_python/doc/source/_static/images/matthew.png\",\n", " transparent=True, bbox_inches=\"tight\")\n", @@ -330,8 +333,6 @@ }, "outputs": [], "source": [ - "%matplotlib inline\n", - "# SLP\n", "from __future__ import (absolute_import, division, print_function, unicode_literals)\n", " \n", "from netCDF4 import Dataset \n", @@ -349,7 +350,7 @@ "slp = getvar(ncfile, \"slp\")\n", "\n", "# Smooth the sea level pressure since it tends to be noisy near the mountains\n", - "smooth_slp = smooth2d(slp, 3)\n", + "smooth_slp = smooth2d(slp, 3, cenweight=4)\n", "\n", "# Get the latitude and longitude points\n", "lats, lons = latlon_coords(slp)\n", @@ -358,22 +359,22 @@ "cart_proj = get_cartopy(slp)\n", "\n", "# Create a figure\n", - "fig = plt.figure(figsize=(12,9))\n", + "fig = plt.figure(figsize=(12,6.0))\n", "# Set the GeoAxes to the projection used by WRF\n", "ax = plt.axes(projection=cart_proj)\n", "\n", "# Download and add the states and coastlines\n", "states = NaturalEarthFeature(category='cultural', scale='50m', facecolor='none',\n", " name='admin_1_states_provinces_shp')\n", - "ax.add_feature(states, linewidth=.5)\n", - "ax.coastlines('50m', linewidth=0.8)\n", + "ax.add_feature(states, linewidth=.5, edgecolor=\"black\")\n", + "ax.coastlines('50m', linewidth=0.8, zorder=3)\n", "\n", "# Make the contour outlines and filled contours for the smoothed sea level pressure.\n", "plt.contour(to_np(lons), to_np(lats), to_np(smooth_slp), 10, colors=\"black\", transform=crs.PlateCarree())\n", "plt.contourf(to_np(lons), to_np(lats), to_np(smooth_slp), 10, transform=crs.PlateCarree(), cmap=get_cmap(\"jet\"))\n", "\n", "# Add a color bar\n", - "plt.colorbar(ax=ax, shrink=.62)\n", + "plt.colorbar(ax=ax, shrink=.98)\n", "\n", "# Set the map limits. Not really necessary, but used for demonstration.\n", "ax.set_xlim(cartopy_xlim(smooth_slp))\n", @@ -388,14 +389,19 @@ " transparent=True, bbox_inches=\"tight\")" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Vertical Cross Section" + ] + }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "%matplotlib inline\n", - "\n", "from __future__ import (absolute_import, division, print_function, unicode_literals)\n", "\n", "import numpy as np\n", @@ -457,6 +463,151 @@ "plt.show()" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Vertical Cross Section with Mountains" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "scrolled": false + }, + "outputs": [], + "source": [ + "import numpy as np\n", + "from matplotlib import pyplot\n", + "from matplotlib.cm import get_cmap\n", + "from matplotlib.colors import from_levels_and_colors\n", + "from cartopy import crs\n", + "from cartopy.feature import NaturalEarthFeature, COLORS\n", + "from netCDF4 import Dataset\n", + "from wrf import (getvar, to_np, get_cartopy, latlon_coords, vertcross,\n", + " cartopy_xlim, cartopy_ylim, interpline, CoordPair)\n", + "\n", + "wrf_file = Dataset(\"/Users/ladwig/Documents/wrf_files/boise_tutorial/orig/wrfout_d01_2010-06-04_00:00:00\")\n", + "\n", + "# Define the cross section start and end points\n", + "cross_start = CoordPair(lat=43.5, lon=-116.5)\n", + "cross_end = CoordPair(lat=43.5, lon=-114)\n", + "\n", + "# Get the WRF variables\n", + "ht = getvar(wrf_file, \"z\", timeidx=-1)\n", + "ter = getvar(wrf_file, \"ter\", timeidx=-1)\n", + "dbz = getvar(wrf_file, \"dbz\", timeidx=-1)\n", + "max_dbz = getvar(wrf_file, \"mdbz\", timeidx=-1)\n", + "Z = 10**(dbz/10.) # Use linear Z for interpolation\n", + "\n", + "# Compute the vertical cross-section interpolation. Also, include the lat/lon\n", + "# points along the cross-section in the metadata by setting latlon to True.\n", + "z_cross = vertcross(Z, ht, wrfin=wrf_file, \n", + " start_point=cross_start, \n", + " end_point=cross_end,\n", + " latlon=True, meta=True)\n", + "\n", + "# Convert back to dBz after interpolation\n", + "dbz_cross = 10.0 * np.log10(z_cross)\n", + "\n", + "# Add back the attributes that xarray dropped from the operations above\n", + "dbz_cross.attrs.update(z_cross.attrs)\n", + "dbz_cross.attrs[\"description\"] = \"radar reflectivity cross section\"\n", + "dbz_cross.attrs[\"units\"] = \"dBZ\"\n", + "\n", + "# To remove the slight gap between the dbz and terrain due to contouring, the new vertical \n", + "# grid spacing, and grid staggering, let's fill in the lower grid cells with the first non-missing \n", + "# value for each column.\n", + "\n", + "# Make a copy of the z cross data. Let's use regular numpy arrays for this.\n", + "dbz_cross_filled = np.ma.copy(to_np(dbz_cross))\n", + "\n", + "# For each cross section column, find the first index with non-missing values and copy\n", + "# these to the missing elements below.\n", + "for i in range(dbz_cross_filled.shape[-1]):\n", + " column_vals = dbz_cross_filled[:,i]\n", + " # Let's find the lowest index that isn't filled. The nonzero function \n", + " # finds all unmasked values greater than 0. Since 0 is a valid value\n", + " # for dBZ, let's change that threshold to be -200 dBZ instead. \n", + " first_idx = int(np.transpose((column_vals > -200).nonzero())[0])\n", + " dbz_cross_filled[0:first_idx, i] = dbz_cross_filled[first_idx, i]\n", + " \n", + "# Get the terrain heights along the cross section line\n", + "ter_line = interpline(ter, wrfin=wrf_file, start_point=cross_start, end_point=cross_end)\n", + "\n", + "# Get the lat/lon points\n", + "lats, lons = latlon_coords(dbz)\n", + "\n", + "# Get the cartopy projection object\n", + "cart_proj = get_cartopy(dbz)\n", + "\n", + "# Create a figure that will have 2 subplots (1 row, 2 columns)\n", + "fig = pyplot.figure(figsize=(12,9))\n", + "ax_cross = pyplot.axes()\n", + "\n", + "dbz_levels = np.arange(5., 75., 5.)\n", + "\n", + "# This is the NWS color table.\n", + "dbz_rgb = np.array([[4,233,231],\n", + " [1,159,244], [3,0,244],\n", + " [2,253,2], [1,197,1],\n", + " [0,142,0], [253,248,2],\n", + " [229,188,0], [253,149,0],\n", + " [253,0,0], [212,0,0],\n", + " [188,0,0],[248,0,253],\n", + " [152,84,198]], np.float32) / 255.0\n", + " \n", + "dbz_map, dbz_norm = from_levels_and_colors(dbz_levels, dbz_rgb, extend=\"max\")\n", + "\n", + "# Make the cross section plot for dbz\n", + "dbz_levels = np.arange(5.,75.,5.)\n", + "xs = np.arange(0, dbz_cross.shape[-1], 1)\n", + "ys = to_np(dbz_cross.coords[\"vertical\"])\n", + "dbz_contours = ax_cross.contourf(xs, \n", + " ys, \n", + " to_np(dbz_cross_filled), \n", + " levels=dbz_levels,\n", + " cmap=dbz_map, \n", + " norm=dbz_norm, \n", + " extend=\"max\")\n", + "cb_dbz = fig.colorbar(dbz_contours, ax=ax_cross)\n", + "cb_dbz.ax.tick_params(labelsize=8)\n", + "\n", + "# Fill in the mountain area\n", + "ht_fill = ax_cross.fill_between(xs, 0, to_np(ter_line), facecolor=\"saddlebrown\")\n", + "\n", + "# Set the x-ticks to use latitude and longitude labels\n", + "coord_pairs = to_np(dbz_cross.coords[\"xy_loc\"])\n", + "x_ticks = np.arange(coord_pairs.shape[0])\n", + "x_labels = [pair.latlon_str() for pair in to_np(coord_pairs)]\n", + "\n", + "# Set the desired number of x ticks below\n", + "num_ticks = 5\n", + "thin = int((len(x_ticks) / num_ticks) + .5)\n", + "ax_cross.set_xticks(x_ticks[::thin])\n", + "ax_cross.set_xticklabels(x_labels[::thin], rotation=45, fontsize=8)\n", + "\n", + "# Set the x-axis and y-axis labels\n", + "ax_cross.set_xlabel(\"Latitude, Longitude\", fontsize=12)\n", + "ax_cross.set_ylabel(\"Height (m)\", fontsize=12)\n", + "\n", + "# Add a title\n", + "ax_cross.set_title(\"Cross-Section of Reflectivity (dBZ)\", {\"fontsize\" : 14})\n", + "\n", + "plt.savefig(\"/Users/ladwig/Documents/workspace/wrf_python/doc/source/_static/images/cross_mtns.png\",\n", + " transparent=True, bbox_inches=\"tight\")\n", + "\n", + "pyplot.show()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Wind Barbs" + ] + }, { "cell_type": "code", "execution_count": null, @@ -503,7 +654,7 @@ "# Download and add the states and coastlines\n", "states = NaturalEarthFeature(category='cultural', scale='50m', facecolor='none',\n", " name='admin_1_states_provinces_shp')\n", - "ax.add_feature(states, linewidth=0.5)\n", + "ax.add_feature(states, linewidth=0.5, edgecolor=\"black\")\n", "ax.coastlines('50m', linewidth=0.8)\n", "\n", "# Add the 500 hPa geopotential height contours\n", @@ -623,7 +774,7 @@ "slp = getvar(ncfile, \"slp\")\n", "\n", "# Smooth the sea level pressure since it tends to be noisy near the mountains\n", - "smooth_slp = smooth2d(slp, 3)\n", + "smooth_slp = smooth2d(slp, 3, cenweight=4)\n", "\n", "# Get the latitude and longitude points\n", "lats, lons = latlon_coords(slp)\n", @@ -632,7 +783,7 @@ "bm = get_basemap(slp)\n", "\n", "# Create a figure\n", - "fig = plt.figure(figsize=(12,9))\n", + "fig = plt.figure(figsize=(12,6))\n", "\n", "# Add geographic outlines\n", "bm.drawcoastlines(linewidth=0.25)\n", @@ -648,7 +799,7 @@ "bm.contourf(x, y, to_np(smooth_slp), 10, cmap=get_cmap(\"jet\"))\n", "\n", "# Add a color bar\n", - "plt.colorbar(shrink=.62)\n", + "plt.colorbar(shrink=.98)\n", "\n", "plt.title(\"Sea Level Pressure (hPa)\")\n", "\n", @@ -664,7 +815,6 @@ "metadata": {}, "outputs": [], "source": [ - "%matplotlib inline\n", "from __future__ import (absolute_import, division, print_function, unicode_literals)\n", "\n", "from netCDF4 import Dataset \n", @@ -731,14 +881,19 @@ "plt.show()" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Basemap Panel Plot" + ] + }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "%matplotlib inline\n", - "\n", "import numpy as np\n", "import matplotlib.pyplot as plt\n", "from matplotlib.cm import get_cmap\n", @@ -772,7 +927,7 @@ "lats, lons = latlon_coords(slp)\n", "\n", "# Create the figure that will have 3 subplots\n", - "fig = plt.figure(figsize=(10,7))\n", + "fig = plt.figure(figsize=(12,9))\n", "ax_ctt = fig.add_subplot(1,2,1)\n", "ax_wspd = fig.add_subplot(2,2,2)\n", "ax_dbz = fig.add_subplot(2,2,4)\n", @@ -827,13 +982,13 @@ "wspd_contours = ax_wspd.contourf(to_np(wspd_cross), cmap=get_cmap(\"jet\"))\n", "# Add the color bar\n", "cb_wspd = fig.colorbar(wspd_contours, ax=ax_wspd)\n", - "cb_wspd.ax.tick_params(labelsize=5)\n", + "cb_wspd.ax.tick_params(labelsize=6)\n", "\n", "# Make the contour plot for dbz\n", "levels = [5 + 5*n for n in range(15)]\n", "dbz_contours = ax_dbz.contourf(to_np(dbz_cross), levels=levels, cmap=get_cmap(\"jet\"))\n", "cb_dbz = fig.colorbar(dbz_contours, ax=ax_dbz)\n", - "cb_dbz.ax.tick_params(labelsize=5)\n", + "cb_dbz.ax.tick_params(labelsize=6)\n", "\n", "# Set the x-ticks to use latitude and longitude labels.\n", "coord_pairs = to_np(dbz_cross.coords[\"xy_loc\"])\n", @@ -842,25 +997,25 @@ "ax_wspd.set_xticks(x_ticks[::20])\n", "ax_wspd.set_xticklabels([], rotation=45)\n", "ax_dbz.set_xticks(x_ticks[::20])\n", - "ax_dbz.set_xticklabels(x_labels[::20], rotation=45, fontsize=4) \n", + "ax_dbz.set_xticklabels(x_labels[::20], rotation=45, fontsize=6) \n", "\n", "# Set the y-ticks to be height.\n", "vert_vals = to_np(dbz_cross.coords[\"vertical\"])\n", "v_ticks = np.arange(vert_vals.shape[0])\n", "ax_wspd.set_yticks(v_ticks[::20])\n", - "ax_wspd.set_yticklabels(vert_vals[::20], fontsize=4) \n", + "ax_wspd.set_yticklabels(vert_vals[::20], fontsize=6) \n", "ax_dbz.set_yticks(v_ticks[::20])\n", - "ax_dbz.set_yticklabels(vert_vals[::20], fontsize=4) \n", + "ax_dbz.set_yticklabels(vert_vals[::20], fontsize=6) \n", "\n", "# Set the x-axis and y-axis labels\n", - "ax_dbz.set_xlabel(\"Latitude, Longitude\", fontsize=5)\n", - "ax_wspd.set_ylabel(\"Height (m)\", fontsize=5)\n", - "ax_dbz.set_ylabel(\"Height (m)\", fontsize=5)\n", + "ax_dbz.set_xlabel(\"Latitude, Longitude\", fontsize=8)\n", + "ax_wspd.set_ylabel(\"Height (m)\", fontsize=8)\n", + "ax_dbz.set_ylabel(\"Height (m)\", fontsize=8)\n", "\n", "# Add titles\n", - "ax_ctt.set_title(\"Cloud Top Temperature (degC)\", {\"fontsize\" : 7})\n", - "ax_wspd.set_title(\"Cross-Section of Wind Speed (kt)\", {\"fontsize\" : 7})\n", - "ax_dbz.set_title(\"Cross-Section of Reflectivity (dBZ)\", {\"fontsize\" : 7})\n", + "ax_ctt.set_title(\"Cloud Top Temperature (degC)\", {\"fontsize\" : 10})\n", + "ax_wspd.set_title(\"Cross-Section of Wind Speed (kt)\", {\"fontsize\" : 10})\n", + "ax_dbz.set_title(\"Cross-Section of Reflectivity (dBZ)\", {\"fontsize\" : 10})\n", "\n", "plt.savefig(\"/Users/ladwig/Documents/workspace/wrf_python/doc/source/_static/images/basemap_front.png\",\n", " transparent=False, bbox_inches=\"tight\")\n", @@ -1261,21 +1416,21 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 2", + "display_name": "Python 3", "language": "python", - "name": "python2" + "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", - "version": 2 + "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", - "pygments_lexer": "ipython2", - "version": "2.7.14" + "pygments_lexer": "ipython3", + "version": "3.6.7" } }, "nbformat": 4,