Class SeasonResampler

xarray/groupers.py:874–1109

Allows grouping using a custom definition of seasons. Parameters ---------- seasons: Sequence[str] An ordered list of seasons. drop_incomplete: bool Whether to drop seasons that are not completely included in the data. For example, if a time series starts in

@dataclass
class SeasonResampler(Resampler):
    """Allows grouping using a custom definition of seasons.

    Parameters
    ----------
    seasons: Sequence[str]
        An ordered list of seasons.
    drop_incomplete: bool
        Whether to drop seasons that are not completely included in the data.
        For example, if a time series starts in Jan-2001, and seasons includes `"DJF"`
        then observations from Jan-2001, and Feb-2001 are ignored in the grouping
        since Dec-2000 isn't present.

    Examples
    --------
    >>> SeasonResampler(["JF", "MAM", "JJAS", "OND"])
    SeasonResampler(seasons=['JF', 'MAM', 'JJAS', 'OND'], drop_incomplete=True)

    >>> SeasonResampler(["DJFM", "AM", "JJA", "SON"])
    SeasonResampler(seasons=['DJFM', 'AM', 'JJA', 'SON'], drop_incomplete=True)
    """

    seasons: Sequence[str]
    drop_incomplete: bool = field(default=True, kw_only=True)
    season_inds: Sequence[Sequence[int]] = field(init=False, repr=False)
    season_tuples: Mapping[str, Sequence[int]] = field(init=False, repr=False)

    def __post_init__(self):
        self.season_inds = season_to_month_tuple(self.seasons)
        all_inds = functools.reduce(operator.add, self.season_inds)
        if len(all_inds) > len(set(all_inds)):
            raise ValueError(
                f"Overlapping seasons are not allowed. Received {self.seasons!r}"
            )
        self.season_tuples = dict(zip(self.seasons, self.season_inds, strict=True))

        if not is_sorted_periodic(list(itertools.chain(*self.season_inds))):
            raise ValueError(
                "Resampling is only supported with sorted seasons. "
                f"Provided seasons {self.seasons!r} are not sorted."
            )

    def factorize(self, group: T_Group) -> EncodedGroups:
        if group.ndim != 1:
            raise ValueError(
                "SeasonResampler can only be used to resample by 1D arrays."
            )
        if not isinstance(group, DataArray) or not _contains_datetime_like_objects(
            group.variable
        ):
            raise ValueError(
                "SeasonResampler can only be used to group by datetime-like DataArrays."
            )

        seasons = self.seasons
        season_inds = self.season_inds
        season_tuples = self.season_tuples