xpectral 1.0__tar.gz

xpectral-1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,27 @@
+# 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/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xpectral"
+version = "1.0"
+description = "Quant Research Library"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+authors = [
+    { name = "BayQuant" }
+]
+keywords = ["finance", "quant", "bokeh", "polars"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+dependencies = [
+    "bokeh==3.8.1",
+    "massive>=2.0.2",
+    "matplotlib>=3.10.7",
+    "pandas>=2.3.3",
+    "polars>=1.34.0",
+    "pyarrow>=21.0.0",
+    "python-dotenv>=1.2.1",
+]
+
+[dependency-groups]
+dev = [
+    "black",                           # code formatter
+    "ipykernel>=7.0.1",                # Jupyter notebook support
+    "furo>=2024.0",                    # Sphinx theme for docs
+    "myst-parser>=3.0",                # Markdown support in Sphinx docs
+    "sphinx>=8.0",                     # Sphinx documentation generator
+    "sphinx-autodoc-typehints>=2.0",   # type hint rendering in Sphinx docs
+]
+
+[project.urls]
+Homepage = "https://github.com/bayquant/xpectral"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["xpectral*"]

xpectral-1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xpectral-1.0/tests/test_polars_charts_accessor.py

@@ -0,0 +1,71 @@
+import unittest
+
+import polars as pl
+from bokeh.plotting import figure
+
+from xpectral.charts import polars_accessors
+
+
+class TestPolarsBokehAccessor(unittest.TestCase):
+    def setUp(self) -> None:
+        self.df = pl.DataFrame(
+            {
+                "x": [1, 2, 3],
+                "y": [10, 20, 30],
+                "y2": [12, 18, 36],
+                "low": [8, 16, 24],
+                "high": [14, 24, 40],
+            }
+        )
+
+    def test_unknown_glyph_raises(self) -> None:
+        with self.assertRaisesRegex(ValueError, "Unknown glyph 'area'"):
+            self.df.bokeh.plot("area", glyph_params={"x": "x", "y": "y"})
+
+    def test_missing_column_fails_through_bokeh_validation(self) -> None:
+        with self.assertRaisesRegex(Exception, "missing"):
+            self.df.bokeh.plot("line", glyph_params={"x": "x", "y": "missing"})
+
+    def test_unsupported_figure_param_raises(self) -> None:
+        with self.assertRaisesRegex(ValueError, "Unsupported figure_params: not_a_figure_prop"):
+            self.df.bokeh.plot(
+                "line",
+                glyph_params={"x": "x", "y": "y"},
+                figure_params={"not_a_figure_prop": 1},
+            )
+
+    def test_default_x_uses_generated_index_column(self) -> None:
+        df = self.df.drop("x")
+        fig = df.bokeh.plot("line", glyph_params={"y": "y"})
+
+        self.assertEqual(fig.renderers[0].glyph.x, "__index")
+        self.assertIn("__index", fig.renderers[0].data_source.column_names)
+        self.assertNotIn("__index", df.columns)
+
+    def test_existing_figure_is_reused_and_updated(self) -> None:
+        existing = figure(width=250)
+        fig = self.df.bokeh.plot(
+            "scatter",
+            glyph_params={"x": "x", "y": "y"},
+            figure=existing,
+            figure_params={"title": "Updated"},
+        )
+
+        self.assertIs(fig, existing)
+        self.assertEqual(existing.title.text, "Updated")
+        self.assertEqual(len(existing.renderers), 1)
+
+    def test_accepted_figure_params_api(self) -> None:
+        fig_keys = self.df.bokeh.accepted_figure_params()
+        self.assertIsInstance(fig_keys, set)
+        self.assertIn("title", fig_keys)
+
+    def test_accepted_figure_params_pattern_filter_returns_set(self) -> None:
+        fig_keys = self.df.bokeh.accepted_figure_params(pattern="title")
+        self.assertIsInstance(fig_keys, set)
+        self.assertTrue(fig_keys)
+        self.assertTrue(all("title" in key for key in fig_keys))
+
+
+if __name__ == "__main__":
+    unittest.main()

xpectral-1.0/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-1.0/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-1.0/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-1.0/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
+#-----------------------------------------------------------------------------