Converting string to cftime.datetime object and vice versa

basics.str_to_date(str, fmt=None, mode='start', calendar=None)[source]

Converts string to cftime.datetime object

Parameters

str (str) – string representing the time
fmt (str, default: ‘%Y-%m-%dT%H:%M:%S’) – Explicit format string
calendar (str, default: ‘standard’) – Calendar type for the datetimes
mode ({‘start’, ‘end’}, default: ‘start’) – start: Set cftime.datetime instance attributes not represented by fmt to 0. end: Set cftime.datetime instance attributes not represented by fmt to last possible values considering str.

Returns

cftime.datetime object

basics.date_to_str(date, fmt=None)[source]

Converts cftime.datetime or datetime.datetime object to string

Parameters

date (cftime.datetime or datetime.datetime object) – time to be converted
fmt (str, default: ‘%Y-%m-%dT%H:%M:%S’) – Explicit format string

Returns

str (str) – string representing the time

Creating and manipulating time axis

basics.date_range(start, end, frequency='D', calendar=None, **kwargs)[source]

Build CFTimeIndex

Parameters

start (cftime.datetime or datetime.datetime or str) – Left bound for generating dates
end (cftime.datetime or datetime.datetime or str) – Right bound for generating dates
frequency (str ot list) – frequency string or list of frequency strings for use with cftime calendars https://xarray.pydata.org/en/stable/generated/xarray.cftime_range.html Set elements to user-given frequency if type of frequency is str Set elements between user-given frequencies if type
calendar (str, default: ‘standard’)

Returns

CFTimeIndex

basics.date_range_to_frequency_limits(start=None, end=None, date_range=None, frequency=None, calendar=None, smonth=[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], emonth=[12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1], is_month_start=None, is_month_end=None, get_range=False, **kwargs)[source]

Get bounds of CFTimeIndex which satisfy user-given conditions.

Parameters

start (str or datetime.datetime or cftime.cftime, optional) – Left bound for generating dates
end (str or datetime.datetime or cftime.cftime, optional) – Right bound for generating dates
date_range (CFTimeIndex, optional) – CFTimeIndex containing cftime.datetime objects
frequency (str ot list) – CF frequency string or list of CF frequency strings or frequency string or list of frequency strings for use with cftime calendars https://xarray.pydata.org/en/stable/generated/xarray.cftime_range.html
calendar (str, default: ‘standard’) – Calendar type for the datetimes
smonth (list, default: [1,2,3,4,5,6,7,8,9,10,11,12]) – One of the allowed values of left bound’s datetime.datetime instance attribute month
emonth (list, default: [12,11,10,9,8,7,6,5,4,3,2,1]) – One of the allowed values of right bound’s datetime.datetime instance attribute month
is_month_start (bool, optional) – Value of left bound’s datetime.datetime instance attribute day must be equal to first day of the month Automatically set to True for sub_monthly frequencies
is_month_end (bool, optional) – Value of right bound’s datetime.datetime instance attribute day must be equal to last day of the month Automatically set to True for sub_monthly frequencies
get_range (bool, default:False) – If False returns left and right bounds If True returns CFTimeIndex

Returns

tuple – Tuple of start and end dates satisfying all conditions

Example

To get bounds of CFTimeIndex which satisfy user-given conditions. Monthly frequency values with a 360-day calendar have to start with the first month of any season and have to end with the last month of any season. It returns the tuple (2005-03-16 00:00:00 2005-11-16 00:00:00):

from pyhomogenize import basics

basics = basics()

start, end = basics.date_range_to_frequency_limits(
         start='2005-01-01',
         end='2005-12-30',
         smonth=[3,6,9,12],
         emonth=[2,5,8,11],
         calendar='360_day',
)

Reading, writing and manipulating netCDF file(s)

netcdf_basics.open()[source]: Opens file or list of files on disk. Result is automaticaly wrote to object’s attributes.

netcdf_basics.write(output=None, **kwargs)[source]

Writes self.ds or user-given xr.Dataset as netCDF file on disk.

Parameters: output (str, optional) – Name of the output netCDF file
Returns: self

netcdf_basics.to_global_attributes(indexes, attr_name)[source]

Adds or updates gloabl attributes

Parameters

indexes (str or list) – Attribute value to be added
attr_name (str) – Name of the attribute which will be added or updated

netcdf_basics.to_variable_attributes(indexes, attr_name)[source]

Adds or updates variable attributes

Parameters

indexes (str or list) – Attribute value to be added
attr_name (str) – Name of the attribute which will be added or updated

Checking self-created or netCDF file’s time axis

basics.is_month_start(cftime_range)[source]

Check whether each element of CFTimeIndex is first day of the month

Parameters: cftime_range (CFTimeIndex) – CFTimeIndex containing cftime.datetime objects
Returns: list – list of boolean values

basics.is_month_end(cftime_range)[source]

Check whether each element of CFTimeIndex is last day of the month

Parameters: cftime_range (CFTimeIndex) – CFTimeIndex containing cftime.datetime objects
Returns: list – list of boolean values

time_control.get_duplicates()[source]: Get string of duplicated time steps.

time_control.get_missings()[source]: Get string of missing time steps.

time_control.get_redundants()[source]: Get string of redundant time steps.

time_control.check_timestamps(selection=['duplicates', 'redundants', 'missings'], output=None, correct=False)[source]

Check netCDF file’s time axis.

Exist whether duplicated, missing and/or redundant time steps.

Parameters

selection (str or list, default=[‘duplicates’,’redundants’,’missings’]) – Check which kind of time steps exist.
output (str, optional) – Write result on disk.
correct (bool, default: False) – Delete located time steps from xr.Dataset. Automatically set True if output.

Returns

pyhomogenize.time_control object

Example

To check netCDF file’s time axis whether duplicated, missing and/or redundant time steps exist and result write on disk:

from pyhomogenize import time_control

time_control('input.nc').check_timestamps(output='output.nc')

time_control.select_time_range(time_range, output=None)[source]

Select user-given time slice from xr.Dataset

Parameters

time_range (list) – List of two strings or cftime.datatime object representing the left and right time bounds
output (str, optional) – Write result on disk.

Returns

pyhomogenize.time_control object

Example

To select time slice from netCDF file.:

from pyhomogenize import time_control

time_control('input.nc').select_time_range(
                             ['2005-01-01','2005-12-31'],
                             output='output.nc')

time_control.select_limited_time_range(output=None, **kwargs)[source]

Select time slice from xr.Dataset satisfying user-given conditions. See pyh.basics.date_range_to_frequency_limits.

Parameters

output (str, optional) – Write result on disk.
kwargs – Optional parameters transferred to function date_range_to_frequency_limits: smonth emonth is_month_start is_month_end

Returns

pyhomogenize.time_control object

Example

To select time slice from netCDF file starts with the first month of any season and ends with the last month of any season. The time slice is then e.g. from 2005-03-16 to 2005-11-16:

from pyhomogenize import time_control

time_control('input.nc').select_limited_time_range(
                                   smonth=[3,6,9,12],
                                   emonth=[2,5,8,11],
                                   output='output.nc')

time_control.within_time_range(requested_time_range, fmt=None)[source]

Checks whether netCDF files time axis is within user-given borders.

Parameters

requested_time_range (list) – List of two strings or cftime.datatime object representing the left and right time bounds
fmt (str, default: ‘%Y-%m-%dT%H:%M:%S’) – Explicit format string for converting string into cftime.datetime object

Returns

bool

Example

To check whether netCDF files time axis is within user-given borders.:

from pyhomogenize import time_control

within = time_control('input.nc').within_time_range(['2005-01-02',
                                                     '2005-12-31'])

Comparing time axes of several netCDF files and/or xr.Datasets

time_compare.max_intersection()[source]

Get the maximum intersection of all time axes.

Intersection of user-given netCDF files on disk and/or time_control objects.

Returns: tuple – Left and right border of maximum time intersection

Example

To get left and right border of maximum time intersection of two netCDF files.:

from pyhomogenize import time_compare

sinter, einter = time_compare('input1.nc',
                              'input2.nc').max_intersection()

time_compare.select_max_intersection(**kwargs)[source]

Select maximum intersection time slice.

Intersection of user-given netCDF files on disk and/or time_control objects.

Parameters: kwargs – Optional parameters transferred to function select_time_range output
Returns: list – List of user-given netCDF files on disk and/or time_control objects cropped to maximum time intersection.

Example

To crop time axes of two netCDF files to maximum time intersection.:

from pyhomogenize import time_compare

time_compare('input1.nc',
             'input2.nc').select_max_intersection(output='output.nc')