rcatool.utils package

Submodules

rcatool.utils.atmosphys module

Atmospheric Function Module

Functions for calculations of various physical properties

Created: Autumn 2017 Authors: Petter Lind & David Lindstedt

rcatool.utils.atmosphys.brunt_vaisala_frequency(ddict, model, lower_plevel, upper_plevel)

Calculate Brunt-Vaisala frequency in layer bounded by two pressure levels. Pressure must be given in hPa, temperature (T) in Kelvin and specific humidity (q) in kg/kg.

Parameters:

• ddict (dictionary) – Data dictionary

• model (str) – model data to use

• lower_plevel (float) – lower pressure surface

• upper_plevel (float) – upper pressure surface

Returns:

N2 – The squared Brunt-Vaisala frequency

Return type:

array with floats

rcatool.utils.atmosphys.calc_e_from_sh(sh, P=101325)

Vapor pressure over liquid surface can be calculated from a variety of different combinations of state variables. Here, vapor pressure is calculated from specific humidity sh (kg/kg) and pressure P (Pa). Formula is given in standard literature; e.g. eq. 2.19 in Rogers & Yau (Cloud physics) and eq. 4.1.4 in Emanuel (1994). Reference: * Emanuel, K. A. (1994): Atmospheric Convection. New York, NY:

Oxford University Press, 580 pp.

rcatool.utils.atmosphys.calc_e_from_w(w, P=1013.25)

Vapor pressure over liquid surface can be calculated from a variety of different combinations of state variables. Here, vapor pressure is calculated from mixing ratio w (kg/kg) and pressure P. Formula is given in standard literature; e.g. eq. 2.18 in Rogers&Yau (Cloud physics) and eq. 4.1.2 in Emanuel (1994). Reference: * Emanuel, K. A. (1994): Atmospheric Convection. New York, NY:

Oxford University Press, 580 pp.

rcatool.utils.atmosphys.calc_es(T)

Returns saturation vapor pressure in hPa at temperature T (Kelvin) Formula 2.17 in Rogers&Yau

rcatool.utils.atmosphys.calc_ws(T, P=1013.25)

Returns saturation mixing ratio in kg/kg at temperature T (Kelvin) and pressure P (hPa). Formula in https://www.weather.gov/media/epz/wxcalc/mixingRatio.pdf

rcatool.utils.atmosphys.lifted_condensation_temperature(tair, tdew)

Returns the lifted condensation temperature in units of Kelvin.

Parameters:

• tair – Air temperature (in units of Kelvin)

• floats (float/array of) – Air temperature (in units of Kelvin)

• tdew – Dew point temperature (in units of Kelvin)

• floats – Dew point temperature (in units of Kelvin)

Returns:

Lifted condensation temperature (in units of Kelvin)

Return type:

tc, floats/arrays of floats

rcatool.utils.atmosphys.rh2sh(rh, T, P=1013.25)

Convert relative humidity to specific humidity Code from: https://github.com/PecanProject/pecan/blob/master/modules/data.atmosphere/R/metutils.R Equation for sh from standard literature, e.g. K. Emanuel (1994; eq. 4.1.4) Reference: * Emanuel, K. A. (1994): Atmospheric Convection. New York, NY:

Oxford University Press, 580 pp.

Parameters:

• rh – Relative humidity in proportion, not percent

• floats (float/array of) – Relative humidity in proportion, not percent

• T – Absolute temperature in Kelvin

• floats – Absolute temperature in Kelvin

• P – Pressure in hPa (mb)

• floats – Pressure in hPa (mb)

Returns:

Specific humidity in kg/kg

Return type:

sh,

rcatool.utils.atmosphys.sh2rh(sh, T, P=1013.25)

Convert specific humidity to relative humidity Code from: https://github.com/PecanProject/pecan/blob/master/modules/data.atmosphere/R/metutils.R

Parameters:

• sh – Specific humidity in kg/kg

• floats (float/array of) – Specific humidity in kg/kg

• T – Absolute temperature in Kelvin

• floats – Absolute temperature in Kelvin

• P – Pressure in hPa (mb)

• floats – Pressure in hPa (mb)

Returns:

Relative humidity in fraction (not percent)

Return type:

rh,

rcatool.utils.atmosphys.sh2td(sh, p)

Returns dew point temperature (K) at mixing ratio sh (kg/kg) and pressure p (Pa). Insert Td in 2.17 in Rogers&Yau and solve for Td

rcatool.utils.atmosphys.td(e)

Returns dew point temperature (C) at vapor pressure e (Pa) Insert Td in 2.17 in Rogers&Yau and solve for Td

rcatool.utils.atmosphys.td2sh(Td, P)

Convert dew point temperature to specific humidity https://github.com/PecanProject/pecan/blob/master/modules/data.atmosphere/R/metutils.R

Parameters:

• Td – Absolute dew point temperature in Kelvin

• floats (float/array of) – Absolute dew point temperature in Kelvin

• P – Pressure in mb

• floats – Pressure in mb

Returns:

Specific humidity in g/kg

Return type:

p, float/array of floats

rcatool.utils.atmosphys.theta_equivalent(tair, tdew, p, sh)

Returns the equivalent potential temperature in units of Kelvin. Based on approximative formula from Bolton, D. 1980 See also: https://glossary.ametsoc.org/wiki/Equivalent_potential_temperature

Parameters:

• tair – Air temperature (in units of Kelvin)

• floats (float/array of) – Air temperature (in units of Kelvin)

• tdew – Dew point temperature (in units of Kelvin)

• floats – Dew point temperature (in units of Kelvin)

• p – Pressure in units of hPa

• floats – Pressure in units of hPa

• sh – Specific humidity in units of kg/kg

• floats – Specific humidity in units of kg/kg

Returns:

Equivalent potential temperature (in units of Kelvin)

Return type:

theta_e, floats/arrays of floats

rcatool.utils.atmosphys.theta_pseudoequiv(tair, tdew, p, sh)

Returns the pseudo-equivalent potential temperature in units of Kelvin. Based on approximative formula from Bolton, D. 1980 See also: https://glossary.ametsoc.org/wiki/Pseudoequivalent_potential_temperature

Note that here the specific humidity is used instead of mixing ratio, which are approximately the same (low water vapor mass in parcel compared to dry mass).

Parameters:

• tair – Air temperature (in units of Kelvin)

• floats (float/array of) – Air temperature (in units of Kelvin)

• tdew – Dew point temperature (in units of Kelvin)

• floats – Dew point temperature (in units of Kelvin)

• p – Pressure in units of hPa

• floats – Pressure in units of hPa

• sh – Specific humidity in units of kg/kg

• floats – Specific humidity in units of kg/kg

Returns:

Pseudo-equivalent potential temperature (in units of Kelvin)

Return type:

theta_ep, floats/arrays of floats

rcatool.utils.atmosphys.uv2wind(u, v)

Converts u and v components to wind speed and direction.

Parameters:

• u – east/west wind component

• floats (float/array of) – east/west wind component

• v – north/south wind component

• floats – north/south wind component

Returns:

wind speed and wind direction respectively.

Return type:

(ws, wd), floats/arrays of floats

rcatool.utils.atmosphys.vpd(rh, T)

Calculate VPD - vapor pressure deficit from relative humidity and temperature. Code from: https://github.com/PecanProject/pecan/blob/master/modules/data.atmosphere/R/metutils.R

Parameters:

• rh – Relative humidity in fraction (not percent)

• floats (float/array of) – Relative humidity in fraction (not percent)

• T – Absolute temperature in Kelvin

• floats – Absolute temperature in Kelvin

Returns:

Vapor pressure deficit (in hPa/mb)

Return type:

vpd,

rcatool.utils.atmosphys.wind2uv(ws, wd, dir_unit='rad')

Converts wind speed and direction to u and v components.

Parameters:

• ws – Wind speed data

• floats (float/array of) – Wind speed data

• wd – Wind direction data

• floats – Wind direction data

• dir_deg – Units of the wind direction data; ‘rad’ (default) or ‘deg’.

• string – Units of the wind direction data; ‘rad’ (default) or ‘deg’.

Returns:

u and v wind components

Return type:

(u, v), floats/arrays of floats

rcatool.utils.draw_polygon module

draw_polygon.py

Draw a simple polygon using matplotlib with mouse event handling

Copyright (C) 2013 Greg von Winckel

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Created: Sat Oct 26 22:04:59 MDT 2013

class rcatool.utils.draw_polygon.Canvas(ax)

Bases: object

set_location(event)

update_path(event)

rcatool.utils.file_io module

This module provides functions representing tools to read and write NetCDF files.

@author Petter Lind @date 2014-10-20

rcatool.utils.file_io.fracday2datetime(tdata)

Takes an array of dates given in %Y%m%d.%f format and returns a corresponding datetime object

rcatool.utils.file_io.getDimensions(nc, close=False)

Function to retrieve the dimensions of a netcdf file nc: Netcdf object opened with function “openFile” close: set True if you want the file to be closed after retrieval. Returns lons and lats, time as well as gridsize Nx,Ny

rcatool.utils.file_io.getParams(nc, params, close=False)

Function to retrieve variables from a netcdf file nc: Netcdf object opened with function “openFile” params: A list of strings with the parameters to be retrieved close: set True if you want the file to be closed after retrieval. Returns a list with the given parameters.

rcatool.utils.file_io.ncdump(nc_fid, verb=True)

ncdump outputs dimensions, variables and their attribute information. The information is similar to that of NCAR’s ncdump utility. ncdump requires a valid instance of Dataset.

Parameters:

• nc_fid (netCDF4.Dataset) – A netCDF4 dateset object

• verb (Boolean) – whether or not nc_attrs, nc_dims, and nc_vars are printed

Returns:

• nc_attrs (list) – A Python list of the NetCDF file global attributes

• nc_dims (list) – A Python list of the NetCDF file dimensions

• nc_vars (list) – A Python list of the NetCDF file variables

rcatool.utils.file_io.openFile(filename)

Function to open netcdf file. filename: string with full path to file

rcatool.utils.file_io.write2netcdf(filename, filedir, dim, variables, global_attr=None, nc_format='NETCDF4', compress=False, complevel=4)

Opens a new NetCDF file to write the input data to. For nc_format, you can choose from ‘NETCDF3_CLASSIC’, ‘NETCDF3_64BIT’, ‘NETCDF4_CLASSIC’, and ‘NETCDF4’ (default)

Parameters:

• filename (str) – name of netcdf file to write to

• filedir (str) – directory path to put the file

• dim (dict) – dimensions to be used

• variables (dict) – variables with their values and attributes

• global_attr (dict) – global attributes (optional)

• nc_format (str) – Specify netCDF format

• compress (boolean) – Whether to compress (using ‘zlib=True’ in the write call).

• complevel (int) – An integer between 1-9 representing the degree of compression to be used.

The dictionaries should be structured as described by the examples below:

dims_dict = {} dims_dict[‘x’] = 154 dims_dict[‘y’] = 192 dims_dict[‘nv’] = 4 dims_dict[‘time’] = None

vars_dict = {} vars_dict = {‘lon’: {‘values’: lons, ‘dims’: (‘y’, ‘x’),

‘attributes’: {‘long_name’: ‘longitude’,

‘standard_name’: ‘longitude’, ‘units’: ‘degrees_east’, ‘_CoordinateAxisType’: ‘Lon’}},

‘lat’: {‘values’: lats, ‘dims’: (‘y’, ‘x’),

‘attributes’: {‘long_name’: ‘latitude’,

‘standard_name’: ‘latitude’, ‘units’: ‘degrees_north’, ‘_CoordinateAxisType’: ‘Lat’}},

‘pr’: {‘values’: pr, ‘dims’: (‘time’, ‘y’, ‘x’),

‘attributes’: {‘long_name’: ‘precipitation’,

‘standard_name’: ‘precipitation flux’,

‘units’: ‘kg m-2 s-1’, ‘coordinates’: ‘lon lat’, ‘_FillValue’: -9999.}}}

glob_attr = {‘description’: ‘some description of file’,

‘history’: ‘Created ‘ + time.ctime(time.time()), ‘experiment’: ‘Fractions Skill Score analysis’, ‘contact’: ‘petter.lind@smhi.se’, ‘references’: ‘http://journals.ametsoc.org/doi/abs/ 10.1175/2007MWR2123.1’}

rcatool.utils.grids module

Grid applications

Functions to remap data given source and target grids Some utilities use python tool xESMF.

Author: Petter Lind (contributions from A. Prein) Date: Jan 2019

rcatool.utils.grids.add_matrix_NaNs(regridder)

Replace zero values of cells in the new grid that are outside the old grid’s domain with NaN’s.

Parameters:

regridder (Object from xESMF Regridder function)

Returns:

Modified regridder where zero valued cells (outside source grid) has been replaced with NaN’s.

Return type:

regridder

rcatool.utils.grids.calc_vertices(lons, lats, write_to_file=False, filename=None)

Estimate the cell boundaries from the cell location of regular grids

Parameters:

• lons (arrays) – Longitude and latitude values

• lats (arrays) – Longitude and latitude values

• write_to_file (bool) – If True lat/lon information, including vertices, is written to file following the structure given by cdo commmand ‘griddes’

• filename (str) – Name of text file for the grid information. Only used if write_to_file is True. If not provided, a default name will be used.

Returns:

lon_bnds, lat_bnds – Arrays of dimension [4, nlat, nlon] containing cell boundaries of each gridcell in lons and lats

Return type:

arrays

rcatool.utils.grids.fnCellCorners(rgrLon, rgrLat)

File name: fnCellBoundaries Author: Andreas Prein E-mail: prein@ucar.edu Date created: 20.03.2015 Date last modified: 20.03.2015

Estimate the cell boundaries from the cell location of regular grids

returns: rgrLonBND & rgrLatBND –> arrays of dimension [nlon,nlat] containing the cell boundaries of each gridcell in rgrlon and rgrlat

rcatool.utils.grids.fnRemapCon(rgrLonS, rgrLatS, rgrLonT, rgrLatT, grOperator, rgrData)

File name: fnRemapCon Author: Andreas Prein E-mail: prein@ucar.edu Date created: 13.06.2017 Date last modified: 13.06.2017

Uses the remap operator generated by the function fnRemapConOperator to remap data to a target grid conservatively

Parameters:

• rgrLonS (arrays) – Source grid longitude and latitude values

• rgrLatS (arrays) – Source grid longitude and latitude values

• rgrLonT (arrays) – Target grid longitude and latitude values

• rgrLatT (arrays) – Target grid longitude and latitude values

• grOperator (dictionary) – Remapping operator returned from fnRemapConOperator.

• rgrData (3D/4D array) – Data to be regridded, structured as (time, lat, lon) or (time, variables, lat, lon).

Returns:

rgrTarData – Remapped data matrix

Return type:

array

rcatool.utils.grids.fnRemapConOperator(rgrLonS, rgrLatS, rgrLonT, rgrLatT, rgrLonSBNDS=None, rgrLatSBNDS=None, rgrLonTBNDS=None, rgrLatTBNDS=None)

File name: fnRemapConOperator Author: Andreas Prein E-mail: prein@ucar.edu Date created: 26.05.2017 Date last modified: 26.05.2017

Generates an opperator to coservatively remapp data from a source rectangular grid to an target rectangular grid.

Parameters:

• rgrLonS (arrays) – Source grid longitude and latitude values

• rgrLatS (arrays) – Source grid longitude and latitude values

• rgrLonT (arrays) – Target grid longitude and latitude values

• rgrLatT (arrays) – Target grid longitude and latitude values

• rgrLonSBNDS (arrays) – Source grid longitude and latitude grid point boundaries (corners). These must be given in the structure (lat, lon, vertices) where vertices are the four corners of each grid point. If not provided (default) then corners are calculated using fnCellCorners.

• rgrLatSBNDS (arrays) – Source grid longitude and latitude grid point boundaries (corners). These must be given in the structure (lat, lon, vertices) where vertices are the four corners of each grid point. If not provided (default) then corners are calculated using fnCellCorners.

• rgrLonTBNDS (arrays) – Target grid longitude and latitude grid point boundaries (corners). See above for more info.

• rgrLatTBNDS (arrays) – Target grid longitude and latitude grid point boundaries (corners). See above for more info.

Returns:

grConRemapOp – opperator that contains the grid cells and their wheights of the source grid for each target grid cell

Return type:

dictionary

rcatool.utils.grids.rotated_grid_transform(lons, lats, pole_lon, pole_lat, rot2reg=True)

rcatool.utils.ini_reader module

Config reader module

Creates and return a dictionary built from a config file.

Created: Autumn 2016 Authors: David Lindstedt & Petter Lind

rcatool.utils.ini_reader.get_config_dict(ini_file)

Create a dictionary from then input config file. PARAMETERS: config (.ini) file RETURNS : Dictionary

rcatool.utils.polygons module

rcatool.utils.polygons.create_polygon()

Retrieve polygon arbitrarily drawn interactively on a map by mouse clicking.

Parameters:

print_zoom_areas (Boolean) – Prints available zoom regions for polygon selection.

Returns:

poly – List with tuples of lat/lon coordinates for drawn polygon

Return type:

list

rcatool.utils.polygons.find_geo_indices(lons, lats, x, y)

Search for nearest decimal degree in an array of decimal degrees and return the index. np.argmin returns the indices of minimum value along an axis. Subtract dd from all values in dd_array, take absolute value and find index of minimum.

Parameters:

• lons/lats (1D/2D numpy array) – Latitude and longitude values defining the grid.

• x (int/float) – Coordinates of searched for data point

• y (int/float) – Coordinates of searched for data point

Returns:

lat_idx/lon_idx – The latitude and longitude indices where closest to searched data point.

Return type:

ints

rcatool.utils.polygons.mask_region(xp, yp, area, data=None, iter_3d=None, cut_data=False)

Routine to mask grid points outside a specified polygon.

Parameters:

• xp (numpy arrays) – eastward and northward grid points respectively, normally lon/lat arrays.

• yp (numpy arrays) – eastward and northward grid points respectively, normally lon/lat arrays.

• area (string or list with tuples) – Either name of predefined region to extract (see reg_dict function for more info.), or a list with tuples defining a polygon; e.g. [(lon1, lat1), (lon2, lat2),…,(lonN, latN), (lon1, lat1)]. NB! First and last tuple must be the same, closing the polygon.

• data (2D/3D numpy array, optional) – data matrix

• iter_3d (int, optional) – If set, masking is performed along the zeroth dimension of array. Thus array must be 3D and have shape [iter_3d, y, x].

• cut_data (boolean, optional) – If True, the data will be cut to a box that covers the input area, leaving one extra (masked) grid point beyond each limiting north/south/east/west grid point. This option will return not only masked and cut data but also cut lon/lat data as well as the box edges (as indices) in the x,y plane.

Returns:

• mask_out (boolean array) – A 2D mask with True inside region of interest, False outside. Returned if data is None.

• masked_data (2D/3D numpy array) – If data is passed to function, this is the returned masked data.

• xp_cut/yp_cut (numpy arrays) – If cut_data is True, these arrays are the cut xp/yp arrays

• reg_x_edges, reg_y_edges (tuples) – If cut_data is True, the tuples contain index of the edges of cropped region in x and y directions respectively.

rcatool.utils.polygons.plot_polygon(polygon, savefig=False, figpath=None)

Plot polygon on map.

Parameters:

• polygon (string or list) – Name of polygon as defined by poly_dict dictionary in ‘polygons’ function, or list with polygon coordinates [[lon1, lat1], [lon2, lat2], …, [lon1, lat1]].

• savefig (boolean) – If True, figure is saved to ‘figpath’ location (‘figpath’ must be set). If false, figure is displayed on screen.

• figpath (string) – Path to folder for saved polygon figure.

rcatool.utils.polygons.polygons(area='', poly_print=False)

See available polygons and retrieve path to polygon files.

Parameters:

• area (string) – name of polygon to be extracted

• poly_print (boolean) – if available polygons should be printed

Returns:

area_file – path to the text file with polygon data

Return type:

string

rcatool.utils.polygons.topo_mask(data, orog, orog_int)

Rotuine to mask grid points outside a specified height interval.

Parameters:

• data (2D numpy array) – the data matrix

• orog (2D numpy array) – array containing topographical heights (same resolution as data)

• orog_int (1D array,list,tuple) – the height interval outside which data should be masked.

Returns:

masked_data – the masked data

Return type:

2D numpy array

Module contents