[Feature]: custom seasons that span calendar years

[arfriedman]

Is your feature request related to a problem?

Following #393, it seems that it would be useful to expand custom seasons functionality across calendar years. Examples include: taking the water year from October to September, or taking a boreal winter average from December to March.

Describe the solution you'd like

I envision the main change would be so that the order of months listed in custom seasons does matter, and could span across calendar years.

For example, this configuation would create Apr-Nov and Dec-March averages, the latter which extends into the following year:

custom_seasons = [
    ["Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov"],
    ["Dec", "Jan", "Feb", "Mar"],
]

Associated with this change I think it would also make sense to generalize the season_config parameters beyond the existing options for DJF, e.g. the flag “drop_incomplete_djf” could become something like "drop_incomplete_season." In addition to seasons that cross the calendar year, this could apply to datasets that end in the middle of a season (for example, the last Apr-June season for a dataset that ends in May).

Describe alternatives you've considered

No response

Additional context

As a possible aside, I was also wondering if it is necessary to keep the requirement to include all 12 months in the custom_seasons list. I imagine that often users are only interested in one season.

[DamienIrving]

👍 to this request.

I have an analysis right now where I'm interested in a (southern hemisphere) growing season NDJFM.

Ideally I'd like to run the following:

ds.temporal.group_average(
    'pr',
    freq='season',
    season_config={
        'dec_mode': 'DJF',
        'drop_incomplete_djf': True,
        'custom_seasons': ['Nov', 'Dec', 'Jan', 'Feb', 'Mar']
    }    
)

Assuming my input dataset ds starts in January 1985, I'd like the first year not to be included because it would be incomplete with only Jan '85, Feb '85, Mar '85 available but not the required Nov '84 and Dec '84 to make a complete NDJFM season. I also have no interest in the rest of the year so custom_seasons would not include all 12 months.

[tomvothecoder]

Thank you for opening this issue @arfriedman! Also thank you @DamienIrving for your input! This feature enhancement definitely sounds useful.

Here are the set of improvements based on the feedback:

1. Support custom seasons that span calendar years
   • Requires detecting order of the months in a season. Currently, order does not matter.
   • For example, for custom_season = ["Nov", "Dec", "Jan", "Feb", "Mar"]:
     • ["Nov", "Dec"] are from the previous year since they are listed before "Jan"
     • ["Jan", "Feb", "Mar"] are from the current year
   • We can potentially extend _shift_decembers() to shift other months too. This method shifts the previous year December to the current year so xarray can properly group "DJF" seasons spanning calendar years.
2. Detect and drop incomplete seasons
   • Right now xCDAT only detects incomplete "DJF" seasons with _drop_incomplete_djf()
   • Replace boolean config drop_incomplete_djf with drop_incomplete_season
   • A possible solution for detecting incomplete seasons is to check if a season has all of the required months. If the count of months for that season does not match the expected count, then drop that season.
3. Remove requirement for all 12 months to be included in a custom season