xpectral 1.0__py3-none-any.whl

xpectral/__init__.py

@@ -0,0 +1,20 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+from pathlib import Path
+
+# Other imports
+from dotenv import load_dotenv
+from . import charts
+from . import data
+from . import quant
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+load_dotenv(
+    dotenv_path=Path(__file__).resolve().parent / ".env"
+)

xpectral/charts/__init__.py

@@ -0,0 +1,17 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+
+# Other imports
+from .polars_accessors import BokehAccessor
+from .polars_accessors import Figure
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+__all__ = [
+    "BokehAccessor"
+]

xpectral/charts/_decorators.py

@@ -0,0 +1,73 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+from __future__ import annotations
+from functools import wraps
+from inspect import Parameter
+from inspect import Signature
+from inspect import signature
+
+# Other imports
+from bokeh.plotting._docstring import generate_docstring
+from bokeh.plotting._renderer import create_renderer
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+def glyph_method(glyphclass):
+    def decorator(func):
+        parameters = glyphclass.parameters()
+
+        # TODO: send issue so that this signature only takes glyphclass.args instead of [x[0] for x in parameters]
+        sigparams = (
+            [Parameter("self", Parameter.POSITIONAL_OR_KEYWORD)]
+            + [x[0] for x in parameters]
+            + [Parameter("source", Parameter.KEYWORD_ONLY, default=None)]
+            + [Parameter("kwargs", Parameter.VAR_KEYWORD)]
+        )
+
+        @wraps(func)
+        def wrapped(self, *args, **kwargs):
+            # Validate positional arguments against the glyph's declared positional field order.
+            if len(args) > len(glyphclass._args):
+                raise TypeError(f"{func.__name__} takes {len(glyphclass._args)} positional argument but {len(args)} were given")
+            # Map positional inputs to their corresponding glyph kwargs by param name.
+            for arg, param in zip(args, sigparams[1:]):
+                kwargs[param.name] = arg
+            # Default source comes from the accessor unless explicitly provided.
+            kwargs.setdefault("source", self.source)
+            # Preserve any coordinate context passed through a custom Figure subclass.
+            if self.coordinates is not None:
+                kwargs.setdefault("coordinates", self.coordinates)
+            # Inspect/create synthetic fields on the source when required by the glyph.
+            source = kwargs["source"]
+            n = len(next(iter(source.data.values()), ()))
+            # If x is required but missing, inject a 1..n index column into source and reference it by name.
+            if "x" in glyphclass._args and "x" not in kwargs and "x" not in source.data:
+                source.data["x"] = list(range(1, n + 1))
+                kwargs["x"] = "x"
+            # If y is required but missing, inject a 1..n index column into source and reference it by name.
+            if "y" in glyphclass._args and "y" not in kwargs and "y" not in source.data:
+                source.data["y"] = list(range(1, n + 1))
+                kwargs["y"] = "y"
+            # Delegate to Bokeh with normalized kwargs and possibly augmented source columns.
+            return create_renderer(glyphclass, self.plot, **kwargs)
+
+        wrapped.__signature__ = Signature(parameters=sigparams, return_annotation=signature(func).return_annotation)
+
+        wrapped.__doc__ = generate_docstring(glyphclass, parameters, func.__doc__)
+
+        return wrapped
+
+    return decorator
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------

xpectral/charts/_figure.py

@@ -0,0 +1,86 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+from __future__ import annotations
+
+# Other imports
+from bokeh.models import Plot
+from bokeh.plotting._figure import FigureOptions
+from bokeh.plotting._plot import get_range
+from bokeh.plotting._plot import get_scale
+from bokeh.plotting._plot import process_axis_and_grid
+from bokeh.plotting._tools import process_active_tools
+from bokeh.plotting._tools import process_tools_arg
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+__all__ = ["Figure"]
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+class Figure(Plot):
+
+    def __init__(self, *arg, **kwargs) -> None:
+        opts = FigureOptions(kwargs)
+
+        names = self.properties()
+        for name in kwargs.keys():
+            if name not in names:
+                self._raise_attribute_error_with_matches(name, names | opts.properties())
+
+        super().__init__(*arg, **kwargs)
+
+        self.x_range = get_range(opts.x_range)
+        self.y_range = get_range(opts.y_range)
+
+        self.x_scale = get_scale(self.x_range, opts.x_axis_type)
+        self.y_scale = get_scale(self.y_range, opts.y_axis_type)
+
+        process_axis_and_grid(
+            self,
+            opts.x_axis_type,
+            opts.x_axis_location,
+            opts.x_minor_ticks,
+            opts.x_axis_label,
+            self.x_range,
+            0,
+        )
+        process_axis_and_grid(
+            self,
+            opts.y_axis_type,
+            opts.y_axis_location,
+            opts.y_minor_ticks,
+            opts.y_axis_label,
+            self.y_range,
+            1,
+        )
+
+        tool_objs, tool_map = process_tools_arg(self, opts.tools, opts.tooltips)
+        self.add_tools(*tool_objs)
+        process_active_tools(
+            self.toolbar,
+            tool_map,
+            opts.active_drag,
+            opts.active_inspect,
+            opts.active_scroll,
+            opts.active_tap,
+            opts.active_multi,
+        )
+
+    @property
+    def plot(self):
+        return self
+
+    @property
+    def coordinates(self):
+        return None
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------

xpectral/charts/polars_accessors.py

@@ -0,0 +1,256 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+from __future__ import annotations
+import warnings
+from typing import Any
+
+# Other imports
+from bokeh.models import ColumnDataSource
+from bokeh.models import glyphs
+from bokeh.models.renderers import GlyphRenderer
+from bokeh.plotting._stack import double_stack
+from bokeh.plotting._stack import single_stack
+from bokeh.util.warnings import BokehUserWarning
+import polars as pl
+from ._decorators import glyph_method
+from ._figure import Figure
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+warnings.simplefilter("ignore", BokehUserWarning)
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+@pl.api.register_dataframe_namespace("bokeh")
+class BokehAccessor(Figure):
+
+    __view_model__ = "Figure"
+    __view_module__ = "bokeh.plotting.figure"
+
+    def __init__(self, df: pl.DataFrame) -> None:
+        self._df = df
+
+    @property
+    def source(self) -> ColumnDataSource:
+        if not hasattr(self, "_source"):
+            self._source = ColumnDataSource(self._df.to_dict(as_series=False))
+        return self._source
+
+    def __call__(self, *args, **kwargs) -> "BokehAccessor":
+        super().__init__(*args, **kwargs)
+        return self.plot
+
+    #-------------------------------------------
+    # Glyph methods with both x and y parameters
+    @glyph_method(glyphs.AnnularWedge)
+    def annular_wedge(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Annulus)
+    def annulus(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Arc)
+    def arc(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Block)
+    def block(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Ellipse)
+    def ellipse(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Image)
+    def image(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.ImageRGBA)
+    def image_rgba(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.ImageStack)
+    def image_stack(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.ImageURL)
+    def image_url(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Line)
+    def line(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.MathMLGlyph)
+    def mathml_glyph(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Ngon)
+    def ngon(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Patch)
+    def patch(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Ray)
+    def ray(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Rect)
+    def rect(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Scatter)
+    def scatter(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Step)
+    def step(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.TeXGlyph)
+    def tex_glyph(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Text)
+    def text(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Wedge)
+    def wedge(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    #----------------------------------------------------
+    # Vertical glyph methods (have parameter x but not y)
+    @glyph_method(glyphs.VArea)
+    def varea(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.VAreaStep)
+    def varea_step(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.VBar)
+    def vbar(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.VSpan)
+    def vspan(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    #------------------------------------------------------
+    # Horizontal glyph methods (have parameter y but not x)
+    @glyph_method(glyphs.HArea)
+    def harea(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.HAreaStep)
+    def harea_step(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.HBar)
+    def hbar(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.HSpan)
+    def hspan(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    #-----------------------------------------
+    # Glyph methods without x nor y parameters
+    @glyph_method(glyphs.Bezier)
+    def bezier(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.HStrip)
+    def hstrip(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.HexTile)
+    def hextile(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.MultiLine)
+    def multi_line(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.MultiPolygons)
+    def multipolygons(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Patches)
+    def patches(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Quad)
+    def quad(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Quadratic)
+    def quadratic(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.Segment)
+    def segment(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    @glyph_method(glyphs.VStrip)
+    def vstrip(self, *args: Any, **kwargs: Any) -> GlyphRenderer:
+        pass
+
+    #-----------------------------------------
+    # Glyph stack methods 
+    def harea_stack(self, stackers: list[str], **kwargs: Any) -> list[GlyphRenderer]:
+        result = []
+        for kwarg in double_stack(stackers=stackers, spec0="x1", spec1="x2", **kwargs):
+            result.append(self.harea(**kwarg))
+        return result
+
+    def hbar_stack(self, stackers: list[str], **kwargs: Any) -> list[GlyphRenderer]:
+        result = []
+        for kwarg in double_stack(stackers=stackers, spec0="left", spec1="right", **kwargs):
+            result.append(self.hbar(**kwarg))
+        return result
+
+    def hline_stack(self, stackers: list[str], **kwargs: Any) -> list[GlyphRenderer]:
+        result = []
+        for kwarg in single_stack(stackers=stackers, spec="x", **kwargs):
+            result.append(self.line(**kwarg))
+        return result
+
+    def varea_stack(self, stackers: list[str], **kwargs: Any) -> list[GlyphRenderer]:
+        result = []
+        for kwarg in double_stack(stackers=stackers, spec0="y1", spec1="y2", **kwargs):
+            result.append(self.varea(**kwarg))
+        return result
+
+    def vbar_stack(self, stackers: list[str], **kwargs: Any) -> list[GlyphRenderer]:
+        result = []
+        for kwarg in double_stack(stackers=stackers, spec0="bottom", spec1="top", **kwargs):
+            result.append(self.vbar(**kwarg))
+        return result
+
+    def vline_stack(self, stackers: list[str], **kwargs: Any) -> list[GlyphRenderer]:
+        result = []
+        for kwarg in single_stack(stackers=stackers, spec="y", **kwargs):
+            result.append(self.line(**kwarg))
+        return result
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------
+
+# Polars' NameSpace descriptor caches the accessor on the DataFrame instance
+# via setattr, causing the same BokehAccessor to be returned on repeated
+# accesses of df.bokeh. Replacing the descriptor with a non-caching property
+# ensures each access produces a fresh instance.
+pl.DataFrame.bokeh = property(lambda self: BokehAccessor(self))  # type: ignore[assignment]

xpectral/charts/theme_manager.py

@@ -0,0 +1,136 @@
+"""Central theme management for Bokeh apps."""
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+from __future__ import annotations
+
+# Other imports
+from bokeh.io import curdoc
+from bokeh.themes import built_in_themes
+from bokeh.themes import Theme
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+THEMES = {
+    "caliber": built_in_themes["caliber"],
+    "carbon": built_in_themes["carbon"],
+    "light_minimal": built_in_themes["light_minimal"],
+    "dark_minimal": built_in_themes["dark_minimal"],
+    "night_sky": built_in_themes["night_sky"],
+    "contrast": built_in_themes["contrast"],
+    "ocean": Theme(
+        json={
+            "attrs": {
+                "Toolbar": {
+                    "logo": None
+                },
+                "Plot": {
+                    "background_fill_color": "#e8e8ea",
+                    "border_fill_color": "#e8e8ea",
+                    "outline_line_color": "#253d8f",
+                    "outline_line_alpha": 0.3,
+                    "min_border_left": 36,
+                    "min_border_right": 24,
+                    "min_border_top": 26,
+                    "min_border_bottom": 36,
+                },
+                "Grid": {
+                    "grid_line_color": "#497bbc",
+                    "grid_line_alpha": 0.2,
+                },
+                "Axis": {
+                    "major_tick_line_alpha": 0.35,
+                    "major_tick_line_color": "#6b7ab0",
+                    "minor_tick_line_alpha": 0.25,
+                    "minor_tick_line_color": "#6b7ab0",
+                    "axis_line_alpha": 0.5,
+                    "axis_line_color": "#6b7ab0",
+                    "major_label_text_color": "#4d4d4d",
+                    "major_label_text_font": "Helvetica",
+                    "major_label_text_font_size": "1.025em",
+                    "axis_label_standoff": 18,
+                    "axis_label_text_color": "#6b7ab0",
+                    "axis_label_text_font": "Helvetica",
+                    "axis_label_text_font_size": "1.25em",
+                    "axis_label_text_font_style": "normal",
+                },
+                "Legend": {
+                    "spacing": 8,
+                    "glyph_width": 15,
+                    "label_standoff": 8,
+                    "label_text_color": "#253d8f",
+                    "label_text_font": "Helvetica",
+                    "label_text_font_size": "1.025em",
+                    "border_line_alpha": 0,
+                    "background_fill_alpha": 0.45,
+                    "background_fill_color": "#e8e8ea",
+                },
+                "BaseColorBar": {
+                    "title_text_color": "#253d8f",
+                    "title_text_font": "Helvetica",
+                    "title_text_font_size": "1.025em",
+                    "title_text_font_style": "normal",
+                    "major_label_text_color": "#253d8f",
+                    "major_label_text_font": "Helvetica",
+                    "major_label_text_font_size": "1.025em",
+                    "background_fill_color": "#e8e8ea",
+                    "major_tick_line_alpha": 0,
+                    "bar_line_alpha": 0,
+                },
+                "Title": {
+                    "text_color": "#253d8f",
+                    "text_font": "Helvetica",
+                    "text_font_size": "1.15em",
+                },
+                "Line": {
+                    "line_color": "#497bbc",
+                },
+                "Fill": {
+                    "fill_color": "#bf4e30",
+                },
+                "Text": {
+                    "text_color": "#253d8f",
+                },
+            }
+        }
+    ),
+}
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+class ThemeAccessor:
+    """Small accessor around a named collection of Bokeh themes."""
+
+    def __init__(self, default: str = "light") -> None:
+        if default not in THEMES:
+            raise ValueError(f"Unknown default theme '{default}'")
+        self._name = default
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def current(self):
+        return THEMES[self._name]
+
+    def set(self, name: str) -> None:
+        if name not in THEMES:
+            raise ValueError(f"Unknown theme '{name}'. Options: {list(THEMES)}")
+        self._name = name
+        curdoc().theme = self.current
+
+
+# Global accessor for app/notebook code.
+theme = ThemeAccessor(default="light_minimal")
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------

xpectral/data/__init__.py

@@ -0,0 +1,16 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+
+# Other imports
+from . import massive
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+__all__ = [
+    "massive"
+]

xpectral/data/massive.py

@@ -0,0 +1,97 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+from datetime import date
+from datetime import datetime
+from functools import lru_cache
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Tuple
+from typing import Union
+import os
+
+# Other imports
+from massive import RESTClient
+from massive.rest.models import Sort
+import polars as pl
+from ..utils.rate_limiter import RateLimiter
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+client = RESTClient(
+    api_key=os.getenv("MASSIVE_API_KEY", ""), pagination=True, trace=False
+)
+_rate_limiter = RateLimiter(calls=5, per_seconds=60)
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+def get_aggregate_bars(
+        tickers: List[str],
+        multiplier: int,
+        timespan: str,
+        from_: Union[str, int, datetime, date],
+        to: Union[str, int, datetime, date],
+        adjusted: Optional[bool] = True,
+        sort: Optional[Union[str, Sort]] = None,
+        limit: Optional[int] = None
+        ):
+    # create kwargs dictionary from local variables (copy to avoid mutating locals directly)
+    kwargs = locals().copy()
+    # convert tickers to tuple for caching (lru_cache)
+    kwargs["tickers"] = tuple(kwargs["tickers"])
+
+    df = _get_aggregate_bars(**kwargs)
+
+    return df
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------
+
+@lru_cache(maxsize=10)
+def _get_aggregate_bars(**kwargs):
+    tickers = list(kwargs.pop("tickers"))
+
+    aggs = []
+    for ticker in tickers:
+        _rate_limiter.acquire()
+        for a in client.list_aggs(ticker=ticker, **kwargs):
+            data = a.__dict__
+            timestamp = data["timestamp"]
+            long_format = [
+                {"timestamp": timestamp, "ticker": ticker, "metric": key, "value": value}
+                for key, value in data.items() if key != "timestamp"
+            ]
+            aggs.extend(long_format)
+
+    df = pl.DataFrame(data=aggs)
+
+    # transform unix timestamp to daily format
+    _FREQ_MAP = {
+        "second": "1s",
+        "minute": "1m",
+    }
+    df = df.with_columns(
+        pl.col("timestamp")
+        .cast(pl.Datetime("ms"))
+        .dt.replace_time_zone("UTC")
+        .dt.convert_time_zone("America/New_York")
+        .dt.truncate(_FREQ_MAP.get(kwargs.pop("timespan"), "1d"))
+    )
+
+    # pivot polars dataframe to semi-wide format
+    df = df.pivot(
+        values="value",
+        index=["timestamp", "ticker"],
+        on="metric"
+    )
+
+    return df.lazy()

xpectral/quant/__init__.py

@@ -0,0 +1,18 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+
+# Other imports
+from .polars_accessors import QuantAccessor
+from .portfolio import Portfolio
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+__all__ = [
+    "Portfolio",
+    "QuantAccessor",
+]

xpectral/quant/polars_accessors.py

@@ -0,0 +1,142 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+
+# Other imports
+import polars as pl
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+@pl.api.register_expr_namespace("quant")
+class QuantAccessor:
+    def __init__(self, expr: pl.Expr):
+        self._expr = expr
+
+    def returns(
+        self,
+        periods: int = 1,
+        over: str | None = None
+    ) -> pl.Expr:
+        """
+        Compute simple percentage return for the expression.
+
+        Parameters
+        ----------
+        periods : int
+            Number of periods to shift (default is 1).
+        over : str | None
+            Optional grouping column (e.g. 'ticker'). If None, compute over the full series.
+        """
+        expr = (self._expr / self._expr.shift(n=periods)) - 1
+        return expr.over(over).alias('return') if over is not None else expr.alias('return')
+
+    def compound(
+        self,
+        over: str | None = None,
+    ) -> pl.Expr:
+        """
+        Compound an existing series.
+
+        Parameters
+        ----------
+        over : str | None
+            Optional grouping column (e.g. 'ticker'). If None, compound over the full series.
+        """
+        expr = (1 + self._expr).cum_prod().sub(1)
+
+        return expr.over(over).alias(f"compounded") if over is not None else expr.alias(f"compounded")
+
+    def rolling_vol(
+        self,
+        window_size: int,
+        weights: list[float] | None = None,
+        *,
+        min_samples: int | None = None,
+        center: bool = False,
+        ddof: int = 1,
+        over: str | None = None
+    ) -> pl.Expr:
+        """
+        Compute rolling volatility (standard deviation) for the expression.
+
+        Parameters
+        ----------
+        over : str | None
+            Optional grouping column (e.g. 'ticker').
+        window_size : int
+            Rolling window size.
+        weights : list[float] | None
+            Optional weights for weighted standard deviation.
+        min_samples : int | None
+            Minimum number of samples required to compute a value.
+        center : bool
+            Whether to center the window around the current row.
+        ddof : int
+            Delta degrees of freedom (default = 1 for sample std).
+        """
+        expr = self._expr.rolling_std(
+            window_size=window_size,
+            weights=weights,
+            min_samples=min_samples,
+            center=center,
+            ddof=ddof,
+        )
+        return expr.over(over).alias('rolling_vol') if over is not None else expr.alias('rolling_vol')
+
+    def rolling_beta(
+        self,
+        benchmark_col: pl.Expr,
+        window_size: int,
+        min_periods: int | None = None,
+        ddof: int = 1,
+        over: str | list[str] | None = None
+    ) -> pl.Expr:
+        """
+        Compute rolling beta of this expression against a benchmark expression.
+
+        Parameters
+        ----------
+        benchmark : pl.Expr
+            Benchmark return column.
+        window : int
+            Rolling window size.
+        min_periods : int | None
+            Minimum number of observations required to compute a value.
+        ddof : int
+            Delta degrees of freedom for variance (default 1 for sample variance).
+        over : str | list[str] | None
+            Optional grouping column(s), e.g., "ticker".
+
+        Returns
+        -------
+        pl.Expr
+            Rolling beta expression
+        """
+        expr = (
+            pl.rolling_cov(
+                a=self._expr,
+                b=benchmark_col,
+                window_size=window_size,
+                min_periods=min_periods,
+                ddof=ddof
+            )
+            / benchmark_col.rolling_var(
+                window_size=window_size,
+                min_periods=min_periods,
+                ddof=ddof
+            )
+        )
+
+        return expr.over(over).alias('rolling_beta') if over is not None else expr.alias('rolling_beta')
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------

xpectral/quant/polars_expressions.py

@@ -0,0 +1,39 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+
+# Other imports
+import polars as pl
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+def ffill_inside(expr: pl.Expr) -> pl.Expr:
+    # True from the start up to the *last* non-null; False after that
+    mask = expr.is_not_null().reverse().cum_max().reverse()
+
+    return pl.when(mask).then(expr.forward_fill()).otherwise(None)
+
+
+df = pl.DataFrame({
+    "a": [None, 1, None, 2, None, None],
+    "b": [5, None, None, 7, None, 9],
+})
+
+df_out = df.with_columns(
+    ffill_inside(pl.col("a")).alias("a"),
+    ffill_inside(pl.col("b")).alias("b"),
+)
+
+print(df_out)
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------

xpectral/quant/portfolio.py

@@ -0,0 +1,82 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+from typing import Dict
+
+# Other imports
+import polars as pl
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+class Portfolio:
+    def __init__(self, df: pl.DataFrame, portfolio: Dict, benchmark: str):
+        """
+        Portfolio analytics class for computing total, systematic, and idiosyncratic returns.
+
+        This class takes in a dataset of asset returns (including a benchmark) and a
+        dictionary of portfolio weights, then computes the time series of portfolio-level
+        returns and their decomposition into systematic and idiosyncratic components.
+
+        Parameters
+        ----------
+        df : pl.DataFrame
+            Polars DataFrame containing asset and benchmark data.
+            Must include at least the following columns:
+            - 'timestamp' : datetime
+            - 'ticker' : str
+            - 'return' : float
+            - 'beta' : float
+
+        portfolio : Dict[str, float]
+            Dictionary mapping asset tickers to their portfolio weights.
+            Example: ``{"AAPL": 0.4, "MSFT": 0.6}``.
+
+        benchmark : str
+            Ticker symbol identifying the benchmark asset within `df`
+        """
+        self.df = df
+
+        self.benchmark_df = df.filter(pl.col('ticker') == benchmark).select(
+            ['timestamp', pl.col('return').alias('benchmark_return')]
+        )
+        self.assets_df = df.filter(pl.col('ticker').is_in(list(portfolio.keys())))
+
+        _weights_df = (
+            pl.DataFrame({'ticker': list(portfolio.keys()), 'weight': list(portfolio.values())})
+        ).lazy()
+        self.assets_df = self.assets_df.join(other=_weights_df, on='ticker', how='inner')
+
+    def compute_returns(self) -> pl.DataFrame:
+        """Compute portfolio total, systematic, and idiosyncratic returns."""
+        df = self.assets_df.join(self.benchmark_df, on='timestamp', how='inner')
+
+        df = df.with_columns([
+            (pl.col('systematic_return') * pl.col('weight')).alias('port_systematic_return'),
+            (pl.col('idio_return') * pl.col('weight')).alias('port_idio_return'),
+            (pl.col('return') * pl.col('weight')).alias('port_total_return')
+        ])
+
+        portfolio = (
+            df.group_by('timestamp')
+            .agg([
+                pl.sum('port_systematic_return').alias('systematic_return'),
+                pl.sum('port_idio_return').alias('idio_return'),
+                pl.sum('port_total_return').alias('return'),
+                pl.first('benchmark_return')
+            ])
+            .sort('timestamp')
+        )
+
+        return portfolio
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------

xpectral/utils/logger.py

@@ -0,0 +1,55 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+import sys
+from dataclasses import dataclass
+from typing import Callable
+from typing import Dict
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class LogLevel:
+    name: str
+    color: str  # ANSI color code
+
+
+class ColorLogger:
+    _LEVELS: Dict[str, LogLevel] = {
+        "DEBUG": LogLevel("DEBUG", "\033[94m"),
+        "INFO": LogLevel("INFO", "\033[92m"),
+        "WARNING": LogLevel("WARNING", "\033[93m"),
+        "ERROR": LogLevel("ERROR", "\033[91m"),
+        "CRITICAL": LogLevel("CRITICAL", "\033[95m"),
+    }
+    _RESET = "\033[0m"
+
+    def __init__(self, name: str):
+        self.name = name
+        for level in self._LEVELS:
+            setattr(self, level.lower(), self._build_logger(level))
+
+    def _build_logger(self, level_name: str) -> Callable[..., None]:
+        def log(message: str, *args) -> None:
+            level = self._LEVELS[level_name]
+            formatted = message.format(*args)
+            output = f"{level.color}[{level.name}] {self.name}: {formatted}{self._RESET}"
+            print(output, file=sys.stderr if level_name in {"ERROR", "CRITICAL"} else sys.stdout)
+
+        return log
+
+
+def get_logger(name: str) -> ColorLogger:
+    return ColorLogger(name)
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------

xpectral/utils/rate_limiter.py

@@ -0,0 +1,52 @@
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+# Standard library imports
+import time
+from collections import deque
+from typing import Deque
+
+# Other imports
+from .logger import get_logger
+
+#-----------------------------------------------------------------------------
+# Globals and constants
+#-----------------------------------------------------------------------------
+
+log = get_logger(name="rate_limiter")
+
+#-----------------------------------------------------------------------------
+# General API
+#-----------------------------------------------------------------------------
+
+class RateLimiter:
+    """Simple token bucket style limiter"""
+
+    def __init__(self, calls: int, per_seconds: float):
+        if calls <= 0 or per_seconds <= 0:
+            raise ValueError("calls and per_seconds must be positive")
+        self.calls = calls
+        self.per_seconds = per_seconds
+        self._hits: Deque[float] = deque()
+
+    def acquire(self) -> None:
+        now = time.monotonic()
+        window_start = now - self.per_seconds
+
+        while self._hits and self._hits[0] <= window_start:
+            self._hits.popleft()
+
+        if len(self._hits) >= self.calls:
+            sleep_for = self.per_seconds - (now - self._hits[0])
+            if sleep_for > 0:
+                log.info("sleeping for {:.0f} seconds", sleep_for)
+                time.sleep(sleep_for)
+            self.acquire()
+            return
+
+        self._hits.append(time.monotonic())
+
+#-----------------------------------------------------------------------------
+# Private API
+#-----------------------------------------------------------------------------

xpectral-1.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: xpectral
+Version: 1.0
+Summary: Quant Research Library
+Author: BayQuant
+License: MIT License
+        
+        Copyright (c) 2025 BayQuant
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/bayquant/xpectral
+Keywords: finance,quant,bokeh,polars
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bokeh==3.8.1
+Requires-Dist: massive>=2.0.2
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: polars>=1.34.0
+Requires-Dist: pyarrow>=21.0.0
+Requires-Dist: python-dotenv>=1.2.1
+Dynamic: license-file
+
+# Xpectral
+
+![Spectral decomposition](assets/xpectral_banner.gif)
+
+A quantitative research library that extends **Polars** DataFrames with charting and financial analytics.
+
+## Modules
+
+- **`xpectral.charts`** — Fluent Bokeh visualization via `df.bokeh.line(...)`, `df.bokeh.scatter(...)`, etc.
+- **`xpectral.quant`** — Financial metrics (returns, volatility, beta) via `pl.col(...).quant.returns()`
+- **`xpectral.data`** — Market data from the Polygon/Massive API with caching and rate limiting
+
+## Usage
+
+```python
+import polars as pl
+import xpectral  # registers .bokeh and .quant accessors
+
+df = pl.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
+fig = df.bokeh.line(x="x", y="y")
+```
+
+## Install
+
+```bash
+uv sync
+```

xpectral-1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+xpectral/__init__.py,sha256=vV8B9L7dvlEJellIhMaSq-pVcetYQBBJRgjKSUQW8Gs,585
+xpectral/charts/__init__.py,sha256=uzlyQqomt8yLB3zZ_W_jrnEL8N1SKVMLwi8F7hr4je4,512
+xpectral/charts/_decorators.py,sha256=cBbJ4JpvZFDewOGDNOL0acco6Mj71ZJE9Wu59RUH4cs,3524
+xpectral/charts/_figure.py,sha256=G5NaWUG5L9JKujzNn2LZfmO3irjtl-qWBCrooTM3wFk,2627
+xpectral/charts/polars_accessors.py,sha256=q9MIZxGmgLjiEe0y_Nnuwx7X0G_iW4jAfh69Wj3TMUM,8546
+xpectral/charts/theme_manager.py,sha256=6z5LoBR13xFjyUbZRVYZntH5weQK6m6JrNoiLIxV7O0,5001
+xpectral/data/__init__.py,sha256=CJ3B4DWPPTyzy4alg0DaRe39Hszz39VPrSR_U40vXgw,447
+xpectral/data/massive.py,sha256=BqvTJyMldJCTNDkiDzFC_PqPd-odDaduAHn-vZkliqI,3011
+xpectral/quant/__init__.py,sha256=E_33oFPPtrcpP0oW2tAPX_CSlQB0tktALB7E-uRKU4g,526
+xpectral/quant/polars_accessors.py,sha256=Ra0OUnZWCvBqsIvS3vj-jHdWZ8cpS5WzCC4kp74oxdA,4524
+xpectral/quant/polars_expressions.py,sha256=LAEwMnr5e7V9QhorcQ1g1iHOLULYOYi2bi17NbKaISU,1237
+xpectral/quant/portfolio.py,sha256=NNH1yb2l-aky1q3_NMg3A7cUtWo3OB4cW3AbcIEz9Hg,3235
+xpectral/utils/logger.py,sha256=kQsgzxPuzxXGtwgbxB4kejWx8q2fEOY548rE8pIEkRI,1898
+xpectral/utils/rate_limiter.py,sha256=7lPj92FXAnJyj3eLu7HW70vFb6nsKah6P0OVVHa2I8I,1760
+xpectral-1.0.dist-info/licenses/LICENSE,sha256=oKFaOASRExmxKyg4h4tzD8yffNm1zGNFwubGUOVwq_E,1065
+xpectral-1.0.dist-info/METADATA,sha256=37RqcqCY7_4fbsVsb2sAr7nGkZKXgg_gBiNV-lU_J8A,2687
+xpectral-1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+xpectral-1.0.dist-info/top_level.txt,sha256=b7Ydg4eYKLz1u82k7zKTjdqL4TvZs490bZtPJFgvEaw,9
+xpectral-1.0.dist-info/RECORD,,

xpectral-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xpectral-1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BayQuant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xpectral-1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xpectral