Calendar Features

Calendar features.

mango_calendar.calendar_features.get_calendar(country: str = 'ES', start_year: int = 2010, end_year: int = 2027, communities: bool = False, weight_communities: dict | None = None, calendar_events: bool = False, return_weights: bool | None = None, return_distances: bool = False, distances_config: dict | None = None, name_transformations: bool = True, pivot: bool = False, pivot_keep_communities: bool = False) → pandas.DataFrame

Get a comprehensive calendar DataFrame with holiday information.

This function generates a pandas DataFrame containing holiday information for a specified country and date range. It can include national holidays, regional community holidays (for Spain), and custom calendar events like Black Friday. The function supports various transformations and output formats.

The resulting DataFrame contains the following columns:

  • date: Date of the holiday

  • name: Name of the holiday

  • country_code: Country code (ISO 3166-2)

  • community_code: Autonomous Community code (ISO 3166-2), only if communities=True

  • community_name: Name of the autonomous community, only if communities=True

  • weight: Weight of the holiday, only if return_weights=True

  • distance: Distance to holiday in days, only if return_distances=True

Parameters:

  • country (str) – Country code (ISO 3166-2) for which to retrieve holidays

  • start_year (int) – First year to include in the calendar

  • end_year (int) – Last year to include in the calendar (exclusive)

  • communities (bool) – Whether to include autonomous community holidays (Spain only)

  • weight_communities (dict | None) – Dictionary mapping community codes to their weights

  • calendar_events (bool) – Whether to add Black Friday to the calendar

  • return_weights (bool | None) – Whether to return holiday weights (auto-set if communities=True)

  • return_distances (bool) – Whether to return distance calculations to holidays

  • distances_config (dict | None) – Configuration for distance calculations with ‘steps_back’ and ‘steps_forward’

  • name_transformations (bool) – Whether to apply text transformations to holiday names

  • pivot (bool) – Whether to pivot the calendar to have columns for each holiday

  • pivot_keep_communities (bool) – Whether to keep community information when pivoting

Returns:

DataFrame containing calendar information with holidays and metadata

Return type:

pd.DataFrame

Raises:

  • ValueError – If start_year > end_year or invalid parameter combinations

  • UserWarning – If return_weights is requested without communities=True

Example:
>>> # Get basic Spanish calendar for 2023
>>> calendar = get_calendar(country="ES", start_year=2023, end_year=2024)
>>> print(calendar.columns.tolist())
['date', 'name', 'country_code']
>>>
>>> # Get calendar with community holidays and weights
>>> calendar_with_communities = get_calendar(
...     country="ES",
...     start_year=2023,
...     end_year=2024,
...     communities=True,
...     return_weights=True
... )
>>> print('weight' in calendar_with_communities.columns)
True

Date Utils

Utility functions for working with dates and calendars.

mango_calendar.date_utils.get_holidays_df(steps_back: int, steps_forward: int, start_year: int = 2014, country: str = 'ES', output_format: str = 'polars') → polars.DataFrame | pandas.DataFrame

Get national holidays DataFrame with distance window bounds.

This function retrieves holiday data for a specified country and creates a DataFrame with distance calculations around each holiday. It filters holidays by weight (>= 0.5), removes duplicates, and pivots the data to have each holiday as a separate column with distance values.

The resulting DataFrame contains:

  • datetime: Date column (as date type)

  • Holiday columns: Each holiday name becomes a column with distance values

Parameters:

  • steps_back (int) – Number of days to go back from each holiday date

  • steps_forward (int) – Number of days to go forward from each holiday date

  • start_year (int) – Starting year for the holiday calendar (default: 2014)

  • country (str) – ISO 3166-1 alpha-2 country code for holiday calendar (default: “ES”)

  • output_format (str) – Output format, either ‘polars’ or ‘pandas’ (default: “polars”)

Returns:

DataFrame with holidays as columns and distance values, in specified format

Return type:

Union[pl.DataFrame, pd.DataFrame]

Raises:

ValueError – If output_format is not ‘polars’ or ‘pandas’

Example:
>>> # Get Spanish holidays with 7-day window in Polars format
>>> holidays = get_holidays_df(
...     steps_back=7,
...     steps_forward=7,
...     start_year=2023,
...     country="ES",
...     output_format="polars"
... )
>>> print(holidays.columns)
['datetime', 'New Year', 'Epiphany', 'Good Friday', ...]
>>>
>>> # Get holidays in Pandas format
>>> holidays_pd = get_holidays_df(
...     steps_back=3,
...     steps_forward=3,
...     output_format="pandas"
... )
>>> print(type(holidays_pd))
<class 'pandas.core.frame.DataFrame'>
mango_calendar.date_utils.get_covid_lockdowns() → polars.DataFrame

Get COVID-19 lockdown period as a Polars DataFrame.

This function creates a DataFrame representing the COVID-19 lockdown period from March 1, 2020 to March 1, 2022. The DataFrame contains daily records with the lockdown name and boundary values set to 0.

The resulting DataFrame contains:

  • ds: Date column (datetime with nanosecond precision)

  • name: Lockdown identifier (“COVID”)

  • lower_bound: Lower boundary value (0)

  • upper_bound: Upper boundary value (0)

Returns:

Polars DataFrame with COVID lockdown period data

Return type:

pl.DataFrame

Example:
>>> covid_data = get_covid_lockdowns()
>>> print(covid_data.shape)
(730, 4)
>>> print(covid_data.columns)
['ds', 'name', 'lower_bound', 'upper_bound']
>>> print(covid_data['name'].unique())
['COVID']
>>> # Check date range
>>> print(covid_data['ds'].min())
2020-03-01 00:00:00
>>> print(covid_data['ds'].max())
2022-02-28 00:00:00