refactor: reorganize module exports for clarity

adding blacklist ability
add weight_xcat capability
2025-11-19 20:06:10 +00:00 · 2025-04-14 00:25:23 +01:00 · 2025-04-14 00:25:09 +01:00 · 2025-04-14 00:24:26 +01:00 · 2025-04-14 00:24:02 +01:00 · 2025-04-14 00:22:59 +01:00
12 changed files with 393 additions and 664 deletions
--- a/notebooks/funcwise/linear_composites.ipynb
+++ b/notebooks/funcwise/linear_composites.ipynb
--- a/src/_py/panel.rs
+++ b/src/_py/panel.rs
@@ -68,7 +68,7 @@ pub fn get_period_indices_hv(dfw: PyDataFrame, est_freq: &str) -> PyResult<Vec<u
    cids,
    weights = None,
    signs = None,
-    weight_xcats = None,
+    weight_xcat = None,
    normalize_weights = false,
    start = None,
    end = None,
@@ -84,7 +84,7 @@ pub fn linear_composite(
    cids: Vec<String>,
    weights: Option<Vec<f64>>,
    signs: Option<Vec<f64>>,
-    weight_xcats: Option<Vec<String>>,
+    weight_xcat: Option<String>,
    normalize_weights: bool,
    start: Option<String>,
    end: Option<String>,
@@ -101,7 +101,7 @@ pub fn linear_composite(
            cids,
            weights,
            signs,
-            weight_xcats,
+            weight_xcat,
            normalize_weights,
            start,
            end,
--- a/src/core/dateseries.rs
+++ b/src/core/dateseries.rs
@@ -1,281 +0,0 @@
 //! # 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)
    }
 }
--- a/src/core/df.rs
+++ b/src/core/df.rs
--- a/src/core/mod.rs
+++ b/src/core/mod.rs
@@ -1,3 +0,0 @@
 pub mod df;
 pub mod xseries;
 pub mod dateseries;
--- a/src/core/xseries.rs
+++ b/src/core/xseries.rs
@@ -1,223 +0,0 @@
 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)
    }
 }
--- a/src/download/jpmaqsdownload.rs
+++ b/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
-/// ```ignore
+/// ```rust
 /// 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:
    ///
-    /// ```ignore
+    /// ```rust
    /// use msyrs::download::jpmaqsdownload::JPMaQSDownload;
    /// use msyrs::download::jpmaqsdownload::JPMaQSDownloadGetIndicatorArgs;
    /// let mut jpamqs_download = JPMaQSDownload::default();
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,4 @@
 // #![doc = include_str!("../README.md")]
 // uncomment the above line to include the README.md file in the documentation
 //! # msyrs
 //!
@@ -19,9 +18,6 @@
 /// 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;
--- a/src/panel/historic_vol.rs
+++ b/src/panel/historic_vol.rs
@@ -1,6 +1,6 @@
 use crate::utils::dateutils::{get_bdates_from_col, get_min_max_real_dates};
 use crate::utils::qdf::pivots::*;
-use crate::utils::qdf::reduce_df::*;
+use crate::utils::qdf::reduce_dataframe;
 use chrono::NaiveDate;
 use ndarray::{s, Array, Array1, Zip};
 use polars::prelude::*;
--- a/src/panel/linear_composite.rs
+++ b/src/panel/linear_composite.rs
@@ -1,6 +1,6 @@
 use crate::utils::qdf::check_quantamental_dataframe;
-use crate::utils::qdf::pivots::*;
+use crate::utils::qdf::pivots::{pivot_dataframe_by_ticker, pivot_wide_dataframe_to_qdf};
-use crate::utils::qdf::reduce_df::*;
+use crate::utils::qdf::reduce_df::reduce_dataframe;
 use polars::prelude::*;
 use std::collections::HashMap;
 const TOLERANCE: f64 = 1e-8;
@@ -108,14 +108,42 @@ fn _form_agg_nan_mask_series(nan_mask_dfw: &DataFrame) -> Result<Series, PolarsE
    Ok(combined.into_series())
 }
 /// Form the weights DataFrame
 fn _form_agg_weights_dfw(
-    agg_weights_map: &HashMap<String, Vec<f64>>,
+    agg_weights_map: &HashMap<String, (WeightValue, f64)>,
-    data_dfw: DataFrame,
+    dfw: &DataFrame,
 ) -> Result<DataFrame, PolarsError> {
    let mut weights_dfw = DataFrame::new(vec![])?;
    for (agg_targ, weight_signs) in agg_weights_map.iter() {
-        let wgt = weight_signs[0] * weight_signs[1];
+        // let wgt = weight_signs[0] * weight_signs[1];
-        let wgt_series = Series::new(agg_targ.into(), vec![wgt; data_dfw.height()]);
+        let wgt_series = match &weight_signs.0 {
            WeightValue::F64(val) => {
                let wgt = val * weight_signs.1;
                Series::new(agg_targ.into(), vec![wgt; dfw.height()])
            }
            WeightValue::Str(vstr) => {
                // vstr column from data_dfw, else raise wieght specification error
                if !dfw.get_column_names().contains(&&PlSmallStr::from(vstr)) {
                    return Err(PolarsError::ComputeError(
                        format!(
                            "The column {} does not exist in the DataFrame. {:?}",
                            vstr, agg_weights_map
                        )
                        .into(),
                    ));
                }
                let vstr_series = dfw.column(vstr)?;
                let multiplied_series = vstr_series * weight_signs.1;
                let mut multiplied_series =
                    multiplied_series.as_series().cloned().ok_or_else(|| {
                        PolarsError::ComputeError(
                            "Failed to convert multiplied_series to Series".into(),
                        )
                    })?;
                multiplied_series.rename(agg_targ.into());
                multiplied_series
            }
        };
        weights_dfw.with_column(wgt_series)?;
    }
    Ok(weights_dfw)
@@ -143,14 +171,14 @@ fn perform_single_group_agg(
    dfw: &DataFrame,
    agg_on: &String,
    agg_targs: &Vec<String>,
-    agg_weights_map: &HashMap<String, Vec<f64>>,
+    agg_weights_map: &HashMap<String, (WeightValue, f64)>,
    normalize_weights: bool,
    complete: bool,
 ) -> Result<Column, PolarsError> {
    let data_dfw = _form_agg_data_dfw(dfw, agg_targs)?;
    let nan_mask_dfw = _form_agg_nan_mask_dfw(&data_dfw)?;
    let nan_mask_series = _form_agg_nan_mask_series(&nan_mask_dfw)?;
-    let weights_dfw = _form_agg_weights_dfw(agg_weights_map, data_dfw.clone())?;
+    let weights_dfw = _form_agg_weights_dfw(agg_weights_map, dfw)?;
    let weights_dfw = match normalize_weights {
        true => normalize_weights_with_nan_mask(weights_dfw, nan_mask_dfw)?,
        false => weights_dfw,
@@ -192,7 +220,7 @@ fn perform_single_group_agg(
 fn perform_multiplication(
    dfw: &DataFrame,
    mult_targets: &HashMap<String, Vec<String>>,
-    weights_map: &HashMap<String, HashMap<String, Vec<f64>>>,
+    weights_map: &HashMap<String, HashMap<String, (WeightValue, f64)>>,
    complete: bool,
    normalize_weights: bool,
 ) -> Result<DataFrame, PolarsError> {
@@ -200,6 +228,7 @@ fn perform_multiplication(
    // let mut new_dfw = DataFrame::new(vec![real_date])?;
    let mut new_dfw = DataFrame::new(vec![])?;
    assert!(!mult_targets.is_empty(), "agg_targs is empty");
    for (agg_on, agg_targs) in mult_targets.iter() {
        // perform_single_group_agg
        let cols_len = new_dfw.get_column_names().len();
@@ -288,76 +317,122 @@ fn get_mul_targets(
    Ok(mul_targets)
 }
 /// Builds a map of the shape:
 /// `HashMap<String, HashMap<String, (WeightValue, f64)>>`
 /// where only one of `weights` or `weight_xcats` can be provided.  
 /// If neither is provided, weights default to 1.0.  
 /// Each tuple is `(WeightValue, f64) = (weight, sign)`.
 fn form_weights_and_signs_map(
    cids: Vec<String>,
    xcats: Vec<String>,
    weights: Option<Vec<f64>>,
    weight_xcat: Option<String>,
    signs: Option<Vec<f64>>,
-) -> Result<HashMap<String, HashMap<String, Vec<f64>>>, Box<dyn std::error::Error>> {
+) -> Result<HashMap<String, HashMap<String, (WeightValue, f64)>>, Box<dyn std::error::Error>> {
-    let _agg_xcats_for_cid = agg_xcats_for_cid(cids.clone(), xcats.clone());
+    // For demonstration, we pretend to load or infer these from helpers:
-
+    let agg_xcats_for_cid = agg_xcats_for_cid(cids.clone(), xcats.clone());
    let (agg_on, agg_targ) = get_agg_on_agg_targs(cids.clone(), xcats.clone());
-    // if weights are None, create a vector of 1s of the same length as agg_targ
+    // Determine if each weight option has non-empty values.
-    let weights = weights.unwrap_or(vec![1.0 / agg_targ.len() as f64; agg_targ.len()]);
+    let weights_provided = weights.as_ref().map_or(false, |v| !v.is_empty());
-    let signs = signs.unwrap_or(vec![1.0; agg_targ.len()]);
+    let weight_xcats_provided = weight_xcat.as_ref().map_or(false, |v| !v.is_empty());
-    // check that the lengths of weights and signs match the length of agg_targ
+    // Enforce that only one of weights or weight_xcats is specified.
-    check_weights_signs_lengths(
+    if weights_provided && weight_xcats_provided {
-        weights.clone(),
+        return Err("Only one of `weights` and `weight_xcats` may be specified.".into());
-        signs.clone(),
+    }
        _agg_xcats_for_cid,
        agg_targ.len(),
    )?;
-    let mut weights_map = HashMap::new();
+    // 1) Build the "actual_weights" vector as WeightValue.
    let actual_weights: Vec<WeightValue> = if weights_provided {
        weights.unwrap().into_iter().map(WeightValue::F64).collect()
    } else if weight_xcats_provided {
        vec![WeightValue::Str(weight_xcat.unwrap()); agg_targ.len()]
    } else {
        // Default to numeric 1.0 if neither is provided
        vec![WeightValue::F64(1.0); agg_targ.len()]
    };
    // 2) Build the "signs" vector; default to 1.0 if not provided
    let signs = signs.unwrap_or_else(|| vec![1.0; agg_targ.len()]);
    // 3) Optional: check lengths & zero values (only numeric weights).
    check_weights_signs_lengths(&actual_weights, &signs, agg_xcats_for_cid, agg_targ.len())?;
    // 4) Build the final nested HashMap
    let mut weights_map: HashMap<String, HashMap<String, (WeightValue, f64)>> = HashMap::new();
    for agg_o in agg_on {
        let mut agg_t_map = HashMap::new();
        for (i, agg_t) in agg_targ.iter().enumerate() {
-            let ticker = match _agg_xcats_for_cid {
+            // Format the ticker
-                true => format!("{}_{}", agg_o, agg_t),
+            let ticker = if agg_xcats_for_cid {
-                false => format!("{}_{}", agg_t, agg_o),
+                format!("{}_{}", agg_o, agg_t)
            } else {
                format!("{}_{}", agg_t, agg_o)
            };
-            let weight_signs = vec![weights[i], signs[i]];
+            // Build the tuple (WeightValue, f64)
-            agg_t_map.insert(ticker, weight_signs);
+            let weight_sign_tuple = match &actual_weights[i] {
                WeightValue::F64(val) => (WeightValue::F64(*val).clone(), signs[i]),
                WeightValue::Str(vstr) => {
                    let new_str = format!("{}_{}", agg_t, vstr);
                    (WeightValue::Str(new_str), signs[i])
                }
            };
            agg_t_map.insert(ticker, weight_sign_tuple);
        }
        weights_map.insert(agg_o.clone(), agg_t_map);
    }
    Ok(weights_map)
 }
-
+/// Checks that the given slices have the expected length and that:
 /// - numeric weights are non-zero,
 /// - signs are non-zero.
 fn check_weights_signs_lengths(
-    weights_vec: Vec<f64>,
+    weights_vec: &[WeightValue],
-    signs_vec: Vec<f64>,
+    signs_vec: &[f64],
-    _agg_xcats_for_cid: bool,
+    agg_xcats_for_cid: bool,
    agg_targ_len: usize,
 ) -> Result<(), Box<dyn std::error::Error>> {
-    // for vx, vname in ...
+    // For diagnostics, decide what to call the dimension
-    let agg_targ = match _agg_xcats_for_cid {
+    let agg_targ = if agg_xcats_for_cid { "xcats" } else { "cids" };
-        true => "xcats",
+
-        false => "cids",
+    // 1) Check numeric weights for zeroes.
-    };
+    for (i, weight) in weights_vec.iter().enumerate() {
-    for (vx, vname) in vec![
+        if let WeightValue::F64(val) = weight {
-        (weights_vec.clone(), "weights"),
+            if *val == 0.0 {
-        (signs_vec.clone(), "signs"),
+                return Err(format!("The weight at index {} is 0.0", i).into());
    ] {
        for (i, v) in vx.iter().enumerate() {
            if *v == 0.0 {
                return Err(format!("The {} at index {} is 0.0", vname, i).into());
            }
        }
-        if vx.len() != agg_targ_len {
+    }
-            return Err(format!(
+    // 2) Ensure the weights vector is the expected length.
-                "The length of {} ({}) does not match the length of {} ({})",
+    if weights_vec.len() != agg_targ_len {
-                vname,
+        return Err(format!(
-                vx.len(),
+            "The length of weights ({}) does not match the length of {} ({})",
-                agg_targ,
+            weights_vec.len(),
-                agg_targ_len
+            agg_targ,
-            )
+            agg_targ_len
-            .into());
+        )
        .into());
    }
    // 3) Check signs for zero.
    for (i, sign) in signs_vec.iter().enumerate() {
        if *sign == 0.0 {
            return Err(format!("The sign at index {} is 0.0", i).into());
        }
    }
    // 4) Ensure the signs vector is the expected length.
    if signs_vec.len() != agg_targ_len {
        return Err(format!(
            "The length of signs ({}) does not match the length of {} ({})",
            signs_vec.len(),
            agg_targ,
            agg_targ_len
        )
        .into());
    }
    Ok(())
 }
 fn rename_result_dfw_cols(
@@ -393,6 +468,36 @@ fn agg_xcats_for_cid(cids: Vec<String>, xcats: Vec<String>) -> bool {
    xcats.len() > 1
 }
 /// Represents a weight value that can be a string, (float, or integer).
 #[derive(Debug, Clone, PartialEq)]
 pub enum WeightValue {
    Str(String),
    F64(f64),
 }
 impl From<String> for WeightValue {
    fn from(s: String) -> Self {
        WeightValue::Str(s)
    }
 }
 impl<'a> From<&'a str> for WeightValue {
    fn from(s: &'a str) -> Self {
        WeightValue::Str(s.to_string())
    }
 }
 impl From<f64> for WeightValue {
    fn from(f: f64) -> Self {
        WeightValue::F64(f)
    }
 }
 impl From<i32> for WeightValue {
    fn from(i: i32) -> Self {
        WeightValue::F64(i as f64)
    }
 }
 /// Weighted linear combinations of cross sections or categories
 /// # Arguments
 /// * `df` - QDF DataFrame
@@ -417,7 +522,7 @@ pub fn linear_composite(
    cids: Vec<String>,
    weights: Option<Vec<f64>>,
    signs: Option<Vec<f64>>,
-    weight_xcats: Option<Vec<String>>,
+    weight_xcat: Option<String>,
    normalize_weights: bool,
    start: Option<String>,
    end: Option<String>,
@@ -429,10 +534,28 @@ pub fn linear_composite(
 ) -> Result<DataFrame, Box<dyn std::error::Error>> {
    // Check if the DataFrame is a Quantamental DataFrame
    check_quantamental_dataframe(df)?;
    if agg_xcats_for_cid(cids.clone(), xcats.clone()) {
        if weight_xcat.is_some() {
            return Err(
                format!(
                    "Using xcats as weights is not supported when aggregating cids for a single xcat. {:?} {:?}",
                    cids, xcats
                )
                .into(),
            );
        }
    }
    let mut rxcats = xcats.clone();
    if weight_xcat.is_some() {
        rxcats.extend(vec![weight_xcat.clone().unwrap()]);
    }
    let rdf = reduce_dataframe(
        df.clone(),
        Some(cids.clone()),
-        Some(xcats.clone()),
+        Some(rxcats.clone()),
        Some(vec!["value".to_string()]),
        start.clone(),
        end.clone(),
@@ -443,10 +566,11 @@ pub fn linear_composite(
    let new_xcat = new_xcat.unwrap_or_else(|| "COMPOSITE".to_string());
    let new_cid = new_cid.unwrap_or_else(|| "GLB".to_string());
-    let dfw = pivot_dataframe_by_ticker(rdf.clone(), Some("value".to_string())).unwrap();
+    let dfw = pivot_dataframe_by_ticker(rdf, Some("value".to_string())).unwrap();
    let mul_targets = get_mul_targets(cids.clone(), xcats.clone())?;
-    let weights_map = form_weights_and_signs_map(cids.clone(), xcats.clone(), weights, signs)?;
+    let weights_map =
        form_weights_and_signs_map(cids.clone(), xcats.clone(), weights, weight_xcat, signs)?;
    for (ticker, targets) in mul_targets.iter() {
        println!("ticker: {}, targets: {:?}", ticker, targets);
--- a/src/utils/qdf/blacklist.rs
+++ b/src/utils/qdf/blacklist.rs
@@ -0,0 +1,27 @@
 use crate::utils::dateutils::{get_bdates_series_default_opt, get_min_max_real_dates};
 use crate::utils::qdf::core::*;
 use chrono::{Duration, NaiveDate};
 use polars::prelude::*;
 use std::collections::HashMap;
 use std::error::Error;
 use super::pivots::pivot_dataframe_by_ticker;
 /// The required columns for a Quantamental DataFrame.
 const QDF_INDEX_COLUMNS: [&str; 3] = ["real_date", "cid", "xcat"];
 pub fn create_blacklist_from_qdf(
    df: &DataFrame,
    metric: Option<String>,
    start: Option<String>,
    end: Option<String>,
 ) -> Result<HashMap<String, Vec<String>>, Box<dyn Error>> {
    // Verify that the DataFrame follows the Quantamental structure.
    check_quantamental_dataframe(df)?;
    let mut blacklist: HashMap<String, Vec<String>> = HashMap::new();
    // Use the provided metric or default to "value".
    let metric = metric.unwrap_or_else(|| "value".into());
    Ok(blacklist)
 }
--- a/src/utils/qdf/mod.rs
+++ b/src/utils/qdf/mod.rs
@@ -1,11 +1,12 @@
 pub mod blacklist;
 pub mod core;
 pub mod update_df;
 pub mod load;
 pub mod reduce_df;
 pub mod pivots;
 pub mod reduce_df;
 pub mod update_df;
 // Re-export submodules for easier access
 pub use core::*;
 pub use update_df::*;
 pub use load::*;
 pub use reduce_df::*;
 pub use update_df::*;
Author	SHA1	Message	Date
Palash Tyagi	5c3862c297	refactor: reorganize module exports for clarity	2025-04-14 00:25:23 +01:00
Palash Tyagi	3559a90ad2	adding blacklist ability	2025-04-14 00:25:09 +01:00
Palash Tyagi	b7368a366e	add weight_xcat capability	2025-04-14 00:24:26 +01:00
Palash Tyagi	24a4176e17	fix: correct import statement for reduce_dataframe in historic_vol.rs	2025-04-14 00:24:02 +01:00
Palash Tyagi	165e1c19e4	updating linear composite binding	2025-04-14 00:22:59 +01:00
Palash Tyagi	fefe849394	updating notebook	2025-04-14 00:22:38 +01:00