pycaps.util package

Submodules

pycaps.util.decompress module

arps_decompress(hd_var, dindex=None)

Decompresses variable fields from ARPS HDF files that use high compression options (specifically, the mapping of 32 bit –> 16 bit integers).

Parameters:

• hd_var – The compressed variable field
• dindex – Option to return a slice of the compressed data if only a slice is desired. The index may be either an integer (interpreted as an element of the first dimension) or a tuple. The tuple must have no more elements than the data has dimensions. Each element must be either an integer (a specific element along the given axis) or a Python slice object (a slice along the given axis). For example, dindex=(0, slice(None), slice(2, 6)) would return the first element along the first axis, all elements along the second axis, and elements 3-7 along the third axis (equivalent to asking for ary[0, :, 2:6], where ary is a numpy array).

Returns:

The decompressed equivalent of hd_var or the requested slice thereof.

pycaps.util.grid module

class ExperimentGrid(**kwargs)

Bases: object

Represents an ARPS Arakawa C grid, with provisions for subsets.

Parameters:

• grid_size (tuple) – Tuple of integers (NX, NY) representing the number of grid points in each dimension of the grid.
• grid_spacing (tuple) – Tuple of floats (DX, DY) representing the grid spacing in meters in each dimension of the grid.
• bounds (tuple) – Tuple of slice objects (SLICEX, SLICEY) representing the bounds in each direction of a subset of the grid. Default is (slice(None), slice(None))
• mpi (tuple) – Tuple of integers (NPROCX, NPROCY) representing the MPI configuration for this grid. Default is (1, 1), meaning no MPI.
• state_list (list) – An optional list of strings containing the two-letter postal codes for each state visible in the domain. This is used for optimizing the drawPolitical() method.
• projection (str) – Map projection to use. Only tested value is ‘lcc’ for Lambert conic conformal.
• resolution (str) – Resolution of the mapping data to load. Acceptable values are ‘c’ (crude), ‘l’ (low), and ‘i’ (intermediate). Recommended value is ‘i’.
• lat_0 – Center latitude for the Lambert projection (degrees N)
• lat_1 – True latitude 1 for the Lambert projection (degrees N)
• lat_2 – True latitude 2 for the Lambert projection (degrees N)
• lon_0 – True longitude for the Lambert projection (degrees E)
• ctr_lat – Center latitude for the domain (degrees N)
• ctr_lon – Center longitude for the domain (degrees E)

__call__(*args, **kwargs)

Convert between latitude, longitude coordinates and x, y coordinates on the domain.

The only meaningful keyword argument is inverse, which should be a boolean specifying whether to convert from latitudes and longitudes to x, y (False) or vice-versa (True). Default is False.

If inverse is False, *args is two numpy arrays of longitudes and latitudes in degrees. If inverse is True, *args is two numpy arrays of x and y coordinates in meters.

Returns:A tuple of numpy arrays of either x and y coordinates in meters or longitudes and latitudes in degrees.

core_bounds(icore, jcore)

Get the grid point bounds for a particular core.

Parameters:

• icore (int) – i-index of the core on the domain.
• jcore (int) – j-index of the core on the domain.

Returns:

A tuple of slice objects (BOUNDX, BOUNDY).

draw_political(scale_len=0, overlays=[], color='k', lw=1)

Draw political boundaries on the current matplotlib axes.

Parameters:

• scale_len (float) – Length of a scale bar in km to draw in the bottom-left corner of the plot. Default is 0, meaning no scale.
• overlays (list) – A list of strings pointing to shapefiles to plot as overlays.
• color (str) – Color in which to draw the political boundaries. Defaults to ‘k’ (black).
• lw (float) – Base line width for the political boundaries. Country boundaries are drawn with width lw, states with width 1.5 * lw, and counties are drawn with width 0.5 * lw

static from_file(fobj, projection='lcc', resolution='l', mpi=(1, 1), bounds=None)

Construct an ExperimentGrid object from information found in a history file. Should work for WRF and ARPS.

Parameters:

• fobj – File object (such as a NetCDF or HDF file) from which to take the information.
• projection (str) – Map projection to use. Currently, the only supported value is ‘lcc’ for Lambert Conic Conformal.
• resolution (str) – Resolution of the mapping data to load. Acceptable values are ‘c’ (crude), ‘l’ (low), and ‘i’ (intermediate). Recommended value is ‘i’.
• mpi (tuple) – Tuple of integers (NPROCX, NPROCY) representing the MPI configuration for this grid. Default is (1, 1), meaning no MPI.
• bounds (tuple) – Tuple of slice objects (SLICEX, SLICEY) representing the bounds in each direction of a subset of the grid. Default is (slice(None), slice(None))

Returns:

An ExperimentGrid object with parameters matching those in the input file.

Return type:

ExperimentGrid

get_boundary_coords()

Get the latitudes and longitudes of the boundary of this domain (useful for drawing this domain using another projection).

Returns:A tuple of 1-dimensional numpy arrays containing the latitudes and longitudes of the domain boundary in degrees.

get_bounds(pcm=False)

Get the grid point bounds for this subdomain

Parameters:pcm (bool) – Whether to assume this will be used in matplotlib’s pcolormesh() function. Default is False. Returns:The bounds as a tuple of slice objects (SLICEY, SLICEX)

get_center()

Get the center lat and lon in the domain.

Returns:A tuple of floats (LAT, LON) in degrees.

get_cores()

Get a list of cores that are in the domain subset.

Returns:A list of tuples containing the i and j indices of the cores in the domain subset.

get_grid_size()

Get the number of grid points.

Returns:The number of grid points in the full domain as a tuple (NX, NY).

get_grid_spacing()

Get the grid spacing.

Returns:The grid spacing in meters as a tuple (DX, DY).

get_width_height(override=False)

Get the width and height of the domain.

Returns:The width and height of the domain in meters of the subsetted domain as a tuple (WIDTHX, WIDTHY)

get_xy(ij=None, pcm=False)

Get x, y coordinates of the center each grid point or a specific grid point.

Parameters:

• ij (tuple) – Get the coordinates of the grid point specified by (i, j). Optional.
• pcm (bool) – Get the coordinates of the corners of the cells, rather than the centers.

Returns:

If ij is not specified, a tuple of 2-dimensional numpy arrays (x, y). Axes are ordered (NX, NY). If ij is specified, returns a tuple of floats. Both are in meters.

pycaps.util.make_proj_grids module

get_proj_obj(proj_dict)

make_proj_grids(proj_dict, grid_dict)

proj_main()

read_arps_map_file(map_filename)

read_ncar_map_file(map_filename)

pycaps.util.progress module

class ProgressBar(descr, n_steps, width=20)

Bases: object

complete_step(print_bar=True)

Tell a progress bar that one of the tasks is complete.

Parameters:print_bar (bool) – Whether or not to print the bar after this step (defaults to True).

initialize()

Starts timing the task and prints the initial progress bar to the screen.

is_complete()

Is the task complete?

Returns:A boolean specifying whether or not the task is complete.

set_step(step, print_bar=True)

Tell the progress bar that we have completed a certain number of tasks.

Parameters:

• step (int) – The number of tasks we have completed.
• print_bar (bool) – Whether or not to print the bar after this step (defaults to True).

pycaps.util.temporal module

class PatchedTemporal(*args)

Bases: object

Keep track of time in an experiment and do time conversions, but for timelines in which the time step is not constant.

__getitem__(index)

Get the time at a particular index.

Parameters:index (int) – The index at which to return the time. Returns:The number of seconds at that index since the experiment reference time. Return type:int

Examples

>>> temp1 = Temporal(0, 1200, 300)
>>> temp2 = Temporal(1200, 1800, 150)
>>> temp = PatchedTemporal(temp1, temp2)
>>> temp[6]
1500

__iter__()

Iterate over the experiment times.

Yields:int – The next time in seconds since the experiment reference time.

Examples

>>> temp1 = Temporal(0, 1200, 300)
>>> temp2 = Temporal(1200, 1800, 150)
>>> temp = PatchedTemporal(temp1, temp2)
>>> [ t for t in temp ]
[ 0, 300, 600, 900, 1200, 1350, 1500, 1650, 1800 ]

__len__()

Get the number of times in the experiment.

Returns:The number of times in the experiment. Return type:int

Examples

>>> temp1 = Temporal(0, 1200, 300)
>>> temp2 = Temporal(1200, 1800, 150)
>>> temp = PatchedTemporal(temp1, temp2)
>>> len(temp)
9

get_datetimes(aslist=False)

Get a list of datetimes represented by the Temporal object.

Parameters:aslist (bool) – Whether to return a list (True) or a Python generator (False). They can be used mostly interchangeably, but a generator is more efficient. Default is False (return a generator). Returns:A Python generator or list of datetime objects.

get_epochs(aslist=False)

Get a list of times represented by the Temporal object.

Parameters:aslist (bool) – Whether to return a list (True) or a Python generator (False). They can be used mostly interchangeably, but a generator is more efficient. Default is False (return a generator). Returns:A Python generator or list of times in seconds since the epoch.

get_strings(format, aslist=False)

Get a list of times as formatted strings.

Parameters:

• format (str) – The string format to use.
• aslist (bool) – Whether to return a list (True) or a Python generator (False). They can be used mostly interchangeably, but a generator is more efficient. Default is False (return a generator).

Returns:

A Python generator or list of strings containing the formatted times.

get_times()

Get the list of times represented by the Temporal object.

Returns:A list of times in seconds since the experiment reference time.

sec_to_dt(exp_seconds)

Convert a number of seconds since the experiment reference time to a datetime object.

Parameters:exp_seconds (int) – The number of seconds since the experiment reference time. Returns:A datetime object representing that time. Return type:datetime

sec_to_epoch(exp_seconds)

Convert a time in seconds since experiment reference time to a time in seconds since the epoch.

Parameters:exp_seconds (int) – The number of seconds since the experiment reference time. Returns:A number of seconds since the epoch. Return type:int

class Temporal(base_time, t_ens_start, t_ens_end, t_ens_step)

Bases: object

Keep track of time in an experiment and convert times between seconds since experiment start, datetime objects and seconds since the epoch.

__getitem__(index)

Get the time at a particular index.

Parameters:index – The index at which to return the time. Returns:If index is an integer, return the number of seconds at index since the experiment reference time. If index is a slice, return a new Temporal object with subsetted according to the slice.

Examples

>>> dt = datetime(2011, 5, 24, 18)
>>> temp = Temporal(dt, 0, 1800, 300)
>>> temp[3]
900

__iter__()

Iterate over the experiment times.

Yields:int – The next time in seconds since the experiment reference time.

Examples

>>> dt = datetime(2011, 5, 24, 18)
>>> temp = Temporal(dt, 0, 1800, 300)
>>> [ t for t in temp ]
[ 0, 300, 600, 900, 1200, 1500, 1800 ]

__len__()

Get the number of times in the experiment.

Returns:The number of times in the experiment. Return type:int

Examples

>>> dt = datetime(2011, 5, 24, 18)
>>> temp = Temporal(dt, 0, 1800, 300)
>>> len(temp)
7

get_datetimes(aslist=False)

Get a list of datetimes represented by the Temporal object.

Parameters:aslist (bool) – Whether to return a list (True) or a Python generator (False). They can be used mostly interchangeably, but a generator is more efficient. Default is False (return a generator). Returns:A Python generator or list of datetime objects.

get_epochs(aslist=False)

Get a list of times represented by the Temporal object.

Parameters:aslist (bool) – Whether to return a list (True) or a Python generator (False). They can be used mostly interchangeably, but a generator is more efficient. Default is False (return a generator). Returns:A Python generator or list of times in seconds since the epoch.

get_strings(str_format, aslist=False)

Get a list of times as formatted strings.

Parameters:

• str_format (str) – The string format to use.
• aslist (bool) – Whether to return a list (True) or a Python generator (False). They can be used mostly interchangeably, but a generator is more efficient. Default is False (return a generator).

Returns:

A Python generator or list of strings containing the formatted times.

get_times()

Get the list of times represented by the Temporal object.

Returns:A list of times in seconds since the experiment reference time.

sec_to_datetime(exp_seconds)

Convert a number of seconds since the experiment reference time to a datetime object.

Parameters:exp_seconds (int) – The number of seconds since the experiment reference time. Returns:A datetime object representing that time. Return type:datetime

sec_to_epoch(exp_seconds)

Convert a time in seconds since experiment reference time to a time in seconds since the epoch.

Parameters:exp_seconds (int) – The number of seconds since the experiment reference time. Returns:A number of seconds since the epoch. Return type:int

dt_to_epoch(dt)

Convert a Python datetime object to a number of seconds since the epoch (00 UTC 1 January 1970).

Parameters:dt (datetime) – A Python datetime object Returns:Time since the epoch in seconds.

epoch_to_dt(epoch)

Convert a number of seconds since the epoch (00 UTC 1 January 1970) to a Python datetime object.

Parameters:epoch (float) – Time since the epoch in seconds Returns:A Python datetime object.

temporal(base_time, *slices)

Create an object to keep track of time in an experiment and do time-related conversions.

Parameters:

• base_time (datetime) – The base time in the experiment (i.e. inittime in the ARPS input file) as a datetime object.
• *slices (slice) – One or more slice objects, each specifying start and end times (in seconds since the base time) and the time step length (in seconds) for a segment. Multiple segments are chained together under the hood to form a continuous timeline.

Returns:

A Temporal or PatchedTemporal object (both have the same interface).

pycaps.util.util module

class abstract(func, custom_name=None)

Bases: object

Use as a decorator to declare a method as abstract.

format_arps_time(rawtime)

Takes an integer number provided and converts it to the six-digit ARPS time format, which is then returned.

Parameters:rawtime (str) – The number to be converted into the ARPS time format Returns:rawtime converted into the ARPS time format

run_concurrently(target, placeholder_vals, args=[], kwargs={}, max_concurrent=-1, zip_result=False, progress=None)

Runs several instances of a function at the same time and returns all their outputs as a list.

Parameters:

• target (function) –
• placeholder_vals (list) – Values of a placeholder parameter to run the function on.
• args (list) – Arguments to pass to the target function. One or more may have the special value “__placeholder__”, which will be replaced with a value from placeholder_vals for each instance of the function.
• kwargs (dict) – Keyword arguments to pass to the target function. One or more may have the special value “__placeholder__”, which will be replaced with a value from placeholder_vals for each instance of the function.
• max_concurrent (int) – Maximum number of function instances to run at the same time. The default is to run an instance for each value in placeholder_vals at the same time.
• zip_result (bool) – A boolean specifying whether to run the zip() function on the result, perhaps if the function returns a tuple of values. Default is False.
• progress (ProgressBar) – An optional progress bar instance to use in displaying progress on the tasks.

Returns:

A list of the return values from each instance of the function, sorted by the corresponding placeholder value.

pycaps.util.wsr88d module

class RadarMeta(filename='data/radarinfo.dat')

Bases: object

Class for keeping track of metadata for US radars.

__call__(network)

Overrides the function call syntax (e.g. obj(...))

Parameters:network (str) – Name of the network from which to return the radar ids. The expected values are ‘tdwr’ for TDWRs, ‘casa’ for the CASA radar network, ‘legacy’ for legacy radars, ‘research’ for research radars, and ‘wsr88d’ for the WSR-88D network. The default value is None, which returns all radar ids. Returns:An iterator over radar metadata for the network.

__getitem__(key)

Overloads the container access operator (e.g. obj[...])

Parameters:key (str) – A 4-character radar ID Returns:A dictionary containing the metadata for the radar with the given 4-character ID

__iter__()

Overloads the iterator (e.g. for elem in obj)

Returns:An iterator over all the radars

__len__()

Overrides the length operator (e.g. len(obj))

Returns:The total number of radars.

get_radar_ids(network=None)

Get a list of radar ids from a given network

Parameters:network (str) – Name of the network from which to return the radar ids. The expected values are ‘tdwr’ for TDWRs, ‘casa’ for the CASA radar network, ‘legacy’ for legacy radars, ‘research’ for research radars, and ‘wsr88d’ for the WSR-88D network. The default value is None, which returns all radar ids. Returns:A list of 4-character radar ids

get_radar_meta(radar_id)

Gets the metadata for the given 4-character radar id.

Parameters:radar_id (str) – The 4-character id for a radar Returns:A dictionary containing the latitude, longitude, name, and ID of the radar.

Module contents