sf-quant 0.2.0__tar.gz → 0.2.2__tar.gz

{sf_quant-0.2.0 → sf_quant-0.2.2}/.gitignore

@@ -220,3 +220,5 @@ __marimo__/
 
 # macOS
 .DS_Store
+
+test.ipynb

{sf_quant-0.2.0 → sf_quant-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sf-quant
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python package for Silver Fund quant team research and trading tools.
 Author-email: Andrew Hall <andrewmartinhall2@gmail.com>
 Requires-Python: <3.14,>=3.11

sf_quant-0.2.2/docs/reference/backtester/sf_quant.backtester.dynamic_backtest_parallel.rst

@@ -0,0 +1,6 @@
+sf\_quant.backtester.dynamic\_backtest\_parallel
+================================================
+
+.. currentmodule:: sf_quant.backtester
+
+.. autofunction:: dynamic_backtest_parallel

sf_quant-0.2.2/docs/reference/backtester/sf_quant.backtester.dynamic_parallel.rst

@@ -0,0 +1,12 @@
+sf\_quant.backtester.dynamic\_parallel
+======================================
+
+.. automodule:: sf_quant.backtester.dynamic_parallel
+
+   
+   .. rubric:: Functions
+
+   .. autosummary::
+   
+      dynamic_backtest_parallel
+   

{sf_quant-0.2.0 → sf_quant-0.2.2}/docs/reference/backtester.rst

@@ -13,4 +13,5 @@ Backtester
    :nosignatures:
 
    backtest_sequential
-   backtest_parallel
+   backtest_parallel
+   dynamic_backtest_parallel

sf_quant-0.2.2/docs/reference/optimizer/sf_quant.optimizer.dynamic_mve_optimizer.rst

@@ -0,0 +1,6 @@
+sf\_quant.optimizer.dynamic\_mve\_optimizer
+===========================================
+
+.. currentmodule:: sf_quant.optimizer
+
+.. autofunction:: dynamic_mve_optimizer

{sf_quant-0.2.0 → sf_quant-0.2.2}/docs/reference/optimizer.rst

@@ -13,6 +13,7 @@ Optimizer
    :nosignatures:
 
    mve_optimizer
+   dynamic_mve_optimizer
    FullInvestment
    ZeroInvestment
    LongOnly

{sf_quant-0.2.0 → sf_quant-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sf-quant"
-version = "0.2.0"
+version = "0.2.2"
 description = "Python package for Silver Fund quant team research and trading tools."
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

{sf_quant-0.2.0 → sf_quant-0.2.2}/src/sf_quant/backtester/__init__.py

@@ -7,5 +7,6 @@ internal execution details hidden.
 
 from .sequential import backtest_sequential
 from .parallel import backtest_parallel
+from .dynamic_parallel import dynamic_backtest_parallel
 
-__all__ = ["backtest_sequential", "backtest_parallel"]
+__all__ = ["backtest_sequential", "backtest_parallel", "dynamic_backtest_parallel"]

sf_quant-0.2.2/src/sf_quant/backtester/dynamic_parallel.py

@@ -0,0 +1,244 @@
+import polars as pl
+import os
+import ray
+import datetime as dt
+from ray.experimental import tqdm_ray
+from sf_quant.data.benchmark import load_benchmark
+from sf_quant.data.covariance_matrix import construct_factor_model_components
+from sf_quant.optimizer.optimizers import dynamic_mve_optimizer
+from sf_quant.optimizer.constraints import Constraint
+from sf_quant.schema.portfolio_schema import PortfolioSchema
+
+
+@ray.remote
+def _construct_portfolio(
+    date_: dt.date,
+    data: pl.DataFrame,
+    constraints: list[Constraint],
+    gamma: float,
+    target_active_risk: float | None = None,
+    benchmark_df: pl.DataFrame | None = None,
+    progress_bar: tqdm_ray.tqdm | None = None,
+):
+    """
+    Construct a single optimized portfolio for a given date.
+
+    This is a Ray-remote helper function for parallel portfolio construction.
+    It filters data to a specific date, constructs the factor model components,
+    and solves a mean-variance optimization problem.
+
+    Parameters
+    ----------
+    date_ : dt.date
+        The date for which to construct the portfolio.
+    data : pl.DataFrame
+        Full dataset with columns 'date', 'barrid', 'alpha', optionally 'predicted_beta'.
+    constraints : list[Constraint]
+        Portfolio constraints to enforce.
+    gamma : float
+        Risk aversion parameter.
+    target_active_risk : float, optional
+        Target active risk for gamma calibration.
+    benchmark_df : pl.DataFrame, optional
+        Benchmark weights data with columns 'date', 'barrid', 'benchmark_weight'.
+    progress_bar : tqdm_ray.tqdm, optional
+        Ray-based progress bar for tracking completion.
+
+    Returns
+    -------
+    pl.DataFrame
+        Portfolio weights for the given date, with columns 'date', 'barrid', 'weight'.
+    """
+    subset = data.filter(pl.col("date").eq(date_)).sort("barrid")
+    barrids = subset["barrid"].to_list()
+    alphas = subset["alpha"].to_numpy()
+
+    betas = (
+        subset["predicted_beta"].to_numpy()
+        if "predicted_beta" in subset.columns
+        else None
+    )
+
+    benchmark_weights = None
+    if benchmark_df is not None:
+        # Get benchmark weights for portfolio barrids on this date
+        bmk_subset = benchmark_df.filter(pl.col("date").eq(date_))
+        # Join with portfolio to ensure alignment
+        aligned = (
+            pl.DataFrame({"barrid": barrids})
+            .join(bmk_subset[["barrid", "benchmark_weight"]], on="barrid", how="left")
+            .fill_null(0.0)
+        )
+        benchmark_weights = aligned["benchmark_weight"].to_numpy()
+
+    (
+        factor_exposures,
+        factor_covariance,
+        specific_risk,
+    ) = construct_factor_model_components(date_, barrids)
+
+    portfolio = dynamic_mve_optimizer(
+        ids=barrids,
+        alphas=alphas,
+        factor_exposures=factor_exposures,
+        factor_covariance=factor_covariance,
+        specific_risk=specific_risk,
+        constraints=constraints,
+        initial_gamma=gamma,
+        betas=betas,
+        target_active_risk=target_active_risk,
+        benchmark_weights=benchmark_weights,
+    )
+
+    portfolio = portfolio.with_columns(pl.lit(date_).alias("date")).select(
+        "date", "barrid", "weight", 'gamma', 'active_risk'
+    )
+
+    if progress_bar is not None:
+        progress_bar.update.remote(1)
+
+    return portfolio
+
+
+def dynamic_backtest_parallel(
+    data: pl.DataFrame,
+    constraints: list[Constraint],
+    initial_gamma: float = 100,
+    target_active_risk: float = 0.05,
+    n_cpus: int | None = None,
+) -> pl.DataFrame:
+    """
+    Run a parallelized backtest of portfolio optimization using Ray.
+
+    This function distributes portfolio construction tasks across multiple CPUs
+    using Ray, solving mean–variance optimization problems for each date in parallel.
+    A Ray-based progress bar tracks computation progress.
+
+    Parameters
+    ----------
+    data : pl.DataFrame
+        Input dataset containing at least the following columns:
+
+        - ``date`` : datetime-like, the date of each observation.
+        - ``barrid`` : str, unique identifier for each asset.
+        - ``alpha`` : float, expected return (alpha) for each asset.
+        - ``predicted_beta`` : float, optional, factor exposures for constraints.
+
+    constraints : list[Constraint]
+        List of portfolio constraints to enforce during optimization.
+    initial_gamma : float, optional
+        Risk aversion parameter. Higher values penalize portfolio variance
+        more strongly. Used as the starting gamma for calibration if
+        ``target_active_risk`` is specified. Default is 100.
+    target_active_risk : float, optional
+        If specified, automatically calibrate gamma for each date to achieve this
+        target annualized active risk (e.g., 0.05 for 5%). Requires benchmark data
+        to be available via :func:`~sf_quant.data.benchmark.load_benchmark`.
+    n_cpus : int, optional
+        Number of CPUs to allocate to Ray. If ``None``, defaults to
+        ``os.cpu_count()`` but is capped at the number of unique dates.
+
+    Returns
+    -------
+    pl.DataFrame
+        A PortfolioSchema-validated Polars DataFrame containing optimized
+        portfolio weights across all backtest dates, with columns:
+
+        - ``date`` : datetime, portfolio date.
+        - ``barrid`` : str, asset identifier.
+        - ``weight`` : float, optimized portfolio weight.
+        - ``gamma`` : float, calibrated risk aversion parameter for each date.
+        - ``active_risk`` : float, achieved annualized active risk for each date.
+
+    Notes
+    -----
+    - Benchmark data is automatically loaded when ``target_active_risk`` is specified,
+      via :func:`~sf_quant.data.benchmark.load_benchmark`.
+    - Ray is initialized with ``ignore_reinit_error=True``, allowing safe
+      re-invocation within the same process.
+
+    See Also
+    --------
+    backtest_parallel : Sequential version without active risk calibration.
+    dynamic_mve_optimizer : Underlying optimizer with active risk calibration.
+
+    Examples
+    --------
+    >>> import sf_quant.data as sfd
+    >>> import sf_quant.backtester as sfb
+    >>> import sf_quant.optimizer as sfo
+    >>> import polars as pl
+    >>> import datetime as dt
+    >>> start = dt.date(2024, 1, 1)
+    >>> end = dt.date(2024, 1, 10)
+    >>> columns = ['date', 'barrid']
+    >>> data = (
+    ...     sfd.load_assets(
+    ...         start=start,
+    ...         end=end,
+    ...         in_universe=True,
+    ...         columns=columns
+    ...     )
+    ...     .with_columns(
+    ...         pl.lit(0).alias('alpha')
+    ...     )
+    ... )
+    >>> constraints = [sfo.FullInvestment()]
+    >>> weights = sfb.dynamic_backtest_parallel(
+    ...     data=data,
+    ...     constraints=constraints,
+    ...     initial_gamma=100,
+    ... )
+    shape: (5, 5)
+    ┌────────────┬─────────┬───────────┬───────┬──────────────┐
+    │ date       ┆ barrid  ┆ weight    ┆ gamma ┆ active_risk  │
+    │ ---        ┆ ---     ┆ ---       ┆ ---   ┆ ---          │
+    │ date       ┆ str     ┆ f64       ┆ f64   ┆ f64          │
+    ╞════════════╪═════════╪═══════════╪═══════╪══════════════╡
+    │ 2024-01-02 ┆ USA06Z1 ┆ -0.000639 ┆ 100.0 ┆ 0.047        │
+    │ 2024-01-02 ┆ USA0771 ┆ -0.000083 ┆ 100.0 ┆ 0.047        │
+    │ 2024-01-02 ┆ USA0C11 ┆ -0.003044 ┆ 100.0 ┆ 0.047        │
+    │ 2024-01-02 ┆ USA0SY1 ┆ -0.002177 ┆ 100.0 ┆ 0.047        │
+    │ 2024-01-02 ┆ USA11I1 ┆ 0.001475  ┆ 100.0 ┆ 0.047        │
+    └────────────┴─────────┴───────────┴───────┴──────────────┘
+    """
+    # Get dates
+    dates = data["date"].unique().sort().to_list()
+
+    start_date = dates[0]
+    end_date = dates[-1]
+    benchmark_df = load_benchmark(start_date, end_date).rename({"weight": "benchmark_weight"})
+
+    # Set up ray
+    n_cpus = n_cpus or os.cpu_count()
+    n_cpus = min(len(dates), n_cpus)
+    # Empty runtime_env = no environment management. Workers use parent's Python directly.
+    # This prevents Ray from trying to serialize code or rebuild packages on air-gapped clusters.
+    ray.init(ignore_reinit_error=True, num_cpus=n_cpus, runtime_env={})
+
+    # Set up ray progress bar
+    remote_tqdm = ray.remote(tqdm_ray.tqdm)
+    progress_bar = remote_tqdm.remote(
+        total=len(dates), desc=f"Computing portfolios with {n_cpus} cpus"
+    )
+
+    # Dispatch parallel tasks
+    portfolio_futures = [
+        _construct_portfolio.remote(
+            date_=date_,
+            data=data,
+            constraints=constraints,
+            gamma=initial_gamma,
+            target_active_risk=target_active_risk,
+            benchmark_df=benchmark_df,
+            progress_bar=progress_bar,
+        )
+        for date_ in dates
+    ]
+
+    portfolio_list = ray.get(portfolio_futures)
+
+    progress_bar.close.remote()
+    ray.shutdown()
+
+    return pl.concat(portfolio_list)

{sf_quant-0.2.0 → sf_quant-0.2.2}/src/sf_quant/backtester/parallel.py

@@ -3,7 +3,7 @@ import os
 import ray
 import datetime as dt
 from ray.experimental import tqdm_ray
-from sf_quant.data.covariance_matrix import construct_covariance_matrix
+from sf_quant.data.covariance_matrix import construct_factor_model_components
 from sf_quant.optimizer.optimizers import mve_optimizer
 from sf_quant.optimizer.constraints import Constraint
 from sf_quant.schema.portfolio_schema import PortfolioSchema
@@ -17,6 +17,31 @@ def _construct_portfolio(
     gamma: float,
     progress_bar: tqdm_ray.tqdm | None = None,
 ):
+    """
+    Construct a single optimized portfolio for a given date.
+
+    This is a Ray-remote helper function for parallel portfolio construction.
+    It filters data to a specific date, constructs the factor model components,
+    and solves a mean-variance optimization problem.
+
+    Parameters
+    ----------
+    date_ : dt.date
+        The date for which to construct the portfolio.
+    data : pl.DataFrame
+        Full dataset with columns 'date', 'barrid', 'alpha', optionally 'predicted_beta'.
+    constraints : list[Constraint]
+        Portfolio constraints to enforce.
+    gamma : float
+        Risk aversion parameter.
+    progress_bar : tqdm_ray.tqdm, optional
+        Ray-based progress bar for tracking completion.
+
+    Returns
+    -------
+    pl.DataFrame
+        Portfolio weights for the given date, with columns 'date', 'barrid', 'weight'.
+    """
     subset = data.filter(pl.col("date").eq(date_)).sort("barrid")
     barrids = subset["barrid"].to_list()
     alphas = subset["alpha"].to_numpy()
@@ -27,14 +52,18 @@ def _construct_portfolio(
         else None
     )
 
-    covariance_matrix = (
-        construct_covariance_matrix(date_, barrids).drop("barrid").to_numpy()
-    )
+    (
+        factor_exposures,
+        factor_covariance,
+        specific_risk,
+    ) = construct_factor_model_components(date_, barrids)
 
     portfolio = mve_optimizer(
         ids=barrids,
         alphas=alphas,
-        covariance_matrix=covariance_matrix,
+        factor_exposures=factor_exposures,
+        factor_covariance=factor_covariance,
+        specific_risk=specific_risk,
         gamma=gamma,
         constraints=constraints,
         betas=betas,
@@ -93,6 +122,18 @@ def backtest_parallel(
         - ``barrid`` : str, asset identifier.
         - ``weight`` : float, optimized portfolio weight.
 
+    Notes
+    -----
+    - Ray is initialized with ``ignore_reinit_error=True``, allowing safe
+      re-invocation within the same process.
+    - The number of CPUs is automatically limited to the number of unique dates
+      to avoid unnecessary idle workers.
+
+    See Also
+    --------
+    backtest_sequential : Sequential version for smaller datasets or debugging.
+    dynamic_backtest_parallel : Parallel version with active risk calibration.
+
     Examples
     --------
     >>> import sf_quant.data as sfd

{sf_quant-0.2.0 → sf_quant-0.2.2}/src/sf_quant/backtester/sequential.py

@@ -1,6 +1,6 @@
 import polars as pl
 import tqdm
-from sf_quant.data.covariance_matrix import construct_covariance_matrix
+from sf_quant.data.covariance_matrix import construct_factor_model_components
 from sf_quant.optimizer.optimizers import mve_optimizer
 from sf_quant.optimizer.constraints import Constraint
 from sf_quant.schema.portfolio_schema import PortfolioSchema
@@ -49,8 +49,14 @@ def backtest_sequential(
     Notes
     -----
     - The optimization is solved using :func:`~sf_quant.optimizer.optimizers.mve_optimizer`.
-    - The covariance matrix is constructed using
-      :func:`~sf_quant.data.covariance_matrix.construct_covariance_matrix`.
+    - The factor model components are constructed using
+      :func:`~sf_quant.data.covariance_matrix.construct_factor_model_components`.
+    - Results are validated against :class:`~sf_quant.schema.portfolio_schema.PortfolioSchema`.
+
+    See Also
+    --------
+    backtest_parallel : Parallelized version using Ray for faster execution.
+    dynamic_backtest_parallel : Parallel version with active risk calibration.
 
     Examples
     --------
@@ -112,14 +118,18 @@ def backtest_sequential(
             else None
         )
 
-        covariance_matrix = (
-            construct_covariance_matrix(date_, barrids).drop("barrid").to_numpy()
-        )
+        (
+            factor_exposures,
+            factor_covariance,
+            specific_risk,
+        ) = construct_factor_model_components(date_, barrids)
 
         portfolio = mve_optimizer(
             ids=barrids,
             alphas=alphas,
-            covariance_matrix=covariance_matrix,
+            factor_exposures=factor_exposures,
+            factor_covariance=factor_covariance,
+            specific_risk=specific_risk,
             gamma=gamma,
             constraints=constraints,
             betas=betas,

{sf_quant-0.2.0 → sf_quant-0.2.2}/src/sf_quant/data/__init__.py

@@ -13,10 +13,13 @@ from .crsp_monthly import load_crsp_monthly, get_crsp_monthly_columns
 from .crsp_v2_monthly import load_crsp_v2_monthly, get_crsp_v2_monthly_columns
 from .exposures import load_exposures, load_exposures_by_date, get_exposures_columns
 from .covariances import load_covariances_by_date, get_covariances_columns
-from .covariance_matrix import construct_covariance_matrix
+from .covariance_matrix import construct_covariance_matrix, construct_factor_model_components
 from .benchmark import load_benchmark, load_benchmark_returns
 from .factors import load_factors, get_factors_columns, get_factor_names
 from .fama_french import load_fama_french, get_fama_french_columns
+from .signals import load_signals, load_signals_by_date
+from .scores import load_scores, load_scores_by_date
+from .alphas import load_alphas, load_alphas_by_date, load_combined_alphas, load_combined_alphas_by_date
 
 __all__ = [
     "env",
@@ -38,6 +41,7 @@ __all__ = [
     "load_covariances_by_date",
     "get_covariances_columns",
     "construct_covariance_matrix",
+    "construct_factor_model_components",
     "load_benchmark",
     "load_benchmark_returns",
     "load_factors",
@@ -45,4 +49,12 @@ __all__ = [
     "get_factor_names",
     "load_fama_french",
     "get_fama_french_columns",
+    "load_signals",
+    "load_signals_by_date",
+    "load_scores",
+    "load_scores_by_date",
+    "load_alphas",
+    "load_alphas_by_date",
+    "load_combined_alphas",
+    "load_combined_alphas_by_date",
 ]

{sf_quant-0.2.0 → sf_quant-0.2.2}/src/sf_quant/data/_tables.py

@@ -56,3 +56,8 @@ exposures_table = Table("exposures")
 covariances_table = Table("covariances")
 factors_table = Table("factors")
 ff_table = FamaFrenchTable("ff5_factors")
+signals_table = Table("signals")
+scores_table = Table("scores")
+alphas_table = Table("alphas")
+combined_alphas_table = Table("combined_alphas")
+optimal_weights_table = Table("optimal_weights")