openseries 1.8.2__py3-none-any.whl → 1.8.4__py3-none-any.whl

openseries/_common_model.py

@@ -33,6 +33,10 @@ if TYPE_CHECKING:  # pragma: no cover
         LiteralLinePlotMode,
         LiteralNanMethod,
         LiteralPandasReindexMethod,
+        LiteralPlotlyHistogramBarMode,
+        LiteralPlotlyHistogramCurveType,
+        LiteralPlotlyHistogramHistNorm,
+        LiteralPlotlyHistogramPlotType,
         LiteralPlotlyJSlib,
         LiteralPlotlyOutput,
         LiteralQuantileInterp,
@@ -50,10 +54,11 @@ from pandas import (
     to_datetime,
 )
 from pandas.tseries.offsets import CustomBusinessDay
+from plotly.figure_factory import create_distplot  # type: ignore[import-untyped]
 from plotly.graph_objs import Figure  # type: ignore[import-untyped]
 from plotly.io import to_html  # type: ignore[import-untyped]
 from plotly.offline import plot  # type: ignore[import-untyped]
-from pydantic import BaseModel, ConfigDict, DirectoryPath
+from pydantic import BaseModel, ConfigDict, DirectoryPath, ValidationError
 from scipy.stats import (  # type: ignore[import-untyped]
     kurtosis,
     norm,
@@ -372,13 +377,23 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         """
         method: LiteralPandasReindexMethod = "nearest"
-        countries = "SE"
+
+        try:
+            countries = self.countries
+            markets = self.markets
+        except AttributeError:
+            countries = self.constituents[0].countries
+            markets = self.constituents[0].markets
+
         wmdf = self.tsdf.copy()
+
         dates = _do_resample_to_business_period_ends(
             data=wmdf,
             freq="BME",
             countries=countries,
+            markets=markets,
         )
+
         wmdf = wmdf.reindex(index=[deyt.date() for deyt in dates], method=method)
         wmdf.index = DatetimeIndex(wmdf.index)
         result = wmdf.ffill().pct_change().min()
@@ -534,14 +549,20 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
     def align_index_to_local_cdays(
         self: Self,
-        countries: CountriesType = "SE",
+        countries: CountriesType | None = None,
+        markets: list[str] | str | None = None,
+        custom_holidays: list[str] | str | None = None,
     ) -> Self:
         """Align the index of .tsdf with local calendar business days.
 
         Parameters
         ----------
-        countries: CountriesType, default: "SE"
+        countries: CountriesType, optional
             (List of) country code(s) according to ISO 3166-1 alpha-2
+        markets: list[str] | str, optional
+            (List of) markets code(s) according to pandas-market-calendars
+        custom_holidays: list[str] | str, optional
+            Argument where missing holidays can be added
 
         Returns:
         -------
@@ -551,10 +572,37 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
         """
         startyear = cast("int", to_datetime(self.tsdf.index[0]).year)
         endyear = cast("int", to_datetime(self.tsdf.index[-1]).year)
+
+        if countries:
+            try:
+                self.countries = countries
+            except ValidationError:
+                for serie in self.constituents:
+                    serie.countries = countries
+        else:
+            try:
+                countries = self.countries
+            except AttributeError:
+                countries = self.constituents[0].countries
+
+        if markets:
+            try:
+                self.markets = markets
+            except ValidationError:
+                for serie in self.constituents:
+                    serie.markets = markets
+        else:
+            try:
+                markets = self.markets
+            except AttributeError:
+                markets = self.constituents[0].markets
+
         calendar = holiday_calendar(
             startyear=startyear,
             endyear=endyear,
             countries=countries,
+            markets=markets,
+            custom_holidays=custom_holidays,
         )
 
         d_range = [
@@ -1005,6 +1053,174 @@ class _CommonModel(BaseModel):  # type: ignore[misc]
 
         return figure, string_output
 
+    def plot_histogram(
+        self: Self,
+        plot_type: LiteralPlotlyHistogramPlotType = "bars",
+        histnorm: LiteralPlotlyHistogramHistNorm = "percent",
+        barmode: LiteralPlotlyHistogramBarMode = "overlay",
+        xbins_size: float | None = None,
+        opacity: float = 0.75,
+        bargap: float = 0.0,
+        bargroupgap: float = 0.0,
+        curve_type: LiteralPlotlyHistogramCurveType = "kde",
+        x_fmt: str | None = None,
+        y_fmt: str | None = None,
+        filename: str | None = None,
+        directory: DirectoryPath | None = None,
+        labels: list[str] | None = None,
+        output_type: LiteralPlotlyOutput = "file",
+        include_plotlyjs: LiteralPlotlyJSlib = "cdn",
+        *,
+        cumulative: bool = False,
+        show_rug: bool = False,
+        auto_open: bool = True,
+        add_logo: bool = True,
+    ) -> tuple[Figure, str]:
+        """Create a Plotly Histogram Figure.
+
+        Parameters
+        ----------
+        plot_type: LiteralPlotlyHistogramPlotType, default: bars
+            Type of plot
+        histnorm: LiteralPlotlyHistogramHistNorm, default: percent
+            Sets the normalization mode
+        barmode: LiteralPlotlyHistogramBarMode, default: overlay
+            Specifies how bar traces are displayed relative to one another
+        xbins_size: float, optional
+            Explicitly sets the width of each bin along the x-axis in data units
+        opacity: float, default: 0.75
+            Sets the trace opacity, must be between 0 (fully transparent) and 1
+        bargap: float, default: 0.0
+            Sets the gap between bars of adjacent location coordinates
+        bargroupgap: float, default: 0.0
+            Sets the gap between bar “groups” at the same location coordinate
+        curve_type: LiteralPlotlyHistogramCurveType, default: kde
+            Specifies the type of distribution curve to overlay on the histogram
+        y_fmt: str, optional
+            None, '%', '.1%' depending on number of decimals to show on the y-axis
+        x_fmt: str, optional
+            None, '%', '.1%' depending on number of decimals to show on the x-axis
+        filename: str, optional
+            Name of the Plotly html file
+        directory: DirectoryPath, optional
+            Directory where Plotly html file is saved
+        labels: list[str], optional
+            A list of labels to manually override using the names of
+            the input self.tsdf
+        output_type: LiteralPlotlyOutput, default: "file"
+            Determines output type
+        include_plotlyjs: LiteralPlotlyJSlib, default: "cdn"
+            Determines how the plotly.js library is included in the output
+        cumulative: bool, default: False
+            Determines whether to compute a cumulative histogram
+        show_rug: bool, default: False
+            Determines whether to draw a rug plot alongside the distribution
+        auto_open: bool, default: True
+            Determines whether to open a browser window with the plot
+        add_logo: bool, default: True
+            If True a Captor logo is added to the plot
+
+        Returns:
+        -------
+        tuple[plotly.go.Figure, str]
+            Plotly Figure and a div section or a html filename with location
+
+        """
+        if labels:
+            if len(labels) != self.tsdf.shape[1]:
+                msg = "Must provide same number of labels as items in frame."
+                raise NumberOfItemsAndLabelsNotSameError(msg)
+        else:
+            labels = list(self.tsdf.columns.get_level_values(0))
+
+        if directory:
+            dirpath = Path(directory).resolve()
+        elif Path.home().joinpath("Documents").exists():
+            dirpath = Path.home().joinpath("Documents")
+        else:
+            dirpath = Path(stack()[1].filename).parent
+
+        if not filename:
+            filename = "".join(choice(ascii_letters) for _ in range(6)) + ".html"
+        plotfile = dirpath.joinpath(filename)
+
+        fig_dict, logo = load_plotly_dict()
+
+        hovertemplate = f"Count: %{{y:{y_fmt}}}" if y_fmt else "Count: %{y}"
+
+        if x_fmt:
+            hovertemplate += f"<br>%{{x:{x_fmt}}}"
+        else:
+            hovertemplate += "<br>%{x}"
+
+        msg = "plot_type must be 'bars' or 'lines'."
+        if plot_type == "bars":
+            figure = Figure(fig_dict)
+            for item in range(self.tsdf.shape[1]):
+                figure.add_histogram(
+                    x=self.tsdf.iloc[:, item],
+                    cumulative={"enabled": cumulative},
+                    histnorm=histnorm,
+                    name=labels[item],
+                    xbins={"size": xbins_size},
+                    opacity=opacity,
+                    hovertemplate=hovertemplate,
+                )
+            figure.update_layout(
+                barmode=barmode,
+                bargap=bargap,
+                bargroupgap=bargroupgap,
+            )
+        elif plot_type == "lines":
+            hist_data = [
+                cast("Series[float]", self.tsdf.loc[:, ds]).dropna().tolist()
+                for ds in self.tsdf
+            ]
+            figure = create_distplot(
+                hist_data=hist_data,
+                curve_type=curve_type,
+                group_labels=labels,
+                show_hist=False,
+                show_rug=show_rug,
+                histnorm=histnorm,
+            )
+            figure.update_layout(dict1=fig_dict["layout"])
+        else:
+            raise TypeError(msg)
+
+        figure.update_layout(xaxis={"tickformat": x_fmt}, yaxis={"tickformat": y_fmt})
+
+        figure.update_xaxes(zeroline=True, zerolinewidth=2, zerolinecolor="lightgrey")
+        figure.update_yaxes(zeroline=True, zerolinewidth=2, zerolinecolor="lightgrey")
+
+        if add_logo:
+            figure.add_layout_image(logo)
+
+        if output_type == "file":
+            plot(
+                figure_or_data=figure,
+                filename=str(plotfile),
+                auto_open=auto_open,
+                auto_play=False,
+                link_text="",
+                include_plotlyjs=cast("bool", include_plotlyjs),
+                config=fig_dict["config"],
+                output_type=output_type,
+            )
+            string_output = str(plotfile)
+        else:
+            div_id = filename.rsplit(".", 1)[0]
+            string_output = to_html(
+                fig=figure,
+                config=fig_dict["config"],
+                auto_play=False,
+                include_plotlyjs=cast("bool", include_plotlyjs),
+                full_html=False,
+                div_id=div_id,
+            )
+
+        return figure, string_output
+
     def arithmetic_ret_func(
         self: Self,
         months_from_last: int | None = None,

openseries/datefixer.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import datetime as dt
 from typing import TYPE_CHECKING, cast
 
+import pandas_market_calendars as mcal
 from dateutil.relativedelta import relativedelta
 from holidays import (
     country_holidays,
@@ -24,6 +25,7 @@ from pandas.tseries.offsets import CustomBusinessDay
 from .owntypes import (
     BothStartAndEndError,
     CountriesNotStringNorListStrError,
+    MarketsNotStringNorListStrError,
     TradingDaysNotAboveZeroError,
 )
 
@@ -31,7 +33,6 @@ if TYPE_CHECKING:
     from .owntypes import (  # pragma: no cover
         CountriesType,
         DateType,
-        HolidayType,
         LiteralBizDayFreq,
     )
 
@@ -45,11 +46,59 @@ __all__ = [
 ]
 
 
+def market_holidays(
+    startyear: int,
+    endyear: int,
+    markets: str | list[str],
+) -> list[str]:
+    """Return a dict of holiday dates mapping to list of markets closed.
+
+    Parameters
+    ----------
+    startyear: int
+        First year (inclusive) to consider.
+    endyear: int
+        Last year (inclusive) to consider.
+    markets: str | list[str]
+        String or list of market codes supported by pandas_market_calendars.
+
+    Returns:
+    -------
+    list[str]
+        list of holiday dates.
+    """
+    market_list = [markets] if isinstance(markets, str) else list(markets)
+
+    supported = mcal.get_calendar_names()
+
+    if not all(m in supported for m in market_list):
+        msg = (
+            "Argument markets must be a string market code or a list of market "
+            "codes supported by pandas_market_calendars."
+        )
+        raise MarketsNotStringNorListStrError(msg)
+
+    holidays: list[str] = []
+    for m in market_list:
+        cal = mcal.get_calendar(m)
+        # noinspection PyUnresolvedReferences
+        cal_hols = cal.holidays().calendar.holidays
+        my_hols: list[str] = [
+            str(date)
+            for date in cal_hols
+            if (startyear <= int(str(date)[:4]) <= endyear)
+        ]
+        holidays.extend(my_hols)
+
+    return list(set(holidays))
+
+
 def holiday_calendar(
     startyear: int,
     endyear: int,
     countries: CountriesType = "SE",
-    custom_holidays: HolidayType | None = None,
+    markets: list[str] | str | None = None,
+    custom_holidays: list[str] | str | None = None,
 ) -> busdaycalendar:
     """Generate a business calendar.
 
@@ -61,9 +110,10 @@ def holiday_calendar(
         Last year in date range generated
     countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
-    custom_holidays: HolidayType, optional
-        Argument where missing holidays can be added as
-        {"2021-02-12": "Jack's birthday"} or ["2021-02-12"]
+    markets: list[str] | str, optional
+        (List of) markets code(s) according to pandas-market-calendars
+    custom_holidays: list[str] | str, optional
+        Argument where missing holidays can be added
 
     Returns:
     -------
@@ -79,20 +129,16 @@ def holiday_calendar(
 
     if isinstance(countries, str) and countries in list_supported_countries():
         staging = country_holidays(country=countries, years=years)
-        if custom_holidays is not None:
-            staging.update(custom_holidays)
-        hols = array(sorted(staging.keys()), dtype="datetime64[D]")
-    elif isinstance(countries, list) and all(
+        hols = list(staging.keys())
+    elif isinstance(countries, (list, set)) and all(
         country in list_supported_countries() for country in countries
     ):
         country: str
         countryholidays: list[dt.date | str] = []
-        for i, country in enumerate(countries):
+        for country in countries:
             staging = country_holidays(country=country, years=years)
-            if i == 0 and custom_holidays is not None:
-                staging.update(custom_holidays)
             countryholidays += list(staging)
-        hols = array(sorted(set(countryholidays)), dtype="datetime64[D]")
+        hols = list(countryholidays)
     else:
         msg = (
             "Argument countries must be a string country code or "
@@ -100,7 +146,22 @@ def holiday_calendar(
         )
         raise CountriesNotStringNorListStrError(msg)
 
-    return busdaycalendar(holidays=hols)
+    if markets:
+        market_hols = market_holidays(
+            startyear=startyear, endyear=endyear, markets=markets
+        )
+        dt_mkt_hols = [date_fix(fixerdate=ddate) for ddate in market_hols]
+        hols.extend(dt_mkt_hols)
+
+    if custom_holidays:
+        custom_list = (
+            [custom_holidays]
+            if isinstance(custom_holidays, str)
+            else list(custom_holidays)  # type: ignore[arg-type]
+        )
+        hols.extend([date_fix(fixerdate=ddate) for ddate in custom_list])
+
+    return busdaycalendar(holidays=array(sorted(set(hols)), dtype="datetime64[D]"))
 
 
 def date_fix(
@@ -137,7 +198,8 @@ def date_offset_foll(
     raw_date: DateType,
     months_offset: int = 12,
     countries: CountriesType = "SE",
-    custom_holidays: HolidayType | None = None,
+    markets: list[str] | str | None = None,
+    custom_holidays: list[str] | str | None = None,
     *,
     adjust: bool = False,
     following: bool = True,
@@ -152,9 +214,10 @@ def date_offset_foll(
         Number of months as integer
     countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
-    custom_holidays: HolidayType, optional
-        Argument where missing holidays can be added as
-        {"2021-02-12": "Jack's birthday"} or ["2021-02-12"]
+    markets: list[str] | str, optional
+        (List of) markets code(s) according to pandas-market-calendars
+    custom_holidays: list[str] | str, optional
+        Argument where missing holidays can be added
     adjust: bool, default: False
         Determines if offset should adjust for business days
     following: bool, default: True
@@ -180,6 +243,7 @@ def date_offset_foll(
             startyear=startyear,
             endyear=endyear,
             countries=countries,
+            markets=markets,
             custom_holidays=custom_holidays,
         )
         while not is_busday(dates=new_date, busdaycal=calendar):
@@ -191,7 +255,8 @@ def date_offset_foll(
 def get_previous_business_day_before_today(
     today: dt.date | None = None,
     countries: CountriesType = "SE",
-    custom_holidays: HolidayType | None = None,
+    markets: list[str] | str | None = None,
+    custom_holidays: list[str] | str | None = None,
 ) -> dt.date:
     """Bump date backwards to find the previous business day.
 
@@ -201,9 +266,10 @@ def get_previous_business_day_before_today(
         Manual input of the day from where the previous business day is found
     countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
-    custom_holidays: HolidayType, optional
-        Argument where missing holidays can be added as
-        {"2021-02-12": "Jack's birthday"} or ["2021-02-12"]
+    markets: list[str] | str, optional
+        (List of) markets code(s) according to pandas-market-calendars
+    custom_holidays: list[str] | str, optional
+        Argument where missing holidays can be added
 
     Returns:
     -------
@@ -215,10 +281,11 @@ def get_previous_business_day_before_today(
         today = dt.datetime.now().astimezone().date()
 
     return date_offset_foll(
-        today - dt.timedelta(days=1),
+        raw_date=today - dt.timedelta(days=1),
+        months_offset=0,
         countries=countries,
+        markets=markets,
         custom_holidays=custom_holidays,
-        months_offset=0,
         adjust=True,
         following=False,
     )
@@ -228,7 +295,8 @@ def offset_business_days(
     ddate: dt.date,
     days: int,
     countries: CountriesType = "SE",
-    custom_holidays: HolidayType | None = None,
+    markets: list[str] | str | None = None,
+    custom_holidays: list[str] | str | None = None,
 ) -> dt.date:
     """Bump date by business days.
 
@@ -244,9 +312,10 @@ def offset_business_days(
         If days is set as anything other than an integer its value is set to zero
     countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
-    custom_holidays: HolidayType, optional
-        Argument where missing holidays can be added as
-        {"2021-02-12": "Jack's birthday"} or ["2021-02-12"]
+    markets: list[str] | str, optional
+        (List of) markets code(s) according to pandas-market-calendars
+    custom_holidays: list[str] | str, optional
+        Argument where missing holidays can be added
 
     Returns:
     -------
@@ -266,6 +335,7 @@ def offset_business_days(
             startyear=ndate.year,
             endyear=ddate.year,
             countries=countries,
+            markets=markets,
             custom_holidays=custom_holidays,
         )
         local_bdays: list[dt.date] = [
@@ -283,6 +353,7 @@ def offset_business_days(
             startyear=ddate.year,
             endyear=ndate.year,
             countries=countries,
+            markets=markets,
             custom_holidays=custom_holidays,
         )
         local_bdays = [
@@ -310,6 +381,8 @@ def generate_calendar_date_range(
     start: dt.date | None = None,
     end: dt.date | None = None,
     countries: CountriesType = "SE",
+    markets: list[str] | str | None = None,
+    custom_holidays: list[str] | str | None = None,
 ) -> list[dt.date]:
     """Generate a list of business day calendar dates.
 
@@ -323,6 +396,10 @@ def generate_calendar_date_range(
         Date when the range ends
     countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
+    markets: list[str] | str, optional
+        (List of) markets code(s) according to pandas-market-calendars
+    custom_holidays: list[str] | str, optional
+        Argument where missing holidays can be added
 
     Returns:
     -------
@@ -344,6 +421,8 @@ def generate_calendar_date_range(
             startyear=start.year,
             endyear=date_fix(tmp_range.tolist()[-1]).year,
             countries=countries,
+            markets=markets,
+            custom_holidays=custom_holidays,
         )
         return [
             d.date()
@@ -360,6 +439,8 @@ def generate_calendar_date_range(
             startyear=date_fix(tmp_range.tolist()[0]).year,
             endyear=end.year,
             countries=countries,
+            markets=markets,
+            custom_holidays=custom_holidays,
         )
         return [
             d.date()
@@ -381,6 +462,8 @@ def _do_resample_to_business_period_ends(
     data: DataFrame,
     freq: LiteralBizDayFreq,
     countries: CountriesType,
+    markets: list[str] | str | None = None,
+    custom_holidays: list[str] | str | None = None,
 ) -> DatetimeIndex:
     """Resample timeseries frequency to business calendar month end dates.
 
@@ -394,7 +477,10 @@ def _do_resample_to_business_period_ends(
         The date offset string that sets the resampled frequency
     countries: CountriesType
         (List of) country code(s) according to ISO 3166-1 alpha-2
-        to create a business day calendar used for date adjustments
+    markets: list[str] | str, optional
+        (List of) markets code(s) according to pandas-market-calendars
+    custom_holidays: list[str] | str, optional
+        Argument where missing holidays can be added
 
     Returns:
     -------
@@ -413,12 +499,14 @@ def _do_resample_to_business_period_ends(
     dates = DatetimeIndex(
         [copydata.index[0]]
         + [
-            date_offset_foll(
-                dt.date(d.year, d.month, 1)
+            date_offset_foll(  # type: ignore[misc]
+                raw_date=dt.date(d.year, d.month, 1)
                 + relativedelta(months=1)
                 - dt.timedelta(days=1),
-                countries=countries,
                 months_offset=0,
+                countries=countries,
+                markets=markets,
+                custom_holidays=custom_holidays,
                 adjust=True,
                 following=False,
             )

openseries/frame.py

@@ -41,7 +41,6 @@ from pydantic import field_validator
 from ._common_model import _CommonModel
 from .datefixer import _do_resample_to_business_period_ends
 from .owntypes import (
-    CountriesType,
     DaysInYearType,
     LabelsNotUniqueError,
     LiteralBizDayFreq,
@@ -429,7 +428,6 @@ class OpenFrame(_CommonModel):
     def resample_to_business_period_ends(
         self: Self,
         freq: LiteralBizDayFreq = "BME",
-        countries: CountriesType = "SE",
         method: LiteralPandasReindexMethod = "nearest",
     ) -> Self:
         """Resamples timeseries frequency to the business calendar month end dates.
@@ -440,9 +438,6 @@ class OpenFrame(_CommonModel):
         ----------
         freq: LiteralBizDayFreq, default "BME"
             The date offset string that sets the resampled frequency
-        countries: CountriesType, default: "SE"
-            (List of) country code(s) according to ISO 3166-1 alpha-2
-            to create a business day calendar used for date adjustments
         method: LiteralPandasReindexMethod, default: nearest
             Controls the method used to align values across columns
 
@@ -456,7 +451,8 @@ class OpenFrame(_CommonModel):
             dates = _do_resample_to_business_period_ends(
                 data=xerie.tsdf,
                 freq=freq,
-                countries=countries,
+                countries=xerie.countries,
+                markets=xerie.markets,
             )
             xerie.tsdf = xerie.tsdf.reindex(
                 [deyt.date() for deyt in dates],

openseries/owntypes.py

@@ -86,16 +86,6 @@ DaysInYearType = Annotated[int, Field(strict=True, ge=1, le=366)]
 
 DateType = str | dt.date | dt.datetime | datetime64 | Timestamp
 
-HolidayType = (
-    dict[dt.date | dt.datetime | str | float | int, str]
-    | list[dt.date | dt.datetime | str | float | int]
-    | dt.date
-    | dt.datetime
-    | str
-    | float
-    | int
-)
-
 PlotlyLayoutType = dict[
     str,
     str
@@ -135,6 +125,15 @@ LiteralCaptureRatio = Literal["up", "down", "both"]
 LiteralBarPlotMode = Literal["stack", "group", "overlay", "relative"]
 LiteralPlotlyOutput = Literal["file", "div"]
 LiteralPlotlyJSlib = Literal[True, False, "cdn"]
+LiteralPlotlyHistogramPlotType = Literal["bars", "lines"]
+LiteralPlotlyHistogramBarMode = Literal["stack", "group", "overlay", "relative"]
+LiteralPlotlyHistogramCurveType = Literal["normal", "kde"]
+LiteralPlotlyHistogramHistNorm = Literal[
+    "percent",
+    "probability",
+    "density",
+    "probability density",
+]
 LiteralOlsFitMethod = Literal["pinv", "qr"]
 LiteralPortfolioWeightings = Literal["eq_weights", "inv_vol"]
 LiteralOlsFitCovType = Literal[
@@ -347,6 +346,10 @@ class CountriesNotStringNorListStrError(Exception):
     """Raised when countries argument is not provided in correct format."""
 
 
+class MarketsNotStringNorListStrError(Exception):
+    """Raised when markets argument is not provided in correct format."""
+
+
 class TradingDaysNotAboveZeroError(Exception):
     """Raised when trading days argument is not above zero."""
 

openseries/plotly_layouts.json

@@ -43,7 +43,7 @@
       "size": 14
     },
     "legend": {
-      "bgcolor": "rgba(255,255,255,1)",
+      "bgcolor": "rgba(0,0,0,0)",
       "orientation": "h",
       "x": 0.98,
       "xanchor": "right",

openseries/series.py

@@ -45,6 +45,7 @@ from .owntypes import (
     LiteralBizDayFreq,
     LiteralPandasReindexMethod,
     LiteralSeriesProps,
+    MarketsNotStringNorListStrError,
     OpenTimeSeriesPropertiesList,
     Self,
     ValueListType,
@@ -91,6 +92,8 @@ class OpenTimeSeries(_CommonModel):
         ISO 4217 currency code of the user's home currency
     countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
+    markets: list[str] | str, optional
+        (List of) markets code(s) according to pandas-market-calendars
     isin : str, optional
         ISO 6166 identifier code of the associated instrument
     label : str, optional
@@ -109,6 +112,7 @@ class OpenTimeSeries(_CommonModel):
     currency: CurrencyStringType
     domestic: CurrencyStringType = "SEK"
     countries: CountriesType = "SE"
+    markets: list[str] | str | None = None  # type: ignore[assignment]
     isin: str | None = None
     label: str | None = None
 
@@ -126,6 +130,25 @@ class OpenTimeSeries(_CommonModel):
         _ = Countries(countryinput=value)
         return value
 
+    @field_validator("markets", mode="before")  # type: ignore[misc]
+    @classmethod
+    def _validate_markets(
+        cls, value: list[str] | str | None
+    ) -> list[str] | str | None:
+        """Pydantic validator to ensure markets field is validated."""
+        msg = (
+            "'markets' must be a string or list of strings, "
+            f"got {type(value).__name__!r}"
+        )
+        if value is None or isinstance(value, str):
+            return value
+        if isinstance(value, list):
+            if all(isinstance(item, str) for item in value) and len(value) != 0:
+                return value
+            item_msg = "All items in 'markets' must be strings."
+            raise MarketsNotStringNorListStrError(item_msg)
+        raise MarketsNotStringNorListStrError(msg)
+
     @model_validator(mode="after")  # type: ignore[misc,unused-ignore]
     def _dates_and_values_validate(self: Self) -> Self:
         """Pydantic validator to ensure dates and values are validated."""
@@ -587,6 +610,7 @@ class OpenTimeSeries(_CommonModel):
             data=self.tsdf,
             freq=freq,
             countries=self.countries,
+            markets=self.markets,
         )
         self.tsdf = self.tsdf.reindex([deyt.date() for deyt in dates], method=method)
         return self

openseries/simulation.py

@@ -417,6 +417,7 @@ class ReturnSimulation(BaseModel):  # type: ignore[misc]
         start: dt.date | None = None,
         end: dt.date | None = None,
         countries: CountriesType = "SE",
+        markets: list[str] | str | None = None,
     ) -> DataFrame:
         """Create a pandas.DataFrame from simulation(s).
 
@@ -430,6 +431,8 @@ class ReturnSimulation(BaseModel):  # type: ignore[misc]
             Date when the simulation ends
         countries: CountriesType, default: "SE"
             (List of) country code(s) according to ISO 3166-1 alpha-2
+        markets: list[str] | str, optional
+            (List of) markets code(s) according to pandas-market-calendars
 
         Returns:
         -------
@@ -442,6 +445,7 @@ class ReturnSimulation(BaseModel):  # type: ignore[misc]
             start=start,
             end=end,
             countries=countries,
+            markets=markets,
         )
 
         if self.number_of_sims == 1:

{openseries-1.8.2.dist-info → openseries-1.8.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: openseries
-Version: 1.8.2
+Version: 1.8.4
 Summary: Tools for analyzing financial timeseries.
 License: # BSD 3-Clause License
          
@@ -50,6 +50,7 @@ Requires-Dist: holidays (>=0.30,<1.0)
 Requires-Dist: numpy (>=1.23.2,<3.0.0)
 Requires-Dist: openpyxl (>=3.1.2,<5.0.0)
 Requires-Dist: pandas (>=2.1.2,<3.0.0)
+Requires-Dist: pandas-market-calendars (>=5.1.0,<7.0.0)
 Requires-Dist: plotly (>=5.18.0,<7.0.0)
 Requires-Dist: pyarrow (>=14.0.2,<21.0.0)
 Requires-Dist: pydantic (>=2.5.2,<3.0.0)
@@ -83,7 +84,6 @@ Description-Content-Type: text/markdown
 This is a project with tools to analyze financial timeseries of a single
 asset or a group of assets. It is solely made for daily or less frequent data.
 
-
 ## Basic Usage
 
 To install:
@@ -119,6 +119,7 @@ _,_=series.plot_series()
 ```
 
 ### Sample output using the OpenFrame.all_properties() method:
+
 ```
                        Scilla Global Equity C (simulation+fund) Global Low Volatility index, SEK
                                                 ValueType.PRICE                  ValueType.PRICE
@@ -156,7 +157,6 @@ The OpenTimeSeries and OpenFrame classes are both subclasses of
 the [Pydantic BaseModel](https://docs.pydantic.dev/usage/models/). Please refer to its documentation for information
 on any attributes or methods inherited from this model.
 
-
 ### Windows Powershell
 
 ```powershell
@@ -202,7 +202,6 @@ make lint
 
 ```
 
-
 ## Table of Contents
 
 - [Basic Usage](#basic-usage)
@@ -239,34 +238,35 @@ make lint
 
 ### Non-numerical or "helper" properties that apply only to the [OpenTimeSeries](https://github.com/CaptorAB/openseries/blob/master/openseries/series.py) class.
 
-| Property        | type            | Applies to       | Description                                                                                                                                  |
-|:----------------|:----------------|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------|
-| `timeseries_id` | `str`           | `OpenTimeSeries` | Placeholder for database identifier for the timeseries. Can be left as empty string.                                                         |
-| `instrument_id` | `str`           | `OpenTimeSeries` | Placeholder for database identifier for the instrument associated with the timeseries. Can be left as empty string.                          |
-| `dates`         | `list[str]`     | `OpenTimeSeries` | Dates of the timeseries. Not edited by any method to allow reversion to original.                                                            |
-| `values`        | `list[float]`   | `OpenTimeSeries` | Values of the timeseries. Not edited by any method to allow reversion to original.                                                           |
-| `currency`      | `str`           | `OpenTimeSeries` | Currency of the timeseries. Only used if conversion/hedging methods are added.                                                               |
-| `domestic`      | `str`           | `OpenTimeSeries` | Domestic currency of the user / investor. Only used if conversion/hedging methods are added.                                                 |
-| `local_ccy`     | `bool`          | `OpenTimeSeries` | Indicates if series should be in its local currency or the domestic currency of the user. Only used if conversion/hedging methods are added. |
-| `name`          | `str`           | `OpenTimeSeries` | An identifier field.                                                                                                                         |
-| `isin`          | `str`           | `OpenTimeSeries` | ISIN code of the associated instrument. If any.                                                                                              |
-| `label`         | `str`           | `OpenTimeSeries` | Field used in outputs. Derived from name as default.                                                                                         |
-| `countries`     | `list` or `str` | `OpenTimeSeries` | (List of) country code(s) according to ISO 3166-1 alpha-2 used to generate business days.                                                    |
-| `valuetype`     | `ValueType`     | `OpenTimeSeries` | Field identifies the type of values in the series. ValueType is an Enum.                                                                     |
+| Property        | type                 | Applies to       | Description                                                                                                                                                       |
+|:----------------|:---------------------|:-----------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `timeseries_id` | `str`                | `OpenTimeSeries` | Placeholder for database identifier for the timeseries. Can be left as empty string.                                                                              |
+| `instrument_id` | `str`                | `OpenTimeSeries` | Placeholder for database identifier for the instrument associated with the timeseries. Can be left as empty string.                                               |
+| `dates`         | `list[str]`          | `OpenTimeSeries` | Dates of the timeseries. Not edited by any method to allow reversion to original.                                                                                 |
+| `values`        | `list[float]`        | `OpenTimeSeries` | Values of the timeseries. Not edited by any method to allow reversion to original.                                                                                |
+| `currency`      | `str`                | `OpenTimeSeries` | Currency of the timeseries. Only used if conversion/hedging methods are added.                                                                                    |
+| `domestic`      | `str`                | `OpenTimeSeries` | Domestic currency of the user / investor. Only used if conversion/hedging methods are added.                                                                      |
+| `local_ccy`     | `bool`               | `OpenTimeSeries` | Indicates if series should be in its local currency or the domestic currency of the user. Only used if conversion/hedging methods are added.                      |
+| `name`          | `str`                | `OpenTimeSeries` | An identifier field.                                                                                                                                              |
+| `isin`          | `str`                | `OpenTimeSeries` | ISIN code of the associated instrument. If any.                                                                                                                   |
+| `label`         | `str`                | `OpenTimeSeries` | Field used in outputs. Derived from name as default.                                                                                                              |
+| `countries`     | `list[str]` or `str` | `OpenTimeSeries` | (List of) country code(s) according to ISO 3166-1 alpha-2 used in the [holidays](https://github.com/vacanza/holidays/) package to generate business days.         |
+| `markets`       | `list[str]` or `str` | `OpenTimeSeries` | (List of) markets code(s) according to market code(s) input for the [pandas-market-calendars](https://pandas-market-calendars.readthedocs.io/en/latest/) package. |
+| `valuetype`     | `ValueType`          | `OpenTimeSeries` | Field identifies the type of values in the series. ValueType is an Enum.                                                                                          |
 
 ### Non-numerical or "helper" properties that apply only to the [OpenFrame](https://github.com/CaptorAB/openseries/blob/master/openseries/frame.py) class.
 
-| Property           | type                   | Applies to  | Description                                                              |
-|:-------------------|:-----------------------|:------------|:-------------------------------------------------------------------------|
-| `constituents`     | `list[OpenTimeSeries]` | `OpenFrame` | A list of the OpenTimeSeries that make up an OpenFrame.                  |
-| `columns_lvl_zero` | `list`                 | `OpenFrame` | A list of the level zero column names in the OpenFrame pandas.DataFrame. |
-| `columns_lvl_one`  | `list`                 | `OpenFrame` | A list of the level one column names in the OpenFrame pandas.DataFrame.  |
-| `item_count`       | `int`                  | `OpenFrame` | Number of columns in the OpenFrame pandas.DataFrame.                     |
-| `weights`          | `list[float]`          | `OpenFrame` | Weights used in the method `make_portfolio`.                             |
-| `first_indices`    | `pandas.Series`        | `OpenFrame` | First dates of all the series in the OpenFrame.                          |
-| `last_indices`     | `pandas.Series`        | `OpenFrame` | Last dates of all the series in the OpenFrame.                           |
-| `lengths_of_items` | `pandas.Series`        | `OpenFrame` | Number of items in each of the series in the OpenFrame.                  |
-| `span_of_days_all` | `pandas.Series`        | `OpenFrame` | Number of days from the first to the last in each of the series.         |
+| Property           | type                             | Applies to  | Description                                                              |
+|:-------------------|:---------------------------------|:------------|:-------------------------------------------------------------------------|
+| `constituents`     | `list[OpenTimeSeries]`           | `OpenFrame` | A list of the OpenTimeSeries that make up an OpenFrame.                  |
+| `columns_lvl_zero` | `list[str]`                      | `OpenFrame` | A list of the level zero column names in the OpenFrame pandas.DataFrame. |
+| `columns_lvl_one`  | `list[ValueType]` or `list[str]` | `OpenFrame` | A list of the level one column names in the OpenFrame pandas.DataFrame.  |
+| `item_count`       | `int`                            | `OpenFrame` | Number of columns in the OpenFrame pandas.DataFrame.                     |
+| `weights`          | `list[float]`                    | `OpenFrame` | Weights used in the method `make_portfolio`.                             |
+| `first_indices`    | `pandas.Series[dt.date]`         | `OpenFrame` | First dates of all the series in the OpenFrame.                          |
+| `last_indices`     | `pandas.Series[dt.date]`         | `OpenFrame` | Last dates of all the series in the OpenFrame.                           |
+| `lengths_of_items` | `pandas.Series[int]`             | `OpenFrame` | Number of items in each of the series in the OpenFrame.                  |
+| `span_of_days_all` | `pandas.Series[int]`             | `OpenFrame` | Number of days from the first to the last in each of the series.         |
 
 ### Non-numerical or "helper" properties that apply to both the [OpenTimeSeries](https://github.com/CaptorAB/openseries/blob/master/openseries/series.py) and the [OpenFrame](https://github.com/CaptorAB/openseries/blob/master/openseries/frame.py) class.
 
@@ -290,7 +290,7 @@ make lint
 | `running_adjustment`     | `OpenTimeSeries` | Adjusts the series performance with a `float` factor.                                                                                          |
 | `ewma_vol_func`          | `OpenTimeSeries` | Returns a `pandas.Series` with volatility based on [Exponentially Weighted Moving Average](https://www.investopedia.com/articles/07/ewma.asp). |
 | `from_1d_rate_to_cumret` | `OpenTimeSeries` | Converts a series of 1-day rates into a cumulative valueseries.                                                                                |
-                                                                           |
+|
 
 ### Methods that apply only to the [OpenFrame](https://github.com/CaptorAB/openseries/blob/master/openseries/frame.py) class.
 
@@ -328,10 +328,11 @@ make lint
 | `to_xlsx`                          | `OpenTimeSeries`, `OpenFrame` | Method to save the data in the .tsdf DataFrame to an Excel file.                                                                                         |
 | `value_to_ret`                     | `OpenTimeSeries`, `OpenFrame` | Converts a value series into a percentage return series.                                                                                                 |
 | `value_to_diff`                    | `OpenTimeSeries`, `OpenFrame` | Converts a value series into a series of differences.                                                                                                    |
-| `value_to_log`                     | `OpenTimeSeries`, `OpenFrame` | Converts a value series into a logarithmic return series.                                                                                                |
+| `value_to_log`                     | `OpenTimeSeries`, `OpenFrame` | Converts a value series into a cumulative log return series, useful for plotting growth relative to the starting point.                                  |
 | `value_ret_calendar_period`        | `OpenTimeSeries`, `OpenFrame` | Returns the series simple return for a specific calendar period.                                                                                         |
-| `plot_series`                      | `OpenTimeSeries`, `OpenFrame` | Opens a HTML [Plotly Scatter](https://plotly.com/python/line-and-scatter/) plot of the series in a browser window.                                       |
-| `plot_bars`                        | `OpenTimeSeries`, `OpenFrame` | Opens a HTML [Plotly Bar](https://plotly.com/python/bar-charts/) plot of the series in a browser window.                                                 |
+| `plot_series`                      | `OpenTimeSeries`, `OpenFrame` | Opens a HTML [Plotly Scatter](https://plotly.com/python/line-and-scatter/) plot of the serie(s) in a browser window.                                     |
+| `plot_bars`                        | `OpenTimeSeries`, `OpenFrame` | Opens a HTML [Plotly Bar](https://plotly.com/python/bar-charts/) plot of the serie(s) in a browser window.                                               |
+| `plot_histogram`                   | `OpenTimeSeries`, `OpenFrame` | Opens a HTML [Plotly Histogram](https://plotly.com/python/histograms/) plot of the serie(s) in a browser window.                                         |
 | `to_drawdown_series`               | `OpenTimeSeries`, `OpenFrame` | Converts the series into drawdown series.                                                                                                                |
 | `rolling_return`                   | `OpenTimeSeries`, `OpenFrame` | Returns a pandas.DataFrame with rolling returns.                                                                                                         |
 | `rolling_vol`                      | `OpenTimeSeries`, `OpenFrame` | Returns a pandas.DataFrame with rolling volatilities.                                                                                                    |

openseries-1.8.4.dist-info/RECORD

@@ -0,0 +1,16 @@
+openseries/__init__.py,sha256=dKw_wEfgrCwwV1IRljesrtxjE9AVFwTyhE8k4CFIck8,1053
+openseries/_common_model.py,sha256=oW-jM8CCAS4E7R-E7hPHDUkMJ5i2sc1DRGxvRB498SA,82789
+openseries/_risk.py,sha256=lZzoP5yjq9vHtKhYe7kU3-iG8rADcu00bkT9kIgsi_E,2086
+openseries/datefixer.py,sha256=7ugMIEKf5lhifd1FlC_aHlHt_Fwvof3aRSLaHM2fvR8,15525
+openseries/frame.py,sha256=H3gAIKTDy5aStKTjBtudsJX15knH0t-8NfdD26JVu3Y,55654
+openseries/load_plotly.py,sha256=VGDdS8ojPQK7AQr-dGi9IfShi5O0EfjM8kUQrJhG_Zw,2000
+openseries/owntypes.py,sha256=j5KUbHqJTKyZPaQOurojtf7RoPgk5TC8A1KEtMO6EN0,9341
+openseries/plotly_captor_logo.json,sha256=F5nhMzEyxKywtjvQqMTKgKRCJQYMDIiBgDSxdte8Clo,178
+openseries/plotly_layouts.json,sha256=9tKAeittrjwJWhBMV8SnCDAWdhgbVnUqXcN6P_J_bos,1433
+openseries/portfoliotools.py,sha256=6bgz64-B6qJVrHAE-pLp8JJCmJkO_JAExHL5G3AwPWE,19295
+openseries/series.py,sha256=xYU4c1MA02AaFko5q72JoVDEKs60zDmxkfG4P_uCpOY,28265
+openseries/simulation.py,sha256=LhKfA32uskMNr90V9r1_uYKC7FZgWRcdLzw2--D1qUM,14131
+openseries-1.8.4.dist-info/LICENSE.md,sha256=wNupG-KLsG0aTncb_SMNDh1ExtrKXlpxSJ6RC-g-SWs,1516
+openseries-1.8.4.dist-info/METADATA,sha256=D6rlANyAmZ72EonbQTMyjE10ctd1MuJqQ3nVXbqNO3A,46550
+openseries-1.8.4.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+openseries-1.8.4.dist-info/RECORD,,

{openseries-1.8.2.dist-info → openseries-1.8.4.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.2
+Generator: poetry-core 2.1.3
 Root-Is-Purelib: true
 Tag: py3-none-any

openseries-1.8.2.dist-info/RECORD

@@ -1,16 +0,0 @@
-openseries/__init__.py,sha256=dKw_wEfgrCwwV1IRljesrtxjE9AVFwTyhE8k4CFIck8,1053
-openseries/_common_model.py,sha256=wQ0tevEqrjckevW8UbTsx6I7t6unAYWAr4QkaIx7pHo,74522
-openseries/_risk.py,sha256=lZzoP5yjq9vHtKhYe7kU3-iG8rADcu00bkT9kIgsi_E,2086
-openseries/datefixer.py,sha256=5S4Ib9CRHfsVPKsDKcIW7x8G86zxkMJz2jZ_Sig2Asw,12535
-openseries/frame.py,sha256=lqRwNNs82TCbl1rjVpy48VpndmIgRztIBNitjaHy2Mo,55859
-openseries/load_plotly.py,sha256=VGDdS8ojPQK7AQr-dGi9IfShi5O0EfjM8kUQrJhG_Zw,2000
-openseries/owntypes.py,sha256=rx0iINJhJDhe8_6udbhofNCyfrlfzEEGpoqm4h2FTjE,9091
-openseries/plotly_captor_logo.json,sha256=F5nhMzEyxKywtjvQqMTKgKRCJQYMDIiBgDSxdte8Clo,178
-openseries/plotly_layouts.json,sha256=FnC5le7YRSb1V8ed3aRr-dEqYtIeE1S6ihtYPpyBynU,1439
-openseries/portfoliotools.py,sha256=6bgz64-B6qJVrHAE-pLp8JJCmJkO_JAExHL5G3AwPWE,19295
-openseries/series.py,sha256=7le45RBcBqF9exDzfXfWbY8iiqgl70UUHNOWORvHAuQ,27221
-openseries/simulation.py,sha256=WHmPU2sNl03YvaL7-Ots7i0I_ZZ9j0hBSCnDYWSypK0,13936
-openseries-1.8.2.dist-info/LICENSE.md,sha256=wNupG-KLsG0aTncb_SMNDh1ExtrKXlpxSJ6RC-g-SWs,1516
-openseries-1.8.2.dist-info/METADATA,sha256=NoHlH3cdCzJ7C6paTWqRS3yytteNOBqO6N8ZDY56UWc,45645
-openseries-1.8.2.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-openseries-1.8.2.dist-info/RECORD,,