improver.generate_ancillaries.generate_timezone_mask module

Module for generating timezone masks.

class GenerateTimezoneMask(include_dst=False, time=None, groupings=None)[source]

Bases: BasePlugin

A plugin to create masks for regions of a geographic grid that are on different timezones. The resulting masks can be used to isolate data for specific timezones from a grid of the same shape as the cube used in this plugin to generate the masks.

__init__(include_dst=False, time=None, groupings=None)[source]

Configure plugin options to generate the desired ancillary.

Parameters

include_dst (bool) – If True, find and use the UTC offset to a grid point including the effect of daylight savings.
time (Optional[str]) – A datetime specified in the format YYYYMMDDTHHMMZ at which to calculate the mask (UTC). If daylight savings are not included this will have no impact on the resulting masks.
groupings (Optional[Dict[int, List[int]]]) –
A dictionary specifying how timezones should be grouped if so desired. This dictionary takes the form:
```
{-9: [-12, -5], 0:[-4, 4], 9: [5, 12]}
```
The numbers in the lists denote the inclusive limits of the groups. This is of use if data is not available at hourly intervals.

_abc_impl = <_abc_data object>

_calculate_offset(point_tz)[source]

Calculates the offset in seconds from UTC for a given timezone, either with or without consideration of daylight savings.

Parameters: point_tz (str) – The string representation of the timezone for a point e.g. “America/Chicago”,
Return type: int
Returns: Timezone offset from UTC in seconds.

_calculate_tz_offsets(coordinate_pairs)[source]

Loop over all the coordinates provided and for each calculate the offset from UTC in seconds.

TimezoneFinder returns a string representation of the timezone for a point if it is defined, e.g. “America/Chicago”, otherwise it returns None.

For points without a national timezone (point_tz = None), usually over the sea, the nautical timezone offset is calculated which is based upon longitude. These are 15 degree wide bands of longitude, centred on the Greenwich meridian; note that the bands corresponding to UTC -/+ 12 hours are only 7.5 degrees wide. Here longitudes are enforced between -180 and 180 degrees so the timezone offset can be calculated as:

offset in hours = np.around(longitude / 15) offset in seconds = 3600 * np.around(longitude / 15)

Parameters: coordinate_pairs (ndarray) – A numpy array containing all the pairs of coordinates that describe the y-x points in the grid. This array is 2-dimensional, being 2 by the product of the grid’s y-x dimension lengths.
Return type: ndarray
Returns: A 1-dimensional array of grid offsets with a length equal to the product of the grid’s y-x dimension lengths.

_create_template_cube(cube)[source]

Create a template cube to store the timezone masks. This cube has only one scalar coordinate which is time, denoting when it is valid; this is only relevant if using daylight savings. The attribute includes_daylight_savings is set to indicate this.

Parameters: cube (Cube) – A cube with the desired grid from which coordinates are taken for inclusion in the template.
Return type: Cube
Returns: A template cube in which each timezone mask can be stored.

static _get_coordinate_pairs(cube)[source]

Create an array containing all the pairs of coordinates that describe y-x points in the grid.

Parameters: cube (Cube) – The cube from which the y-x grid is being taken.
Return type: ndarray
Returns: A numpy array containing all the pairs of coordinates that describe the y-x points in the grid. This array is 2-dimensional, with shape (2, (len(y-points) * len(x-points))).

_group_timezones(timezone_mask)[source]

If the ancillary will be used with data that is not available at hourly intervals, the masks can be grouped to match the intervals of the data. For example, 3-hourly interval data might group UTC offsets:

{12: [-12, -11], 9: [-10, -9, -8], 6: [-7, -6, -5], etc.}

The dictionary specifying the groupings has a key, which provides the UTC offset to be used for the group. The list contains the UTC offsets that should be grouped together.

The grouped UTC_offset cubes are collapsed together over the UTC_offset coordinate using iris.analysis.MIN. This means all the unmasked (0) points in each cube are preserved as the dimension is collapsed, enlarging the unmasked region to include all unmasked points from all the cubes.

Parameters: timezone_mask (Union[CubeList, List[Cube]]) – A cube list containing a mask cube for each UTC offset that has been found necessary.
Return type: CubeList
Returns: A cube list containing cubes created by blending together different UTC offset cubes to create larger masked regions.

_set_time(cube)[source]

Set self.time to a datetime object specifying the date and time for which the masks should be created. self.time is set in UTC.

Parameters: cube (Cube) – The cube from which the validity time should be taken if one has not been explicitly provided by the user.
Return type: None

process(cube)[source]

Use the grid from the provided cube to create masks that correspond to all the timezones that exist within the cube. These masks are then returned in a single cube with a leading UTC_offset coordinate that differentiates between them.

Parameters: cube (Cube) – A cube with the desired grid. If no ‘time’ is specified in the plugin configuration the time on this cube will be used for determining the validity time of the calculated UTC offsets (this is only relevant if daylight savings times are being included).
Return type: Cube
Returns: A timezone mask cube with a leading UTC_offset dimension. Each UTC_offset slice contains a field of ones (masked out) and zeros (masked in) that correspond to the grid points whose local times are at the relevant UTC_offset.