Merge branch 'main' into rawdf

Optimizing `bdates` utils

notebooks/funcwise/bdate_range_util.ipynb

@@ -0,0 +1,360 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ! uv pip install E:\\Work\\ruzt\\msyrs --upgrade"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Import Python packages\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import macrosynergy\n",
+    "import pandas as pd\n",
+    "import numpy as np\n",
+    "import polars as pl\n",
+    "import os\n",
+    "import time\n",
+    "\n",
+    "from macrosynergy.panel import view_timelines\n",
+    "from macrosynergy.management.types import QuantamentalDataFrame\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Import Python bindings - `msyrs`\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import msyrs"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<div>\n",
+       "<style scoped>\n",
+       "    .dataframe tbody tr th:only-of-type {\n",
+       "        vertical-align: middle;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe tbody tr th {\n",
+       "        vertical-align: top;\n",
+       "    }\n",
+       "\n",
+       "    .dataframe thead th {\n",
+       "        text-align: right;\n",
+       "    }\n",
+       "</style>\n",
+       "<table border=\"1\" class=\"dataframe\">\n",
+       "  <thead>\n",
+       "    <tr style=\"text-align: right;\">\n",
+       "      <th></th>\n",
+       "      <th>bdates</th>\n",
+       "      <th>0</th>\n",
+       "    </tr>\n",
+       "  </thead>\n",
+       "  <tbody>\n",
+       "    <tr>\n",
+       "      <th>0</th>\n",
+       "      <td>2000-01-03</td>\n",
+       "      <td>2000-01-03</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1</th>\n",
+       "      <td>2000-01-10</td>\n",
+       "      <td>2000-01-10</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>2</th>\n",
+       "      <td>2000-01-17</td>\n",
+       "      <td>2000-01-17</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>3</th>\n",
+       "      <td>2000-01-24</td>\n",
+       "      <td>2000-01-24</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>4</th>\n",
+       "      <td>2000-01-31</td>\n",
+       "      <td>2000-01-31</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>...</th>\n",
+       "      <td>...</td>\n",
+       "      <td>...</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1056</th>\n",
+       "      <td>2020-03-30</td>\n",
+       "      <td>2020-03-30</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1057</th>\n",
+       "      <td>2020-04-06</td>\n",
+       "      <td>2020-04-06</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1058</th>\n",
+       "      <td>2020-04-13</td>\n",
+       "      <td>2020-04-13</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1059</th>\n",
+       "      <td>2020-04-20</td>\n",
+       "      <td>2020-04-20</td>\n",
+       "    </tr>\n",
+       "    <tr>\n",
+       "      <th>1060</th>\n",
+       "      <td>2020-04-27</td>\n",
+       "      <td>2020-04-27</td>\n",
+       "    </tr>\n",
+       "  </tbody>\n",
+       "</table>\n",
+       "<p>1061 rows × 2 columns</p>\n",
+       "</div>"
+      ],
+      "text/plain": [
+       "         bdates          0\n",
+       "0    2000-01-03 2000-01-03\n",
+       "1    2000-01-10 2000-01-10\n",
+       "2    2000-01-17 2000-01-17\n",
+       "3    2000-01-24 2000-01-24\n",
+       "4    2000-01-31 2000-01-31\n",
+       "...         ...        ...\n",
+       "1056 2020-03-30 2020-03-30\n",
+       "1057 2020-04-06 2020-04-06\n",
+       "1058 2020-04-13 2020-04-13\n",
+       "1059 2020-04-20 2020-04-20\n",
+       "1060 2020-04-27 2020-04-27\n",
+       "\n",
+       "[1061 rows x 2 columns]"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "x = msyrs.utils.get_bdates_series_default_opt(start_date='2000-01-01', end_date='2020-05-01', freq='W').to_pandas()\n",
+    "y = pd.Series(pd.bdate_range(start='2000-01-01', end='2020-05-01', freq='W-MON'))\n",
+    "\n",
+    "pd.concat([x, y], axis=1)\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Results for M\t & \tBMS\t are exactly the same\n",
+      "Results for Q\t & \tBQS\t are exactly the same\n",
+      "Results for W\t & \tW-MON\t are exactly the same\n",
+      "Results for WF\t & \tW-FRI\t are exactly the same\n"
+     ]
+    }
+   ],
+   "source": [
+    "for rs_freq, pd_freq in [('M', 'BMS'), ('Q', 'BQS'), ('W', 'W-MON'), ('WF', 'W-FRI')]:\n",
+    "\n",
+    "\n",
+    "    x = msyrs.utils.get_bdates_series_default_opt(start_date='2000-01-01', end_date='2020-05-01', freq=rs_freq).to_pandas()\n",
+    "    y = pd.Series(pd.bdate_range(start='2000-01-01', end='2020-05-01', freq=pd_freq))\n",
+    "\n",
+    "    e = x  == y\n",
+    "    res = e.all()\n",
+    "    non_matching_df = pd.concat([x[~e], y[~e]], axis=1)\n",
+    "    assert res, f\"Results for {rs_freq}\\t and \\t{pd_freq}\\t are not the same\\n{non_matching_df}\"\n",
+    "    print(f\"Results for {rs_freq}\\t & \\t{pd_freq}\\t are exactly the same\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "23.5 μs ± 1.02 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)\n",
+      "67.4 μs ± 979 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)\n",
+      "1.97 ms ± 57.3 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)\n",
+      "4.65 ms ± 170 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n",
+      "28.3 ms ± 898 μs per loop (mean ± std. dev. of 7 runs, 10 loops each)\n",
+      "93.8 ms ± 2.02 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='2000-01-01', end_date='2020-05-01', freq='D')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='1971-01-01', end_date='2040-05-01', freq='D')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='2000-01-01', end_date='2020-05-01', freq='D')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='1971-01-01', end_date='2040-05-01', freq='D')\n",
+    "%timeit pd.bdate_range(start='2000-01-01', end='2020-05-01', freq='B')\n",
+    "%timeit pd.bdate_range(start='1971-01-01', end='2040-05-01', freq='B')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "7.95 μs ± 146 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)\n",
+      "17.9 μs ± 108 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)\n",
+      "1.73 ms ± 20.8 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)\n",
+      "4 ms ± 69.3 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n",
+      "5.69 ms ± 139 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n",
+      "19.1 ms ± 268 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='2000-01-01', end_date='2020-05-01', freq='WF')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='1971-01-01', end_date='2040-05-01', freq='WF')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='2000-01-01', end_date='2020-05-01', freq='WF')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='1971-01-01', end_date='2040-05-01', freq='WF')\n",
+    "%timeit pd.bdate_range(start='2000-01-01', end='2020-05-01', freq='W-FRI')\n",
+    "%timeit pd.bdate_range(start='1971-01-01', end='2040-05-01', freq='W-FRI')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "6.9 μs ± 126 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)\n",
+      "13.1 μs ± 93.3 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)\n",
+      "1.73 ms ± 29.3 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)\n",
+      "4.2 ms ± 81.5 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n",
+      "931 μs ± 14.2 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)\n",
+      "3.05 ms ± 47.5 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='2000-01-01', end_date='2020-05-01', freq='ME')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='1971-01-01', end_date='2040-05-01', freq='ME')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='2000-01-01', end_date='2020-05-01', freq='ME')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='1971-01-01', end_date='2040-05-01', freq='ME')\n",
+    "%timeit pd.bdate_range(start='2000-01-01', end='2020-05-01', freq='BME')\n",
+    "%timeit pd.bdate_range(start='1971-01-01', end='2040-05-01', freq='BME')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "3.65 μs ± 69.1 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)\n",
+      "4.78 μs ± 38.7 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)\n",
+      "1.73 ms ± 122 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)\n",
+      "4.16 ms ± 286 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n",
+      "340 μs ± 11.3 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)\n",
+      "1.1 ms ± 11.5 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='2000-01-01', end_date='2020-05-01', freq='Q')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='1971-01-01', end_date='2040-05-01', freq='Q')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='2000-01-01', end_date='2020-05-01', freq='Q')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='1971-01-01', end_date='2040-05-01', freq='Q')\n",
+    "%timeit pd.bdate_range(start='2000-01-01', end='2020-05-01', freq='BQS')\n",
+    "%timeit pd.bdate_range(start='1971-01-01', end='2040-05-01', freq='BQS')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "3.21 μs ± 83.4 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)\n",
+      "3.66 μs ± 198 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)\n",
+      "2.67 ms ± 459 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n",
+      "3.71 ms ± 143 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n",
+      "98.7 μs ± 1.47 μs per loop (mean ± std. dev. of 7 runs, 10,000 loops each)\n",
+      "289 μs ± 15.3 μs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)\n"
+     ]
+    }
+   ],
+   "source": [
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='2000-01-01', end_date='2020-05-01', freq='YE')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_opt(start_date='1971-01-01', end_date='2040-05-01', freq='YE')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='2000-01-01', end_date='2020-05-01', freq='YE')\n",
+    "%timeit msyrs.utils.get_bdates_series_default_pl(start_date='1971-01-01', end_date='2040-05-01', freq='YE')\n",
+    "%timeit pd.bdate_range(start='2000-01-01', end='2020-05-01', freq='BYE')\n",
+    "%timeit pd.bdate_range(start='1971-01-01', end='2040-05-01', freq='BYE')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

src/_py/utils.rs

@@ -5,18 +5,31 @@ use pyo3_polars::{PyDataFrame, PySeries};
 #[allow(deprecated)]
 #[pymodule]
 pub fn utils(_py: Python, m: &PyModule) -> PyResult<()> {
-    m.add_function(wrap_pyfunction!(get_bdates_series_default, m)?)?;
+    m.add_function(wrap_pyfunction!(get_bdates_series_default_pl, m)?)?;
+    m.add_function(wrap_pyfunction!(get_bdates_series_default_opt, m)?)?;
     Ok(())
 }
 
 #[pyfunction]
-pub fn get_bdates_series_default(
+pub fn get_bdates_series_default_pl(
     start_date: String,
     end_date: String,
     freq: Option<String>,
 ) -> PyResult<PySeries> {
     Ok(PySeries(
-        crate::utils::dateutils::get_bdates_series_default(start_date, end_date, freq)
+        crate::utils::dateutils::get_bdates_series_default_pl(start_date, end_date, freq)
+            .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(format!("{}", e)))?,
+    ))
+}
+
+#[pyfunction]
+pub fn get_bdates_series_default_opt(
+    start_date: String,
+    end_date: String,
+    freq: Option<String>,
+) -> PyResult<PySeries> {
+    Ok(PySeries(
+        crate::utils::dateutils::get_bdates_series_default_opt(start_date, end_date, freq)
             .map_err(|e| PyErr::new::<pyo3::exceptions::PyValueError, _>(format!("{}", e)))?,
     ))
 }

src/core/dateseries.rs

@@ -0,0 +1,281 @@
+//! # DateSeries and BDateSeries Implementations
+//!
+//! This module provides two date-handling types using the [`chrono`](https://docs.rs/chrono) crate:
+//!
+//! - [`DateSeries`]: Stores any set of calendar dates and allows adding/subtracting *calendar days*.
+//! - [`BDateSeries`]: Stores only Monday–Friday business days and interprets add/sub as *business day* shifts,
+//!   skipping weekends (e.g., adding 1 to Friday goes to Monday).
+//!
+//! Both types also provide a [`from_iso8601_range`](#method.from_iso8601_range) constructor
+//! that builds a date series (or business‑date series) from a start/end string (YYYY‑MM‑DD).
+
+use chrono::{Datelike, Duration, NaiveDate, ParseResult};
+use std::ops::{Add, Sub};
+
+/// Determines if the date is Saturday or Sunday.
+fn is_weekend(date: NaiveDate) -> bool {
+    matches!(date.weekday(), chrono::Weekday::Sat | chrono::Weekday::Sun)
+}
+
+/// A `DateSeries` stores a list of [`NaiveDate`] values and shifts by **calendar days**.
+///
+/// ## Example Usage
+///
+/// ```
+/// use chrono::NaiveDate;
+/// use msyrs::core::dateseries::DateSeries;
+///
+/// // Create from explicit dates
+/// let ds = DateSeries::new(vec![
+///     NaiveDate::from_ymd_opt(2023, 7, 14).unwrap(), // a Friday
+///     NaiveDate::from_ymd_opt(2023, 7, 15).unwrap(), // a Saturday
+/// ]);
+///
+/// // Shift forward by 5 calendar days
+/// let ds_plus = ds + 5;
+/// // 2023-07-14 + 5 => 2023-07-19 (Wednesday)
+/// // 2023-07-15 + 5 => 2023-07-20 (Thursday)
+///
+/// assert_eq!(ds_plus.data()[0], NaiveDate::from_ymd_opt(2023, 7, 19).unwrap());
+/// assert_eq!(ds_plus.data()[1], NaiveDate::from_ymd_opt(2023, 7, 20).unwrap());
+/// ```
+///
+#[derive(Debug, Clone)]
+pub struct DateSeries {
+    data: Vec<NaiveDate>,
+}
+
+impl DateSeries {
+    /// Creates a new `DateSeries` from a vector of [`NaiveDate`] values.
+    ///
+    /// # Panics
+    /// - Does not panic on invalid weekend or anything; this type accepts all valid dates.
+    pub fn new(data: Vec<NaiveDate>) -> Self {
+        Self { data }
+    }
+
+    /// Constructs a `DateSeries` by parsing an ISO‑8601 start/end string (YYYY‑MM‑DD)
+    /// and including **every calendar date** from start to end (inclusive).
+    ///
+    /// # Errors
+    /// - Returns a [`chrono::ParseError`](chrono::ParseError) if parsing fails.
+    /// - Panics if `start` > `end` chronologically.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use msyrs::core::dateseries::DateSeries;
+    /// # fn main() -> Result<(), chrono::ParseError> {
+    /// let ds = DateSeries::from_iso8601_range("2023-07-14", "2023-07-16")?;
+    /// assert_eq!(ds.data().len(), 3);
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn from_iso8601_range(start: &str, end: &str) -> ParseResult<Self> {
+        let start_date = NaiveDate::parse_from_str(start, "%Y-%m-%d")?;
+        let end_date = NaiveDate::parse_from_str(end, "%Y-%m-%d")?;
+        assert!(
+            start_date <= end_date,
+            "start date cannot be after end date"
+        );
+
+        let mut dates = Vec::new();
+        let mut current = start_date;
+        while current <= end_date {
+            dates.push(current);
+            current = current
+                .checked_add_signed(Duration::days(1))
+                .expect("Date overflow in from_iso8601_range");
+        }
+        Ok(Self::new(dates))
+    }
+
+    /// Returns a reference to the underlying slice of dates.
+    pub fn data(&self) -> &[NaiveDate] {
+        &self.data
+    }
+
+    /// Internal helper applying a function to each date.
+    fn apply<F>(&self, op: F) -> Self
+    where
+        F: Fn(NaiveDate) -> NaiveDate,
+    {
+        let new_data = self.data.iter().map(|&date| op(date)).collect();
+        Self { data: new_data }
+    }
+}
+
+/// Implements adding calendar days to each `NaiveDate`.
+///
+/// If the shifted date goes out of chrono's valid range, it panics.
+impl Add<i64> for DateSeries {
+    type Output = Self;
+
+    fn add(self, rhs: i64) -> Self::Output {
+        self.apply(|date| {
+            date.checked_add_signed(Duration::days(rhs))
+                .expect("Overflow in date addition")
+        })
+    }
+}
+
+/// Implements subtracting calendar days from each `NaiveDate`.
+///
+/// If the shifted date goes out of chrono's valid range, it panics.
+impl Sub<i64> for DateSeries {
+    type Output = Self;
+
+    fn sub(self, rhs: i64) -> Self::Output {
+        self.apply(|date| {
+            date.checked_sub_signed(Duration::days(rhs))
+                .expect("Overflow in date subtraction")
+        })
+    }
+}
+
+/// A “Business Date Series” for Monday–Friday only.
+///
+/// 1. The constructor disallows weekend dates (panics if any date is Sat/Sun).  
+/// 2. Adding or subtracting an `i64` interprets that integer as *business days*, skipping weekends.
+///    For example, adding 1 to a Friday yields the following Monday.
+///
+/// ## Example Usage
+///
+/// ```
+/// use chrono::NaiveDate;
+/// use msyrs::core::dateseries::BDateSeries;
+///
+/// // Friday
+/// let friday = NaiveDate::from_ymd_opt(2023, 7, 14).unwrap();
+/// let mut bds = BDateSeries::new(vec![friday]);
+///
+/// // Adding 1 “business day” => next Monday, 2023-07-17
+/// bds = bds + 1;
+/// assert_eq!(bds.data()[0], NaiveDate::from_ymd_opt(2023, 7, 17).unwrap());
+/// ```
+#[derive(Debug, Clone)]
+pub struct BDateSeries {
+    data: Vec<NaiveDate>,
+}
+
+impl BDateSeries {
+    /// Creates a new `BDateSeries`, panicking if any of the supplied dates is on Saturday/Sunday.
+    pub fn new(data: Vec<NaiveDate>) -> Self {
+        for &d in &data {
+            if is_weekend(d) {
+                panic!("BDateSeries cannot contain weekend dates: {}", d);
+            }
+        }
+        Self { data }
+    }
+
+    /// Constructs a `BDateSeries` by parsing an ISO‑8601 start/end string (YYYY‑MM‑DD).
+    ///
+    /// Only Monday–Friday dates within `[start, end]` are included in the series.  
+    ///
+    /// # Errors
+    /// - Returns a [`chrono::ParseError`](chrono::ParseError) if parsing fails.
+    /// - Panics if `start` > `end` chronologically.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use msyrs::core::dateseries::BDateSeries;
+    /// # fn main() -> Result<(), chrono::ParseError> {
+    /// let bds = BDateSeries::from_iso8601_range("2023-07-14", "2023-07-18")?;
+    /// // 2023-07-14 (Friday), 2023-07-15 (Saturday) => skipped,
+    /// // 2023-07-16 (Sunday) => skipped,
+    /// // 2023-07-17 (Monday), 2023-07-18 (Tuesday)
+    /// // so total 3 valid business days
+    /// assert_eq!(bds.data().len(), 3);
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn from_iso8601_range(start: &str, end: &str) -> ParseResult<Self> {
+        let start_date = NaiveDate::parse_from_str(start, "%Y-%m-%d")?;
+        let end_date = NaiveDate::parse_from_str(end, "%Y-%m-%d")?;
+        assert!(
+            start_date <= end_date,
+            "start date cannot be after end date"
+        );
+
+        let mut dates = Vec::new();
+        let mut current = start_date;
+        while current <= end_date {
+            if !is_weekend(current) {
+                dates.push(current);
+            }
+            current = current
+                .checked_add_signed(Duration::days(1))
+                .expect("Date overflow in from_iso8601_range");
+        }
+        Ok(Self::new(dates))
+    }
+
+    /// Returns a reference to the underlying slice of dates.
+    pub fn data(&self) -> &[NaiveDate] {
+        &self.data
+    }
+
+    /// Internal helper that tries to shift a date forward or backward by one day at a time,
+    /// skipping weekends, for a total of `delta` business days.
+    fn shift_business_days(date: NaiveDate, delta: i64) -> NaiveDate {
+        if delta == 0 {
+            return date;
+        }
+
+        let step = if delta > 0 { 1 } else { -1 };
+        let abs_delta = delta.abs();
+
+        let mut new_date = date;
+        for _ in 0..abs_delta {
+            // Move by 1 day in the correct direction
+            new_date = new_date
+                .checked_add_signed(Duration::days(step))
+                .expect("Overflow in BDateSeries add/sub");
+            // If we land on weekend, keep moving until Monday..Friday
+            while is_weekend(new_date) {
+                new_date = new_date
+                    .checked_add_signed(Duration::days(step))
+                    .expect("Overflow in BDateSeries skipping weekend");
+            }
+        }
+        new_date
+    }
+
+    /// Internal helper to apply a shift of `delta` business days to each date.
+    fn apply(&self, delta: i64) -> Self {
+        let new_data = self
+            .data
+            .iter()
+            .map(|&date| Self::shift_business_days(date, delta))
+            .collect();
+        Self { data: new_data }
+    }
+}
+
+/// Implement *business day* addition for `BDateSeries`.
+///
+/// # Panics
+/// - If the resulting date(s) overflow `NaiveDate` range.
+/// - `BDateSeries` is guaranteed to remain Monday..Friday after the shift.
+impl Add<i64> for BDateSeries {
+    type Output = Self;
+
+    fn add(self, rhs: i64) -> Self::Output {
+        self.apply(rhs)
+    }
+}
+
+/// Implement *business day* subtraction for `BDateSeries`.
+///
+/// # Panics
+/// - If the resulting date(s) overflow `NaiveDate`.
+/// - `BDateSeries` is guaranteed to remain Monday..Friday after the shift.
+impl Sub<i64> for BDateSeries {
+    type Output = Self;
+
+    fn sub(self, rhs: i64) -> Self::Output {
+        self.apply(-rhs)
+    }
+}

src/core/mod.rs

@@ -0,0 +1,3 @@
+pub mod df;
+pub mod xseries;
+pub mod dateseries;

src/core/xseries.rs

@@ -0,0 +1,223 @@
+use std::ops::{Add, Div, Mul, Sub};
+
+//
+// 1) Define a float series: FSeries
+//
+
+#[derive(Debug, Clone)]
+pub struct FSeries {
+    data: Vec<f64>,
+}
+
+impl FSeries {
+    /// Create a new FSeries from a vector of f64 values.
+    pub fn new(data: Vec<f64>) -> Self {
+        Self { data }
+    }
+
+    pub fn len(&self) -> usize {
+        self.data.len()
+    }
+
+    /// Element‑wise helper applying an operation between two FSeries.
+    pub fn apply<F>(&self, other: &Self, op: F) -> Self
+    where
+        F: Fn(f64, f64) -> f64,
+    {
+        assert!(
+            self.len() == other.len(),
+            "FSeries must have the same length to apply operations."
+        );
+        let data = self
+            .data
+            .iter()
+            .zip(other.data.iter())
+            .map(|(&a, &b)| op(a, b))
+            .collect();
+        FSeries { data }
+    }
+
+    /// Access to the underlying data
+    pub fn data(&self) -> &[f64] {
+        &self.data
+    }
+}
+
+// Macros for float series arithmetic (element‑wise)
+macro_rules! impl_fseries_bin_op {
+    ($trait:ident, $method:ident, $op:tt) => {
+        impl $trait for FSeries {
+            type Output = Self;
+
+            fn $method(self, rhs: Self) -> Self::Output {
+                self.apply(&rhs, |a, b| a $op b)
+            }
+        }
+    };
+}
+
+impl_fseries_bin_op!(Add, add, +);
+impl_fseries_bin_op!(Sub, sub, -);
+impl_fseries_bin_op!(Mul, mul, *);
+impl_fseries_bin_op!(Div, div, /);
+
+macro_rules! impl_fseries_scalar_op {
+    ($trait:ident, $method:ident, $op:tt) => {
+        impl $trait<f64> for FSeries {
+            type Output = Self;
+
+            fn $method(mut self, scalar: f64) -> Self::Output {
+                for x in self.data.iter_mut() {
+                    *x = *x $op scalar;
+                }
+                self
+            }
+        }
+    };
+}
+
+impl_fseries_scalar_op!(Add, add, +);
+impl_fseries_scalar_op!(Sub, sub, -);
+impl_fseries_scalar_op!(Mul, mul, *);
+impl_fseries_scalar_op!(Div, div, /);
+
+//
+// 2) Define an integer series: ISeries
+//
+
+#[derive(Debug, Clone)]
+pub struct ISeries {
+    data: Vec<i64>,
+}
+
+impl ISeries {
+    /// Create an ISeries from a vector of i64 values.
+    pub fn new(data: Vec<i64>) -> Self {
+        Self { data }
+    }
+
+    pub fn len(&self) -> usize {
+        self.data.len()
+    }
+
+    pub fn data(&self) -> &[i64] {
+        &self.data
+    }
+
+    /// Element‑wise helper for integer series.
+    pub fn apply<F>(&self, other: &Self, op: F) -> Self
+    where
+        F: Fn(i64, i64) -> i64,
+    {
+        assert!(
+            self.len() == other.len(),
+            "ISeries must have the same length to apply operations."
+        );
+        let data = self
+            .data
+            .iter()
+            .zip(other.data.iter())
+            .map(|(&a, &b)| op(a, b))
+            .collect();
+        ISeries { data }
+    }
+}
+
+// Macros for integer series arithmetic (element‑wise)
+macro_rules! impl_iseries_bin_op {
+    ($trait:ident, $method:ident, $op:tt) => {
+        impl $trait for ISeries {
+            type Output = Self;
+
+            fn $method(self, rhs: Self) -> Self::Output {
+                self.apply(&rhs, |a, b| a $op b)
+            }
+        }
+    };
+}
+
+impl_iseries_bin_op!(Add, add, +);
+impl_iseries_bin_op!(Sub, sub, -);
+impl_iseries_bin_op!(Mul, mul, *);
+impl_iseries_bin_op!(Div, div, /); // integer division (floor trunc)
+
+// Optional scalar operations (for i64)
+macro_rules! impl_iseries_scalar_op {
+    ($trait:ident, $method:ident, $op:tt) => {
+        impl $trait<i64> for ISeries {
+            type Output = Self;
+
+            fn $method(mut self, scalar: i64) -> Self::Output {
+                for x in self.data.iter_mut() {
+                    *x = *x $op scalar;
+                }
+                self
+            }
+        }
+    };
+}
+
+impl_iseries_scalar_op!(Add, add, +);
+impl_iseries_scalar_op!(Sub, sub, -);
+impl_iseries_scalar_op!(Mul, mul, *);
+impl_iseries_scalar_op!(Div, div, /); // floor/trunc division by scalar
+
+/// A boolean series: BSeries
+///
+#[derive(Debug, Clone)]
+pub struct BSeries {
+    data: Vec<bool>,
+}
+
+impl BSeries {
+    pub fn new(data: Vec<bool>) -> Self {
+        Self { data }
+    }
+
+    pub fn len(&self) -> usize {
+        self.data.len()
+    }
+
+    pub fn data(&self) -> &[bool] {
+        &self.data
+    }
+}
+
+/// Convert an FSeries to ISeries by truncation (floor cast).
+impl From<FSeries> for ISeries {
+    fn from(fseries: FSeries) -> Self {
+        let data = fseries
+            .data
+            .into_iter()
+            .map(|val| val as i64) // trunc cast
+            .collect();
+        ISeries::new(data)
+    }
+}
+
+/// Implement conversion from ISeries to FSeries by casting to f64.
+impl From<ISeries> for FSeries {
+    fn from(iseries: ISeries) -> Self {
+        let data = iseries.data.into_iter().map(|val| val as f64).collect();
+        FSeries::new(data)
+    }
+}
+
+/// Convert an ISeries to BSeries by checking if each value is non-zero.
+impl From<ISeries> for BSeries {
+    fn from(iseries: ISeries) -> Self {
+        let data = iseries.data.into_iter().map(|val| val != 0).collect();
+        BSeries::new(data)
+    }
+}
+
+impl From<BSeries> for ISeries {
+    fn from(bseries: BSeries) -> Self {
+        let data = bseries
+            .data
+            .into_iter()
+            .map(|val| if val { 1 } else { 0 })
+            .collect();
+        ISeries::new(data)
+    }
+}

src/download/jpmaqsdownload.rs

@@ -102,7 +102,7 @@ impl Default for JPMaQSDownloadGetIndicatorArgs {
 /// Struct for downloading data from the JPMaQS data from JPMorgan DataQuery API.
 ///
 /// ## Example Usage
-/// ```rust
+/// ```ignore
 /// use msyrs::download::jpmaqsdownload::JPMaQSDownload;
 /// use msyrs::download::jpmaqsdownload::JPMaQSDownloadGetIndicatorArgs;
 /// use polars::prelude::*;
@@ -140,7 +140,7 @@ impl Default for JPMaQSDownloadGetIndicatorArgs {
 ///    Ok(_) => println!("Saved indicators to disk"),
 ///   Err(e) => println!("Error saving indicators: {:?}", e),
 /// }
-///
+/// ```
 #[derive(Debug, Clone)]
 pub struct JPMaQSDownload {
     requester: DQRequester,
@@ -277,7 +277,7 @@ impl JPMaQSDownload {
     ///  
     /// Usage:
     ///
-    /// ```rust
+    /// ```ignore
     /// use msyrs::download::jpmaqsdownload::JPMaQSDownload;
     /// use msyrs::download::jpmaqsdownload::JPMaQSDownloadGetIndicatorArgs;
     /// let mut jpamqs_download = JPMaQSDownload::default();

src/lib.rs

@@ -1,4 +1,5 @@
 // #![doc = include_str!("../README.md")]
+// uncomment the above line to include the README.md file in the documentation
 
 //! # msyrs
 //!
@@ -18,6 +19,9 @@
 /// Documentation and type-stubs for the `msyrs` Python API.
 pub mod _py;
 
+/// Implementation for the `core` module.
+pub mod core;
+
 /// Implementation for the `download` module.
 pub mod download;
 

src/msyrs.pyi

@@ -51,6 +51,8 @@ class panel:
     def linear_composite(*args, **kwargs) -> DataFrame: ...
 
 class utils:
-    __all__ = ["get_bdates_series_default"]
+    __all__ = ["get_bdates_series_default", "get_bdates_series_default_opt"]
     @staticmethod
-    def get_bdates_series_default(*args, **kwargs) -> Series: ...
+    def get_bdates_series_default_pl(*args, **kwargs) -> Series: ...
+    @staticmethod
+    def get_bdates_series_default_opt(*args, **kwargs) -> Series: ...

src/utils/dateutils.rs

@@ -1,4 +1,4 @@
-use crate::utils::bdates::get_bdates_list_with_freq;
+use crate::utils::bdates;
 use crate::utils::bdates::BDateFreq;
 use chrono::NaiveDate;
 use chrono::{Datelike, Weekday};
@@ -36,25 +36,110 @@ pub fn get_min_max_real_dates(
     }
 }
 
-pub fn get_bdates_series_default(
+/// Get the business dates between two dates.
+pub fn get_bdates_list(
+    start_date: String,
+    end_date: String,
+) -> Result<Vec<NaiveDate>, Box<dyn Error>> {
+    let start_date = NaiveDate::parse_from_str(&start_date, "%Y-%m-%d")?;
+    let end_date = NaiveDate::parse_from_str(&end_date, "%Y-%m-%d")?;
+
+    let mut business_days = Vec::new();
+    let mut current_date = start_date;
+    while current_date <= end_date {
+        // Check if the current date is a business day (not Saturday or Sunday)
+        if current_date.weekday() != Weekday::Sat && current_date.weekday() != Weekday::Sun {
+            business_days.push(current_date);
+        }
+        current_date = current_date.succ_opt().ok_or(format!(
+            "Failed to get the next day for : {:?}",
+            current_date
+        ))?;
+    }
+    Ok(business_days)
+}
+
+fn compute_group_key(d: NaiveDate, freq: BDateFreq) -> String {
+    match freq {
+        // For Daily, each date is its own group.
+        BDateFreq::Daily => format!("{}", d),
+        // For weekly grouping, we use ISO week information.
+        BDateFreq::WeeklyMonday | BDateFreq::WeeklyFriday => {
+            let iso = d.iso_week();
+            format!("{}-W{:02}", iso.year(), iso.week())
+        }
+        // Group by Year-Month.
+        BDateFreq::MonthStart | BDateFreq::MonthEnd => {
+            format!("{}-M{:02}", d.year(), d.month())
+        }
+        // Group by Year-Quarter.
+        BDateFreq::QuarterStart | BDateFreq::QuarterEnd => {
+            let quarter = (d.month() - 1) / 3 + 1;
+            format!("{}-Q{}", d.year(), quarter)
+        }
+        // Group by Year.
+        BDateFreq::YearStart | BDateFreq::YearEnd => format!("{}", d.year()),
+    }
+}
+pub fn get_bdates_series_default_opt(
     start_date: String,
     end_date: String,
     freq: Option<String>,
 ) -> Result<Series, Box<dyn Error>> {
     let freq = freq.unwrap_or_else(|| "D".to_string());
     let freq = BDateFreq::from_str(&freq)?;
-    get_bdates_series(start_date, end_date, freq)
+    let series = Series::new(
+        "bdates".into(),
+        bdates::get_bdates_list_with_freq(&start_date, &end_date, freq)?,
+    );
+    Ok(series)
+}
+
+pub fn get_bdates_series_default_pl(
+    start_date: String,
+    end_date: String,
+    freq: Option<String>,
+) -> Result<Series, Box<dyn Error>> {
+    let freq = freq.unwrap_or_else(|| "D".to_string());
+    let freq = BDateFreq::from_str(&freq)?;
+    get_bdates_series_pl(start_date, end_date, freq)
 }
 
 /// Get the business dates between two dates as a Series.
-pub fn get_bdates_series(
+pub fn get_bdates_series_pl(
     start_date: String,
     end_date: String,
     freq: BDateFreq,
 ) -> Result<Series, Box<dyn Error>> {
-    let bdates_list = get_bdates_list_with_freq(&start_date, &end_date, freq)?;
+    let business_days = get_bdates_list(start_date, end_date)?;
-    let bdates_series = Series::new("bdates".into(), bdates_list);
+    let group_keys: Vec<String> = business_days
-    Ok(bdates_series)
+        .iter()
+        .map(|&d| compute_group_key(d, freq))
+        .collect();
+
+    let df = DataFrame::new(vec![
+        Column::new("bdates".into(), business_days),
+        Column::new("group".into(), group_keys),
+    ])?;
+    let gb = df.lazy().group_by(["group"]);
+    let aggx = match freq.agg_type() {
+        bdates::AggregationType::Start => gb.agg([col("bdates").first()]),
+        bdates::AggregationType::End => gb.agg([col("bdates").last()]),
+    };
+    let result = aggx.collect()?;
+    let result = result
+        .column("bdates")?
+        .as_series()
+        .ok_or("Column 'bdates' not found")?
+        .clone();
+    let result = result.sort(SortOptions {
+        descending: false,
+        nulls_last: false,
+        multithreaded: false,
+        maintain_order: false,
+    })?;
+
+    Ok(result)
 }
 
 /// Get the business dates from a date column in a DataFrame.