pyfru 0.1.0__tar.gz

pyfru-0.1.0/Cargo.toml

@@ -0,0 +1,4 @@
+[workspace]
+members = ["fru-arrow", "pyfru"]
+
+resolver = "3"

pyfru-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: pyfru
+Version: 0.1.0
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: pyarrow>=23.0.1
+Requires-Dist: pytest>=9 ; extra == 'dev'
+Requires-Dist: pandas>=3 ; extra == 'dev'
+Requires-Dist: furo>=2025.12.19 ; extra == 'dev'
+Requires-Dist: myst-parser>=5.1.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.15.12 ; extra == 'dev'
+Requires-Dist: sphinx>=9.1.0 ; extra == 'dev'
+Provides-Extra: dev
+Summary: Blazingly fast Random Forest with arrow support (pandas, polars, pyarrow etc.)
+Author-email: Chris Piwonski <fruarrow@kpiwonski.com>
+License-Expression: GPL-3.0-or-later
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: documentation, https://kpiwonski.github.io/fru-arrow/
+Project-URL: repository, https://github.com/kpiwonski/fru-arrow
+
+# Fru-arrow
+
+[R version](https://cran.r-project.org/web/packages/fru/index.html) |
+[Pyfru docs](https://kpiwonski.github.io/fru-arrow/)
+
+Fru-arrow is a highly performant implementation of the **Random Forest** model. It uses Arrow PyCapsule underneath,
+making integration with any library that supports it - ``polars``, ``pandas``, ``pyarrow`` straightforward.
+Moreover, it features permutation importance with a novel, highly optimized algorithm.
+It can be used for both **classification** and **regression**, as well as out-of-bag predictions.
+

pyfru-0.1.0/README.md

@@ -0,0 +1,9 @@
+# Fru-arrow
+
+[R version](https://cran.r-project.org/web/packages/fru/index.html) |
+[Pyfru docs](https://kpiwonski.github.io/fru-arrow/)
+
+Fru-arrow is a highly performant implementation of the **Random Forest** model. It uses Arrow PyCapsule underneath,
+making integration with any library that supports it - ``polars``, ``pandas``, ``pyarrow`` straightforward.
+Moreover, it features permutation importance with a novel, highly optimized algorithm.
+It can be used for both **classification** and **regression**, as well as out-of-bag predictions.

pyfru-0.1.0/fru-arrow/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "fru-arrow"
+version = "0.1.0"
+authors = ["Krzysztof Piwonski <fruarrow@kpiwonski.com>", "Miron B. Kursa <m@mbq.me>"]
+edition="2024"
+license = "GPL-3.0-or-later"
+description = "Blazingly fast implementation of Random Forest with apache arrow support"
+readme = "README.md"
+keywords = ["machine-learning", "ml", "random-forest", "decision-tree"]
+categories = ["artificial-intelligence"]
+repository = "https://github.com/kpiwonski/fru-arrow"
+
+[dependencies]
+xrf = {version="0.1.7"}
+minarrow = {version="0.11.0", features=["extended_numeric_types", "extended_categorical"]}
+serde = "1.0.228"
+postcard = {version = "1.1.3", features = ["use-std"]}
+thiserror = "2.0.18"
+
+[dev-dependencies]
+rand = "0.9"
+minarrow = {version="0.11.0", features=["extended_numeric_types", "extended_categorical", "views"]}
+
+[profile.release]
+codegen-units = 1
+lto = "fat"

pyfru-0.1.0/fru-arrow/README.md

@@ -0,0 +1,9 @@
+# Fru-arrow
+
+[R version](https://cran.r-project.org/web/packages/fru/index.html) |
+[Pyfru docs](https://kpiwonski.github.io/fru-arrow/)
+
+Fru-arrow is a highly performant implementation of the **Random Forest** model. It uses Arrow PyCapsule underneath,
+making integration with any library that supports it - ``polars``, ``pandas``, ``pyarrow`` straightforward.
+Moreover, it features permutation importance with a novel, highly optimized algorithm.
+It can be used for both **classification** and **regression**, as well as out-of-bag predictions.

pyfru-0.1.0/fru-arrow/src/attribute.rs

@@ -0,0 +1,191 @@
+use std::marker::PhantomData;
+
+use minarrow::{
+    Array, BooleanArray, CategoricalArray, FloatArray, IntegerArray, NumericArray, TextArray,
+};
+use serde::{Deserialize, Serialize};
+use xrf::{FeatureSampler, RfInput, RfRng};
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub enum DfPivot {
+    Logical,
+    Real(f64),
+    Integer(i64),
+    UInteger(u64),
+    Subset(u64),
+}
+
+pub struct SplittingIterator<'a, M> {
+    pair: DfSplittingPair<'a>,
+    mask_iter: M,
+}
+
+enum DfSplittingPair<'a> {
+    Boolean(&'a BooleanArray<()>),
+    Float32(&'a FloatArray<f32>, f64),
+    Float64(&'a FloatArray<f64>, f64),
+    Integer8(&'a IntegerArray<i8>, i64),
+    Integer16(&'a IntegerArray<i16>, i64),
+    Integer32(&'a IntegerArray<i32>, i64),
+    Integer64(&'a IntegerArray<i64>, i64),
+    UInteger8(&'a IntegerArray<u8>, u64),
+    UInteger16(&'a IntegerArray<u16>, u64),
+    UInteger32(&'a IntegerArray<u32>, u64),
+    UInteger64(&'a IntegerArray<u64>, u64),
+    Categorical8(&'a CategoricalArray<u8>, u64),
+    Categorical16(&'a CategoricalArray<u16>, u64),
+    Categorical32(&'a CategoricalArray<u32>, u64),
+    Categorical64(&'a CategoricalArray<u64>, u64),
+}
+impl<'a, M> SplittingIterator<'a, M> {
+    pub fn new(x: &'a Array, pivot: &DfPivot, mask_iter: M) -> Self {
+        let pair = match x {
+            Array::NumericArray(num) => match (num, pivot) {
+                (NumericArray::Float32(arr), &DfPivot::Real(xt)) => {
+                    DfSplittingPair::Float32(arr, xt)
+                }
+                (NumericArray::Float64(arr), &DfPivot::Real(xt)) => {
+                    DfSplittingPair::Float64(arr, xt)
+                }
+                (NumericArray::Int8(arr), &DfPivot::Integer(xt)) => {
+                    DfSplittingPair::Integer8(arr, xt)
+                }
+                (NumericArray::Int16(arr), &DfPivot::Integer(xt)) => {
+                    DfSplittingPair::Integer16(arr, xt)
+                }
+                (NumericArray::Int32(arr), &DfPivot::Integer(xt)) => {
+                    DfSplittingPair::Integer32(arr, xt)
+                }
+                (NumericArray::Int64(arr), &DfPivot::Integer(xt)) => {
+                    DfSplittingPair::Integer64(arr, xt)
+                }
+                (NumericArray::UInt8(arr), &DfPivot::UInteger(xt)) => {
+                    DfSplittingPair::UInteger8(arr, xt)
+                }
+                (NumericArray::UInt16(arr), &DfPivot::UInteger(xt)) => {
+                    DfSplittingPair::UInteger16(arr, xt)
+                }
+                (NumericArray::UInt32(arr), &DfPivot::UInteger(xt)) => {
+                    DfSplittingPair::UInteger32(arr, xt)
+                }
+                (NumericArray::UInt64(arr), &DfPivot::UInteger(xt)) => {
+                    DfSplittingPair::UInteger64(arr, xt)
+                }
+                _ => panic!("Unsupported array type!"),
+            },
+            Array::TextArray(cat) => match (cat, pivot) {
+                (TextArray::Categorical8(arr), &DfPivot::Subset(sub)) => {
+                    DfSplittingPair::Categorical8(arr, sub)
+                }
+                (TextArray::Categorical16(arr), &DfPivot::Subset(sub)) => {
+                    DfSplittingPair::Categorical16(arr, sub)
+                }
+                (TextArray::Categorical32(arr), &DfPivot::Subset(sub)) => {
+                    DfSplittingPair::Categorical32(arr, sub)
+                }
+                (TextArray::Categorical64(arr), &DfPivot::Subset(sub)) => {
+                    DfSplittingPair::Categorical64(arr, sub)
+                }
+                _ => panic!("Unsupported array type!"),
+            },
+            Array::BooleanArray(arr) => match pivot {
+                &DfPivot::Logical => DfSplittingPair::Boolean(arr),
+                _ => panic!("Unsupported array type!"),
+            },
+            _ => panic!("Unsupported array type!"),
+        };
+
+        Self { pair, mask_iter }
+    }
+}
+
+impl<'a, 'b, M> Iterator for SplittingIterator<'a, M>
+where
+    M: Iterator<Item = &'b usize>,
+{
+    type Item = bool;
+    fn next(&mut self) -> Option<bool> {
+        if let Some(&e) = self.mask_iter.next() {
+            let ans = match self.pair {
+                DfSplittingPair::Boolean(x) => x[e],
+                DfSplittingPair::Float32(x, xt) => x[e] as f64 > xt,
+                DfSplittingPair::Float64(x, xt) => x[e] > xt,
+                DfSplittingPair::Integer8(x, xt) => x[e] as i64 > xt,
+                DfSplittingPair::Integer16(x, xt) => x[e] as i64 > xt,
+                DfSplittingPair::Integer32(x, xt) => x[e] as i64 > xt,
+                DfSplittingPair::Integer64(x, xt) => x[e] > xt,
+                DfSplittingPair::UInteger8(x, xt) => x[e] as u64 > xt,
+                DfSplittingPair::UInteger16(x, xt) => x[e] as u64 > xt,
+                DfSplittingPair::UInteger32(x, xt) => x[e] as u64 > xt,
+                DfSplittingPair::UInteger64(x, xt) => x[e] > xt,
+                DfSplittingPair::Categorical8(x, split) => split & (1 << x[e] as u64) != 0,
+                DfSplittingPair::Categorical16(x, split) => split & (1 << x[e] as u64) != 0,
+                DfSplittingPair::Categorical32(x, split) => split & (1 << x[e] as u64) != 0,
+                DfSplittingPair::Categorical64(x, split) => split & (1 << x[e]) != 0,
+            };
+            Some(ans)
+        } else {
+            None
+        }
+    }
+}
+
+pub struct FYSampler<I> {
+    mixed: Vec<usize>,
+    left: usize,
+    marker: PhantomData<I>,
+}
+
+impl<I: RfInput<FeatureId = usize>> FYSampler<I> {
+    pub fn new(input: &I) -> Self {
+        Self {
+            mixed: (0..input.feature_count()).collect(),
+            left: input.feature_count(),
+            marker: PhantomData,
+        }
+    }
+}
+
+impl<I: RfInput<FeatureId = usize>> FeatureSampler<I> for FYSampler<I> {
+    fn random_feature(&mut self, rng: &mut RfRng) -> I::FeatureId {
+        let sel = rng.up_to(self.left);
+        let ans = self.mixed[sel];
+        self.left = self.left.checked_sub(1).unwrap();
+        self.mixed.swap(sel, self.left);
+        ans
+    }
+    fn reload(&mut self) {
+        self.left = self.mixed.len();
+    }
+    fn reset(&mut self) {
+        self.mixed = (0..self.mixed.len()).collect();
+        self.left = self.mixed.len();
+    }
+}
+
+macro_rules! impl_from_uint_for_dfpivot {
+    ($($t:ty),* $(,)?) => {
+        $(
+            impl From<$t> for DfPivot {
+                fn from(value: $t) -> Self {
+                    DfPivot::UInteger(value as u64)
+                }
+            }
+        )*
+    };
+}
+
+macro_rules! impl_from_int_for_dfpivot {
+    ($($t:ty),* $(,)?) => {
+        $(
+            impl From<$t> for DfPivot {
+                fn from(value: $t) -> Self {
+                    DfPivot::Integer(value as i64)
+                }
+            }
+        )*
+    };
+}
+
+impl_from_int_for_dfpivot!(i8, i16, i32, i64);
+impl_from_uint_for_dfpivot!(u8, u16, u32, u64);

pyfru-0.1.0/fru-arrow/src/classification/da.rs

@@ -0,0 +1,59 @@
+use crate::classification::ClsDecisionBasicType;
+
+use super::DataFrame;
+use minarrow::CategoricalArray;
+use std::collections::HashMap;
+use xrf::{AccuracyDecreaseAggregator, Mask, RfInput};
+
+pub struct ClsDaAggregator {
+    direct: Vec<Option<ClsDecisionBasicType>>,
+    drops: HashMap<usize, isize>,
+    n: usize,
+    true_decision: CategoricalArray<ClsDecisionBasicType>,
+}
+impl AccuracyDecreaseAggregator<DataFrame> for ClsDaAggregator {
+    fn new(input: &DataFrame, on: &Mask, n: usize) -> Self {
+        Self {
+            direct: vec![None; n],
+            drops: HashMap::new(),
+            n: on.len(),
+            //TODO: Reference here
+            true_decision: input.decision.clone(),
+        }
+    }
+    fn ingest(&mut self, permutted: Option<usize>, mask: &Mask, vote: &ClsDecisionBasicType) {
+        if let Some(permutted) = permutted {
+            let diff: isize = mask
+                .iter()
+                .map(|&e| {
+                    let oob_vote = self.direct.get(e).unwrap().unwrap();
+                    if !oob_vote.eq(vote) {
+                        let tru = self.true_decision[e];
+                        match (tru.eq(vote), tru.eq(&oob_vote)) {
+                            (true, true) => unreachable!("Logic error"),
+                            (true, false) => -1,
+                            (false, true) => 1,
+
+                            (false, false) => 0,
+                        }
+                    } else {
+                        0
+                    }
+                })
+                .sum();
+            *self.drops.entry(permutted).or_insert(0) += diff;
+        } else {
+            for &e in mask.iter() {
+                self.direct[e] = Some(*vote);
+            }
+        }
+    }
+    fn get_direct_vote(&self, e: usize) -> ClsDecisionBasicType {
+        self.direct.get(e).unwrap().unwrap()
+    }
+    fn mda_iter(&self) -> impl Iterator<Item = (<DataFrame as RfInput>::FeatureId, f64)> {
+        self.drops
+            .iter()
+            .map(|(a, b)| (*a, (*b as f64) / (self.n as f64)))
+    }
+}

pyfru-0.1.0/fru-arrow/src/classification/impurity.rs

@@ -0,0 +1,187 @@
+use std::ops::Add;
+
+use super::{DecisionSlice, Votes};
+use crate::{attribute::DfPivot, classification::ClsDecisionBasicType, tools::MidpointThreshold};
+use minarrow::BooleanArray;
+use xrf::{Mask, RfRng, VoteAggregator};
+
+pub fn scan_bin(x: &BooleanArray<()>, ys: &DecisionSlice, mask: &Mask) -> Option<(DfPivot, f64)> {
+    let mut left = Votes::new(ys.ncat);
+    let mut xt = 0_usize;
+    let n = mask.len();
+    mask.iter()
+        .map(|&e| x[e])
+        .zip(ys.values.iter())
+        .for_each(|(x, &y)| {
+            if x {
+                left.ingest_vote(y);
+                xt += 1;
+            }
+        });
+    let score: f64 = ys
+        .summary
+        .0
+        .iter()
+        .zip(left.0.iter())
+        .map(|(total, &left)| {
+            let for_false = (n - xt) as f64;
+            let for_true = xt as f64;
+            let n = n as f64;
+            let right = (total - left) as f64;
+            let left = left as f64;
+            (left / for_true) * (left / n) + (right / for_false) * (right / n)
+        })
+        .sum();
+    Some((DfPivot::Logical, score))
+}
+
+pub fn scan_categorical<T: Copy + Ord + TryInto<usize> + Into<DfPivot> + MidpointThreshold>(
+    x: &[T],
+    xc: usize,
+    ys: &DecisionSlice,
+    mask: &Mask,
+    _rng: &mut RfRng,
+) -> Option<(DfPivot, f64)> {
+    if xc > 10 {
+        //When there is too many combinations, just treat it as ordered
+        return scan_integer(x, ys, mask);
+    }
+    if xc < 2 {
+        return None;
+    }
+    let n = mask.len();
+    let mut va: Vec<Votes> = std::iter::repeat_with(|| Votes::new(ys.ncat))
+        .take(xc)
+        .collect();
+    mask.iter()
+        .map(|&e| x[e])
+        .zip(ys.values.iter())
+        .for_each(|(x, &y)| va[x.try_into().ok().unwrap()].ingest_vote(y));
+    let sub_max: u64 = (1 << (xc - 1)) - 1;
+
+    (0..sub_max)
+        .map(|bitmask_id| bitmask_id + (1 << (xc - 1)))
+        .fold(None, |acc: Option<(u64, f64)>, bitmask| {
+            let left = va
+                .iter()
+                .enumerate()
+                .filter(|(e, _)| bitmask & (1 << e) != 0)
+                .fold(Votes::new(ys.ncat), |mut acc, (_, v)| {
+                    acc.merge(v);
+                    acc
+                });
+            let in_left: usize = left.0.iter().sum();
+
+            let score: f64 = ys
+                .summary
+                .0
+                .iter()
+                .zip(left.0.iter())
+                .map(|(&all, &left)| {
+                    let ahead = (n - in_left) as f64;
+                    let scanned = in_left as f64;
+                    let n = n as f64;
+                    let right = (all - left) as f64;
+                    let left = left as f64;
+                    (left / scanned) * (left / n) + (right / ahead) * (right / n)
+                })
+                .sum();
+            if score > acc.map(|x| x.1).unwrap_or(f64::NEG_INFINITY) {
+                return Some((bitmask, score));
+            }
+            acc
+        })
+        .map(|(bitmask, score)| (DfPivot::Subset(bitmask), score))
+}
+
+pub fn scan_float<T: Copy + PartialOrd + Add<T, Output = T> + Into<f64>>(
+    x: &[T],
+    ys: &DecisionSlice,
+    mask: &Mask,
+) -> Option<(DfPivot, f64)> {
+    let mut bound: Vec<(T, ClsDecisionBasicType)> = mask
+        .iter()
+        .zip(ys.values.iter())
+        .map(|(&xe, &y)| (x[xe], y))
+        .collect();
+    bound.sort_unstable_by(|a, b| a.0.partial_cmp(&b.0).unwrap());
+
+    let n = bound.len();
+    let mut left = Votes::new(ys.ncat);
+    let mut scanned = 0_usize;
+
+    bound
+        .windows(2)
+        .map(|x| (x[0].0, x[1].0, x[0].1))
+        .fold(None, |acc: Option<(f64, f64)>, (x, next_x, y)| {
+            scanned += 1;
+            left.ingest_vote(y);
+            if x.partial_cmp(&next_x).unwrap().is_ne() {
+                let score: f64 = ys
+                    .summary
+                    .0
+                    .iter()
+                    .zip(left.0.iter())
+                    .map(|(&all, &left)| {
+                        let ahead = (n - scanned) as f64;
+                        let scanned = scanned as f64;
+                        let n = n as f64;
+                        let right = (all - left) as f64;
+                        let left = left as f64;
+                        (left / scanned) * (left / n) + (right / ahead) * (right / n)
+                    })
+                    .sum();
+                if score > acc.map(|x| x.1).unwrap_or(f64::NEG_INFINITY) {
+                    return Some((Into::<f64>::into(x + next_x) * 0.5, score));
+                }
+            }
+            acc
+        })
+        .map(|(thresh, score)| (DfPivot::Real(thresh), score))
+}
+
+pub fn scan_integer<T: Copy + Ord + Into<DfPivot> + MidpointThreshold>(
+    x: &[T],
+    ys: &DecisionSlice,
+    mask: &Mask,
+) -> Option<(DfPivot, f64)> {
+    let mut bound: Vec<(T, ClsDecisionBasicType)> = mask
+        .iter()
+        .zip(ys.values.iter())
+        .map(|(&xe, &y)| (x[xe], y))
+        .collect();
+    bound.sort_unstable_by_key(|a| a.0);
+
+    let n = bound.len();
+    let mut left = Votes::new(ys.ncat);
+    let mut scanned = 0_usize;
+
+    bound
+        .windows(2)
+        .map(|x| (x[0].0, x[1].0, x[0].1))
+        .fold(None, |acc: Option<(T, f64)>, (x, next_x, y)| {
+            scanned += 1;
+            left.ingest_vote(y);
+            if x.cmp(&next_x).is_ne() {
+                let score: f64 = ys
+                    .summary
+                    .0
+                    .iter()
+                    .zip(left.0.iter())
+                    .map(|(&all, &left)| {
+                        let ahead = (n - scanned) as f64;
+                        let scanned = scanned as f64;
+                        let n = n as f64;
+                        let right = (all - left) as f64;
+                        let left = left as f64;
+                        (left / scanned) * (left / n) + (right / ahead) * (right / n)
+                    })
+                    .sum();
+                if score > acc.map(|x| x.1).unwrap_or(f64::NEG_INFINITY) {
+                    return Some((x.midpoint_threshold(next_x), score));
+                }
+            }
+            acc
+        })
+        .map(|(thresh, score)| (thresh.into(), score))
+}

pyfru-0.1.0/fru-arrow/src/classification/votes.rs

@@ -0,0 +1,45 @@
+use crate::classification::ClsDecisionBasicType;
+
+use super::DataFrame;
+use serde::{Deserialize, Serialize};
+use xrf::{FairBest, RfRng, VoteAggregator};
+
+#[derive(Clone, Serialize, Deserialize)]
+pub struct Votes(pub Vec<usize>); //TODO: Fix impurity to make it private
+
+impl Votes {
+    pub fn is_pure(&self) -> bool {
+        self.0.iter().filter(|&&x| x > 0).count() <= 1
+    }
+    pub fn new(ncat: ClsDecisionBasicType) -> Self {
+        Self(std::iter::repeat_n(0, ncat as usize).collect())
+    }
+
+    pub fn collapse_empty_random(&self, rng: &mut RfRng) -> ClsDecisionBasicType {
+        self.0
+            .iter()
+            .enumerate()
+            .fold(FairBest::new(), |mut best, (cls, count)| {
+                best.ingest(count, cls, rng);
+                best
+            })
+            .consume()
+            .map(|(_score, class)| class as ClsDecisionBasicType)
+            .unwrap()
+    }
+}
+
+impl VoteAggregator<DataFrame> for Votes {
+    fn new(input: &DataFrame) -> Self {
+        Votes::new(input.ncat)
+    }
+    fn ingest_vote(&mut self, v: ClsDecisionBasicType) {
+        self.0[v as usize] += 1;
+    }
+    fn merge(&mut self, other: &Self) {
+        self.0
+            .iter_mut()
+            .zip(other.0.iter())
+            .for_each(|(t, s)| *t += s);
+    }
+}