Python cftime.datetime() Examples

def test_cftime_transform_noleap_warn(self):
        try:
            import cftime
        except:
            raise SkipTest('Test requires cftime library')
        gregorian_dates = [cftime.DatetimeNoLeap(2000, 2, 28),
                           cftime.DatetimeNoLeap(2000, 3, 1),
                           cftime.DatetimeNoLeap(2000, 3, 2)]
        curve = Curve((gregorian_dates, [1, 2, 3]))
        plot = bokeh_renderer.get_plot(curve)
        xs = plot.handles['cds'].data['x']
        self.assertEqual(xs.astype('int64'),
                         np.array([951696000000, 951868800000, 951955200000]))
        substr = (
            "Converting cftime.datetime from a non-standard calendar "
            "(noleap) to a standard calendar for plotting. This may "
            "lead to subtle errors in formatting dates, for accurate "
            "tick formatting switch to the matplotlib backend.")
        self.log_handler.assertEndsWith('WARNING', substr) 

def cfindex_end_time(cfindex, freq):
    """
    Get the start of a period for a pseudo-period index. As we are using
    datetime indices to stand in for period indices, assumptions regarding the
    period are made based on the given freq. IMPORTANT NOTE: this function
    cannot be used on greater-than-day freq that start at the beginning of a
    month, e.g., 'MS', 'QS', 'AS' -- this mirrors pandas behavior.

    Parameters
    __________
    cfindex : CFTimeIndex
        CFTimeIndex as a proxy representation for CFPeriodIndex
    freq : str
        String specifying the frequency/offset such as 'MS', '2D', 'H', or '3T'

    Returns
    _______
    CFTimeIndex
        The ending datetimes of periods inferred from dates and freq
    """
    return CFTimeIndex([cftime_end_time(date, freq) for date in cfindex]) 

def ensure_datetime(obj):
    """Return the object if it is a datetime-like object

    Parameters
    ----------
    obj : Object to be tested.

    Returns
    -------
    The original object if it is a datetime-like object

    Raises
    ------
    TypeError if `obj` is not datetime-like
    """
    _VALID_TYPES = (str, datetime.datetime, cftime.datetime,
                    np.datetime64)
    if isinstance(obj, _VALID_TYPES):
        return obj
    raise TypeError("datetime-like object required.  "
                    "Type given: {}".format(type(obj))) 

def datetime_or_default(date, default):
    """Return a datetime-like object or a default.

    Parameters
    ----------
    date : `None` or datetime-like object or str
    default : The value to return if `date` is `None`

    Returns
    -------
    `default` if `date` is `None`, otherwise returns the result of
    `utils.times.ensure_datetime(date)`

    """
    if date is None:
        return default
    else:
        return ensure_datetime(date) 

def cfindex_start_time(cfindex, freq):
    """
    Get the start of a period for a pseudo-period index. As we are using
    datetime indices to stand in for period indices, assumptions regarding the
    period are made based on the given freq. IMPORTANT NOTE: this function
    cannot be used on greater-than-day freq that start at the beginning of a
    month, e.g., 'MS', 'QS', 'AS' -- this mirrors pandas behavior.

    Parameters
    __________
    cfindex : CFTimeIndex
        CFTimeIndex as a proxy representation for CFPeriodIndex
    freq : str
        String specifying the frequency/offset such as 'MS', '2D', 'H', or '3T'

    Returns
    _______
    CFTimeIndex
        The starting datetimes of periods inferred from dates and freq
    """
    return CFTimeIndex([cftime_start_time(date, freq) for date in cfindex]) 

def ensure_cftime_array(time: Sequence):
    """Convert an input 1D array to an array of cftime objects. Python's datetime are converted to cftime.DatetimeGregorian.

    Raises ValueError when unable to cast the input.
    """
    if isinstance(time, xr.DataArray):
        time = time.indexes["time"]
    elif isinstance(time, np.ndarray):
        time = pd.DatetimeIndex(time)
    if isinstance(time[0], cftime.datetime):
        return time
    if isinstance(time[0], pydt.datetime):
        return np.array(
            [cftime.DatetimeGregorian(*ele.timetuple()[:6]) for ele in time]
        )
    raise ValueError("Unable to cast array to cftime dtype") 

def cftime_to_timestamp(date, time_unit='us'):
    """Converts cftime to timestamp since epoch in milliseconds

    Non-standard calendars (e.g. Julian or no leap calendars)
    are converted to standard Gregorian calendar. This can cause
    extra space to be added for dates that don't exist in the original
    calendar. In order to handle these dates correctly a custom bokeh
    model with support for other calendars would have to be defined.

    Args:
        date: cftime datetime object (or array)

    Returns:
        time_unit since 1970-01-01 00:00:00
    """
    import cftime
    utime = cftime.utime('microseconds since 1970-01-01 00:00:00')
    if time_unit == 'us':
        tscale = 1
    else:
        tscale = (np.timedelta64(1, 'us')/np.timedelta64(1, time_unit))
    return utime.date2num(date)*tscale 

def axisinfo(unit, axis):
        """
        Returns the :class:`~matplotlib.units.AxisInfo` for *unit*.

        *unit* is a tzinfo instance or None.
        The *axis* argument is required but not used.
        """
        calendar, date_unit, date_type = unit

        majloc = NetCDFTimeDateLocator(4, calendar=calendar,
                                       date_unit=date_unit)
        majfmt = NetCDFTimeDateFormatter(majloc, calendar=calendar,
                                         time_units=date_unit)
        if date_type is CalendarDateTime:
            datemin = CalendarDateTime(cftime.datetime(2000, 1, 1),
                                       calendar=calendar)
            datemax = CalendarDateTime(cftime.datetime(2010, 1, 1),
                                       calendar=calendar)
        else:
            datemin = date_type(2000, 1, 1)
            datemax = date_type(2010, 1, 1)
        return munits.AxisInfo(majloc=majloc, majfmt=majfmt, label='',
                               default_limits=(datemin, datemax)) 

def test_360_day_calendar_list_CalendarDateTime(self):
        calendar = '360_day'
        unit = 'days since 2000-01-01'
        val = [CalendarDateTime(cftime.datetime(2014, 8, 12), calendar)]
        result = NetCDFTimeConverter().default_units(val, None)
        self.assertEqual(result, (calendar, unit, CalendarDateTime)) 

def average_time_bounds(ds):
    """Return the average of each set of time bounds in the Dataset.

    Useful for creating a new time array to replace the Dataset's native time
    array, in the case that the latter matches either the start or end bounds.
    This can cause errors in grouping (akin to an off-by-one error) if the
    timesteps span e.g. one full month each.  Note that the Dataset's times
    must not have already undergone "CF decoding", wherein they are converted
    from floats using the 'units' attribute into datetime objects.

    Parameters
    ----------
    ds : xarray.Dataset
        A Dataset containing a time bounds array with name matching
        internal_names.TIME_BOUNDS_STR.  This time bounds array must have two
        dimensions, one of which's coordinates is the Dataset's time array, and
        the other is length-2.

    Returns
    -------
    xarray.DataArray
        The mean of the start and end times of each timestep in the original
        Dataset.

    Raises
    ------
    ValueError
        If the time bounds array doesn't match the shape specified above.

    """
    bounds = ds[TIME_BOUNDS_STR]
    new_times = bounds.mean(dim=BOUNDS_STR, keep_attrs=True)
    new_times = new_times.drop_vars(TIME_STR).rename(TIME_STR)
    new_times[TIME_STR] = new_times
    return new_times 

def test_360_day_calendar_nd_CalendarDateTime(self):
        # Test the case where the input is an nd-array.
        calendar = '360_day'
        unit = 'days since 2000-01-01'
        val = np.array([[CalendarDateTime(cftime.datetime(2014, 8, 12),
                                          calendar)],
                       [CalendarDateTime(cftime.datetime(2014, 8, 13),
                                         calendar)]])
        result = NetCDFTimeConverter().default_units(val, None)
        self.assertEqual(result, (calendar, unit, CalendarDateTime)) 

def test_nonequal_calendars(self):
        # Test that different supplied calendars causes an error.
        calendar_1 = '360_day'
        calendar_2 = '365_day'
        unit = 'days since 2000-01-01'
        val = [CalendarDateTime(cftime.datetime(2014, 8, 12), calendar_1),
               CalendarDateTime(cftime.datetime(2014, 8, 13), calendar_2)]
        with assertRaisesRegex(self, ValueError, 'not all equal'):
            NetCDFTimeConverter().default_units(val, None) 

def test_cftime_np_array_CalendarDateTime(self):
        val = np.array([CalendarDateTime(cftime.datetime(2012, 6, 4),
                                         '360_day')], dtype=np.object)
        result = NetCDFTimeConverter().convert(val, None, None)
        self.assertEqual(result, np.array([4473.])) 

def test_non_cftime_datetime(self):
        val = CalendarDateTime(4, '360_day')
        msg = 'The datetime attribute of the CalendarDateTime object must ' \
              'be of type `cftime.datetime`.'
        with assertRaisesRegex(self, ValueError, msg):
            result = NetCDFTimeConverter().convert(val, None, None) 

def isfinite(val):
    """
    Helper function to determine if scalar or array value is finite extending
    np.isfinite with support for None, string, datetime types.
    """
    is_dask = is_dask_array(val)
    if not np.isscalar(val) and not is_dask:
        val = asarray(val, strict=False)

    if val is None:
        return False
    elif is_dask:
        import dask.array as da
        return da.isfinite(val)
    elif isinstance(val, np.ndarray):
        if val.dtype.kind == 'M':
            return ~isnat(val)
        elif val.dtype.kind == 'O':
            return np.array([isfinite(v) for v in val], dtype=bool)
        elif val.dtype.kind in 'US':
            return ~pd.isna(val) if pd else np.ones_like(val, dtype=bool)
        finite = np.isfinite(val)
        if pd and pandas_version >= '1.0.0':
            finite &= ~pd.isna(val)
        return finite
    elif isinstance(val, datetime_types+timedelta_types):
        return not isnat(val)
    elif isinstance(val, (basestring, bytes)):
        return True
    finite = np.isfinite(val)
    if pd and pandas_version >= '1.0.0':
        if finite is pd.NA:
            return False
        return finite & (~pd.isna(val))
    return finite 

def isdatetime(value):
    """
    Whether the array or scalar is recognized datetime type.
    """
    if isinstance(value, np.ndarray):
        return (value.dtype.kind == "M" or
                (value.dtype.kind == "O" and len(value) and
                 isinstance(value[0], datetime_types)))
    else:
        return isinstance(value, datetime_types) 

def unique_array(arr):
    """
    Returns an array of unique values in the input order.

    Args:
       arr (np.ndarray or list): The array to compute unique values on

    Returns:
       A new array of unique values
    """
    if not len(arr):
        return np.asarray(arr)
    elif pd:
        if isinstance(arr, np.ndarray) and arr.dtype.kind not in 'MO':
            # Avoid expensive unpacking if not potentially datetime
            return pd.unique(arr)

        values = []
        for v in arr:
            if (isinstance(v, datetime_types) and
                not isinstance(v, cftime_types)):
                v = pd.Timestamp(v).to_datetime64()
            values.append(v)
        return pd.unique(values)
    else:
        arr = np.asarray(arr)
        _, uniq_inds = np.unique(arr, return_index=True)
        return arr[np.sort(uniq_inds)] 

def dt64_to_dt(dt64):
    """
    Safely converts NumPy datetime64 to a datetime object.
    """
    ts = (dt64 - np.datetime64('1970-01-01T00:00:00')) / np.timedelta64(1, 's')
    return dt.datetime(1970,1,1,0,0,0) + dt.timedelta(seconds=ts) 

def dt_to_int(value, time_unit='us'):
    """
    Converts a datetime type to an integer with the supplied time unit.
    """
    if pd:
        if isinstance(value, pd.Period):
            value = value.to_timestamp()
        if isinstance(value, pd.Timestamp):
            try:
                value = value.to_datetime64()
            except:
                value = np.datetime64(value.to_pydatetime())
    elif isinstance(value, cftime_types):
        return cftime_to_timestamp(value, time_unit)

    if isinstance(value, dt.date):
        value = dt.datetime(*value.timetuple()[:6])

    # Handle datetime64 separately
    if isinstance(value, np.datetime64):
        try:
            value = np.datetime64(value, 'ns')
            tscale = (np.timedelta64(1, time_unit)/np.timedelta64(1, 'ns'))
            return value.tolist()/tscale
        except:
            # If it can't handle ns precision fall back to datetime
            value = value.tolist()

    if time_unit == 'ns':
        tscale = 1e9
    else:
        tscale = 1./np.timedelta64(1, time_unit).tolist().total_seconds()

    try:
        # Handle python3
        return int(value.timestamp() * tscale)
    except:
        # Handle python2
        return (time.mktime(value.timetuple()) + value.microsecond / 1e6) * tscale 

def get_calendar(arr: Union[xr.DataArray, xr.Dataset], dim: str = "time") -> str:
    """Return the calendar of the time coord of the DataArray

    Parameters
    ----------
    arr : Union[xr.DataArray, xr.Dataset]
      Array/dataset with a datetime coordinate. Values must either be of datetime64 dtype or have a dt.calendar attribute.
    dim : str
      Name of the coordinate to check.

    Raises
    ------
    ValueError
        If `arr` doesn't have a datetime64 or cftime dtype.

    Returns
    -------
    str
      The cftime calendar name or "default" when the data is using numpy's datetime type (numpy.datetime64.
    """
    if arr[dim].dtype == "O":  # Assume cftime, if it fails, not our fault
        non_na_item = arr[dim].where(arr[dim].notnull(), drop=True)[0].item()
        cal = non_na_item.calendar
    elif "datetime64" in arr[dim].dtype.name:
        cal = "default"
    else:
        raise ValueError(
            f"Cannot infer calendars from timeseries of type {arr[dim][0].dtype}"
        )
    return cal 

def datetime_to_decimal_year(
    times: xr.DataArray, calendar: Optional[str] = None
) -> xr.DataArray:
    """Convert a datetime xr.DataArray to decimal years according to its calendar or the given one.

    Decimal years are the number of years since 0001-01-01 00:00:00 AD.
    Ex: '2000-03-01 12:00' is 2000.1653 in a standard calendar, 2000.16301 in a "noleap" or 2000.16806 in a "360_day".
    """

    calendar = calendar or get_calendar(times)
    if calendar == "default":
        calendar = "standard"

    def _make_index(time):
        year = int(time.dt.year[0])
        doys = cftime.date2num(
            ensure_cftime_array(time), f"days since {year:04d}-01-01", calendar=calendar
        )
        return xr.DataArray(
            year + doys / days_in_year(year, calendar),
            dims=time.dims,
            coords=time.coords,
            name="time",
        )

    return times.groupby("time.year").map(_make_index) 

def cftime_start_time(date, freq):
    """
    Get the cftime.datetime for the start of a period. As we are not supplying
    actual period objects, assumptions regarding the period are made based on
    the given freq. IMPORTANT NOTE: this function cannot be used
    on greater-than-day freq that start at the beginning of a month, e.g.,
    'MS', 'QS', 'AS' -- this mirrors pandas behavior.

    Parameters
    __________
    datetime : cftime.datetime
        The original datetime object as a proxy representation for period.
    freq : str
        String specifying the frequency/offset such as 'MS', '2D', 'H', or '3T'

    Returns
    _______
    cftime.datetime
        The starting datetime of the period inferred from date and freq.
    """

    freq = to_offset(freq)
    if isinstance(freq, (YearBegin, QuarterBegin, MonthBegin)):
        raise ValueError("Invalid frequency: " + freq.rule_code())
    if isinstance(freq, YearEnd):
        month = freq.month
        return date - YearEnd(n=1, month=month) + pydt.timedelta(days=1)
    if isinstance(freq, QuarterEnd):
        month = freq.month
        return date - QuarterEnd(n=1, month=month) + pydt.timedelta(days=1)
    if isinstance(freq, MonthEnd):
        return date - MonthEnd(n=1) + pydt.timedelta(days=1)
    return date 

def test_axis_default_limits(self):
        cal = '360_day'
        unit = (cal, 'days since 2000-02-25 00:00:00', CalendarDateTime)
        result = NetCDFTimeConverter().axisinfo(unit, None)
        expected_dt = [cftime.datetime(2000, 1, 1),
                       cftime.datetime(2010, 1, 1)]
        np.testing.assert_array_equal(
            result.default_limits,
            [CalendarDateTime(edt, cal) for edt in expected_dt]) 

def apply_time_offset(time, years=0, months=0, days=0, hours=0):
    """Apply a specified offset to the given time array.

    This is useful for GFDL model output of instantaneous values.  For example,
    3 hourly data postprocessed to netCDF files spanning 1 year each will
    actually have time values that are offset by 3 hours, such that the first
    value is for 1 Jan 03:00 and the last value is 1 Jan 00:00 of the
    subsequent year.  This causes problems in xarray, e.g. when trying to group
    by month.  It is resolved by manually subtracting off those three hours,
    such that the dates span from 1 Jan 00:00 to 31 Dec 21:00 as desired.

    Parameters
    ----------
    time : xarray.DataArray representing a timeseries
    years, months, days, hours : int, optional
        The number of years, months, days, and hours, respectively, to offset
        the time array by.  Positive values move the times later.

    Returns
    -------
    pandas.DatetimeIndex

    Examples
    --------
    Case of a length-1 input time array:

    >>> times = xr.DataArray(datetime.datetime(1899, 12, 31, 21))
    >>> apply_time_offset(times)
    Timestamp('1900-01-01 00:00:00')

    Case of input time array with length greater than one:

    >>> times = xr.DataArray([datetime.datetime(1899, 12, 31, 21),
    ...                       datetime.datetime(1899, 1, 31, 21)])
    >>> apply_time_offset(times) # doctest: +NORMALIZE_WHITESPACE
    DatetimeIndex(['1900-01-01', '1899-02-01'], dtype='datetime64[ns]',
                  freq=None)
    """
    return (pd.to_datetime(time.values) +
            pd.DateOffset(years=years, months=months, days=days, hours=hours)) 

def get_time_decoded(self, midpoint=True):
        """Return time decoded.
        """
        # to compute a time midpoint, we need a time_bound variable
        if midpoint and self.time_bound is None:
            raise ValueError('cannot compute time midpoint w/o time bounds')

        if midpoint:
            time_data = self.time_bound.mean(self.tb_dim)

        else:
            # if time has already been decoded and there's no year_offset,
            # just return the time as is
            if self.isdecoded(self.time):
                if self.year_offset is None:
                    return self.time

                # if we need to un-decode time to apply the year_offset,
                time_data = self.get_time_undecoded()

            # time has not been decoded
            else:
                time_data = self.time

        if self.year_offset is not None:
            time_data += cftime.date2num(
                datetime(int(self.year_offset), 1, 1),
                units=self.time_attrs['units'],
                calendar=self.time_attrs['calendar'],
            )
        time_out = self.time.copy()
        time_out.data = xr.CFTimeIndex(
            cftime.num2date(
                time_data,
                units=self.time_attrs['units'],
                calendar=self.time_attrs['calendar'],
                only_use_cftime_datetimes=True,
            )
        )
        return time_out 

def time_year_to_midyeardate(self):
        """Set the time coordinate to the mid-point of the year.
        """
        ds = self._ds_time_computed.copy(True)
        ds[self.time_coord_name].data = np.array(
            [cftime.datetime(entry.year, 7, 2) for entry in ds[self.time_coord_name].data]
        )
        return ds 

def climatology(dset, freq, time_coord_name=None):
    """Compute climatologies for a specified time frequency

    Parameters
    ----------
    dset : xarray.Dataset
           The data on which to operate

    freq : str
        Frequency alias. Accepted alias:

        - ``mon``: for monthly climatologies

    time_coord_name : str
            Name for time coordinate to use


    Returns
    -------
    computed_dset : xarray.Dataset
                    The computed climatology data

    """

    accepted_freq = {'mon'}
    if freq not in accepted_freq:
        raise ValueError(f'{freq} is not among supported frequency aliases={accepted_freq}')

    else:
        ds = dset.esmlab.set_time(time_coord_name=time_coord_name).compute_mon_climatology()
        new_history = f'\n{datetime.now()} esmlab.climatology(<DATASET>, freq="{freq}")'
        ds.attrs['history'] = new_history
        return ds 

def anomaly(dset, clim_freq, slice_mon_clim_time=None, time_coord_name=None):
    """Compute anomalies for a specified time frequency

    Parameters
    ----------
    dset : xarray.Dataset
           The data on which to operate

    clim_freq : str
        Climatology frequency alias. Accepted alias:

        - ``mon``: for monthly climatologies

    slice_mon_clim_time : slice, optional
                          a slice object passed to
                          `dset.isel(time=slice_mon_clim_time)` for subseting
                          the time-period overwhich the climatology is computed
    time_coord_name : str
            Name for time coordinate to use


    Returns
    -------
    computed_dset : xarray.Dataset
                    The computed anomaly data

    """

    accepted_freq = {'mon'}
    if clim_freq not in accepted_freq:
        raise ValueError(f'{clim_freq} is not among supported frequency aliases={accepted_freq}')
    else:
        ds = dset.esmlab.set_time(time_coord_name=time_coord_name).compute_mon_anomaly(
            slice_mon_clim_time=slice_mon_clim_time
        )
        new_history = f'\n{datetime.now()} esmlab.anomaly(<DATASET>, clim_freq="{clim_freq}", slice_mon_clim_time="{slice_mon_clim_time}")'
        ds.attrs['history'] = new_history
        return ds 

def __init__(self, datetime, calendar):
        self.datetime = datetime
        self.calendar = calendar 

def __eq__(self, other):
        return (isinstance(other, self.__class__) and
                self.datetime == other.datetime and
                self.calendar == other.calendar)