Struct Series 

pub struct Series<T>
where
    T: BlackJackData,
{
    pub name: Option<String>,
    pub values: Vec<T>,
    /* private fields */
}

Series struct for containing underlying Array and other meta data.

Fields

name: Option<String>

Name of the series, if added to a dataframe without a name, it will be assigned a default name equalling the count of columns in the dataframe.

values: Vec<T>

The underlying values of the Series

Implementations

impl<T> Series<T>

where T: BlackJackData,

Constructor methods for Series<T>

pub fn arange(start: T, stop: T) -> Self

where T: Integer + BlackJackData + ToPrimitive, Range<T>: Iterator, Vec<T>: FromIterator<<Range<T> as Iterator>::Item>,

Create a new Series struct from an integer range with one step increments.

Example

use blackjack::prelude::*;

let series: Series<i32> = Series::arange(0, 10);

pub fn drop_positions<I>(&mut self, positions: I)

where I: IntoIterator<Item = usize>,

Drop positions of the Series

pub fn iloc<'b, I>(&self, idx_vals: I) -> Vec<&T>

where I: IntoIterator<Item = &'b usize>,

Fetch values from the series by matching index positions, not by index value.

No data copies are made, and currently this is not done in parallel. As by currently single threaded exceeds parallel execution up to ~10m elements. As the majority of use cases have less than this amount, we’ve opted for single threading. If you need concurrent execution, please file an issue at our github. :-)

Example

use blackjack::prelude::*;

let mut series = Series::arange(0, 10000);  // Index values end up being 0-10000 by default here

let vals = series.iloc(&vec![250, 500, 1000, 2000, 4000, 5000]);  // ~300ns, ~28x faster than Pandas
assert_eq!(vals, vec![&250, &500, &1000, &2000, &4000, &5000]);

pub fn rolling(&self, window: usize) -> Rolling<'_, T>

where T: Send + Sync,

Calculate a predefined rolling aggregation

See Rolling for additional functionality.

Example

use blackjack::prelude::*;
use float_cmp::ApproxEq;

let series = Series::from_vec(vec![0, 1, 2, 3, 4, 5]);

let rolled: Series<f64> = series.rolling(4).mean().unwrap();
assert_eq!(rolled.len(), 6);

// vals in indexes 0 thru 2 should be NaN as they are inside the window
assert_eq!(rolled[0..2].iter().all(|v| v.is_nan()), true);

assert_eq!(rolled[3], 1.5);
assert_eq!(rolled[4], 2.5);
assert_eq!(rolled[5], 3.5);

pub fn isna<'a>(&'a self) -> impl Iterator<Item = bool> + 'a

where T: Float,

Return an iterable of booleans determining if any element is NaN

Example

use blackjack::prelude::*;

let mut series = Series::from_vec(vec![0, 1, 2])
    .astype::<f32>()
    .unwrap();

// No NaNs currently
assert_eq!(series.isna().collect::<Vec<bool>>(), vec![false, false, false]);

// Insert a NaN at index zero
series[0] = num::Float::nan();
assert_eq!(series.isna().collect::<Vec<bool>>(), vec![true, false, false]);

pub fn all<F>(&self, condition: F) -> bool

where for<'r> F: Fn(&'r T) -> bool,

Determine if all elements in the Series meet a given condition

This will stop iteration after encountering the first element which breaks the condition.

Example

use blackjack::prelude::*;

let series = Series::from_vec(vec![1, 2, 3, 4]);

assert_eq!(series.all(|x| *x > 0), true);
assert_eq!(series.all(|x| *x > 2), false);

pub fn all_equal(&self) -> bool

where T: PartialEq,

Check if all elements with the Series are equal

Example

use blackjack::prelude::*;

let series = Series::from_vec(vec![1, 1, 1, 1, 1]);
assert!(series.all_equal());

pub fn any<F>(&self, condition: F) -> bool

where for<'r> F: FnMut(&'r &T) -> bool,

Determine if any element in the Series meets a given condition

This will stop iteration after encountering the first element which meets conditions supplied.

pub fn cartesian_product<O>(&self, other: &Series<O>) -> (Series<T>, Series<O>)

where O: BlackJackData,

Create a cartesian product of this series and another, returns a pair of Series representing the cartesian product

Example

use blackjack::prelude::*;

let series1 = Series::from_vec(vec![0, 1]);
let series2 = Series::from_vec(vec![1, 2]);

let (cart_prod1, cart_prod2) = series1.cartesian_product(&series2);

assert_eq!(cart_prod1.values, vec![0, 0, 1, 1]);
assert_eq!(cart_prod2.values, vec![1, 2, 1, 2]);

pub fn positions<'a, F>( &'a self, condition: F, ) -> impl Iterator<Item = usize> + 'a

where F: 'a + Fn(&T) -> bool,

Return the positions of where a given condition evaluates to true

This is somewhat akin to the pandas where method.

Example

use blackjack::prelude::*;

let series = Series::from_vec(vec![1, 2, 1, 2]);

let indexes_of_ones = series.positions(|x| *x == 1).collect::<Vec<usize>>();
assert_eq!(indexes_of_ones, vec![0, 2]);

pub fn map_par<B, F>(self, func: F) -> Series<B>

where B: BlackJackData, F: Fn(T) -> B + Send + Sync,

Map a function over a series in parallel Function takes some type T and returns some type B which has BlackJackData implemented.

Example

use blackjack::prelude::*;

let series = Series::from_vec(vec![1, 1, 1, 1]);

let new_series = series.map_par(|x| x * 2);
assert_eq!(new_series.sum(), 8);

pub fn map<B, F>(self, func: F) -> Series<B>

where B: BlackJackData, F: Fn(T) -> B,

Map a function over a series in a single thread Function takes some type T and returns some type B which has BlackJackData implemented.

pub fn astype<A>(&self) -> Result<Series<A>, &'static str>

where A: BlackJackData + FromStr,

Convert the series into another DType (creates a new series)

Example

use blackjack::prelude::*;

let series: Series<i32> = Series::arange(0, 10);
assert_eq!(series[0].dtype(), DType::I32);
let new_series = series.astype::<f64>().unwrap();
assert_eq!(new_series[0].dtype(), DType::F64);

pub fn into_type<A>(self) -> Result<Series<A>, &'static str>

where A: BlackJackData + FromStr,

Convert this series into another DType (consumes current series)

Example

use blackjack::prelude::*;

let series: Series<i32> = Series::arange(0, 10);
assert_eq!(series[0].dtype(), DType::I32);
let new_series = series.into_type::<f64>().unwrap();
assert_eq!(new_series[0].dtype(), DType::F64);

pub fn unique(&self) -> Series<T>

where T: PartialOrd + Copy,

Get a series of the unique elements held in this series

Example

use blackjack::prelude::*;

let series: Series<i32> = Series::from_vec(vec![1, 2, 1, 0, 1, 0, 1, 1]);
let unique: Series<i32> = series.unique();
assert_eq!(unique, Series::from_vec(vec![0, 1, 2]));

pub fn from_vec(vec: Vec<T>) -> Self

Create a new Series struct from a vector, where T is supported by BlackJackData.

Example

use blackjack::prelude::*;

let series: Series<i32> = Series::from_vec(vec![1, 2, 3]);

pub fn into_vec(self) -> Vec<T>

Convert the series to a Vec

Example

use blackjack::prelude::*;

let series = Series::from_vec(vec![1_f64, 2_f64, 3_f64]);

assert_eq!(
    series.clone().into_vec(),
    vec![1_f64, 2_f64, 3_f64]
);

pub fn set_name(&mut self, name: &str)

Set the name of a series

pub fn name(&self) -> Option<String>

Get the name of the series; Series may not be assigned a string, so an Option is returned.

Example

use blackjack::prelude::*;

let mut series = Series::from_vec(vec![1, 2, 3]);
series.set_name("my-series");

assert_eq!(series.name(), Some("my-series".to_string()));

pub fn mode(&self) -> Result<Self, BlackJackError>

where T: BlackJackData + PartialOrd + Copy + ToPrimitive,

Finds the returns a Series containing the mode(s) of the current Series

pub fn var(&self, ddof: f64) -> Result<f64, BlackJackError>

where T: ToPrimitive + Num,

Calculate the variance of the series, using either population or sample variance

Population: ddof == 0_f64 Sample: ddof == 1_f64

pub fn std(&self, ddof: f64) -> Result<f64, BlackJackError>

where T: BlackJackData + ToPrimitive + Copy + Num,

Calculate the standard deviation of the series

Example

use blackjack::prelude::*;
use float_cmp::ApproxEq;

let series = Series::arange(0, 10).astype::<f32>().unwrap();

let std = series.std(1_f64).unwrap(); // using population ddof (sample variance == 0_f64)
assert_eq!(std, 3.0276503540974917);

pub fn sum(&self) -> T

where T: Num + Copy + Sum,

Sum a given series, yielding the same type as the elements stored in the series.

pub fn mean(&self) -> Result<f64, BlackJackError>

where T: ToPrimitive + Copy + Num + Sum,

Average / Mean of a given series - Requires specifying desired float return annotation

Example:

use blackjack::prelude::*;

let series = Series::arange(0, 5);
let mean = series.mean();

match mean {
    Ok(result) => {
        println!("Result is: {}", &result);
        assert_eq!(result, 2.0);
    },
    Err(err) => {
        panic!("Was unable to compute mean, error: {}", err);
    }
}

pub fn quantile(&self, quantile: f64) -> Result<f64, BlackJackError>

where T: ToPrimitive + BlackJackData,

Calculate the quantile of the series

Example:

use blackjack::prelude::*;

let series = Series::arange(0, 100).astype::<f32>().unwrap();
let qtl = series.quantile(0.5).unwrap(); // `49.5_f32`

assert!(qtl < 49.51);
assert!(qtl > 49.49);

pub fn median(&self) -> Result<f64, BlackJackError>

where T: ToPrimitive + Copy + PartialOrd,

Calculate the median of a series

pub fn min(&self) -> Result<T, BlackJackError>

where T: Num + PartialOrd + BlackJackData + Copy,

Find the minimum of the series. If several elements are equally minimum, the first element is returned. If it’s empty, an Error will be returned.

Example

use blackjack::prelude::*;

let series: Series<i32> = Series::arange(10, 100);

assert_eq!(series.min().unwrap(), 10);

pub fn max(&self) -> Result<T, BlackJackError>

where T: Num + PartialOrd + BlackJackData + Copy,

Exibits the same behavior and usage of Series::min, only yielding the Result of a maximum.

pub fn len(&self) -> usize

Determine the length of the Series

pub fn is_empty(&self) -> bool

Determine if series is empty.

pub fn dtype(&self) -> Option<DType>

Get the dtype, returns None if series dtype is unknown. in such a case, calling .astype() to coerce all types to a single type is needed.

pub fn append<V: Into<T>>(&mut self, val: V)

Append a BlackJackData element to the Series

Example

use blackjack::prelude::*;

let mut series = Series::from_vec(vec![0, 1, 2]);
assert_eq!(series.len(), 3);

series.append(3);
assert_eq!(series.len(), 4);

pub fn into_raw(self) -> *mut Self

As boxed pointer, recoverable by Box::from_raw(ptr) or Series::from_raw(*mut Self)

pub fn from_raw(ptr: *mut Self) -> Self

Create from raw pointer

pub fn groupby(&self, keys: &Series<T>) -> SeriesGroupBy<T>

where T: ToPrimitive,

Group by method for grouping elements in a Series by key.

Example

use blackjack::prelude::*;

let series = Series::from_vec(vec![1, 2, 3, 1, 2, 3]);
let keys   = Series::from_vec(vec![4, 5, 6, 4, 5, 6]);

let grouped: Series<i32> = series.groupby(&keys).sum();
assert_eq!(grouped.len(), 3);

let mut vals = grouped.into_vec();
vals.sort();
assert_eq!(vals, vec![2, 4, 6]);

pub fn find<F: Fn(&T) -> bool>(&self, condition: F) -> Vec<usize>

Find the positions where a condition is true

Example

let series = Series::from(0..10);
let positions = series.find(|v| v % 2 == 0);

assert_eq!(positions, vec![0, 2, 4, 6, 8]);

Trait Implementations

impl<T> Add<T> for Series<T>

where T: Num + Copy + BlackJackData + Send + Sync, Vec<T>: IntoParallelIterator<Item = T>, <Vec<T> as IntoParallelIterator>::Iter: IndexedParallelIterator,

Support series + scalar

type Output = Series<T>

The resulting type after applying the + operator.

fn add(self, scalar_val: T) -> Series<T>

Performs the + operation.

impl<T> Add for Series<T>

where T: Add<Output = T> + BlackJackData,

Support series + series

type Output = Result<Series<T>, BlackJackError>

The resulting type after applying the + operator.

fn add(self, other: Series<T>) -> Self::Output

Performs the + operation.

impl<T> AddAssign<T> for Series<T>

where T: Num + Copy + BlackJackData + Send + Sync + FromPrimitive + AddAssign<T>, Vec<T>: IntoParallelIterator<Item = T>, <Vec<T> as IntoParallelIterator>::Iter: IndexedParallelIterator,

Support series += scalar

fn add_assign(&mut self, scalar_val: T)

Performs the += operation.

impl<T> AddAssign for Series<T>

where T: BlackJackData + AddAssign,

fn add_assign(&mut self, other: Series<T>)

Performs the += operation.

impl<T> Clone for Series<T>

where T: BlackJackData + Clone,

fn clone(&self) -> Series<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Series<T>

where T: BlackJackData + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<I> Default for Series<I>

where I: PartialOrd + PartialEq + BlackJackData,

fn default() -> Self

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for Series<T>

where T: BlackJackData + Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Display for Series<T>

where T: BlackJackData, String: From<T>,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Div<T> for Series<T>

where T: Num + Copy + BlackJackData + Send + Sync, Vec<T>: IntoParallelIterator<Item = T>, <Vec<T> as IntoParallelIterator>::Iter: IndexedParallelIterator,

Support series - scalar

type Output = Series<T>

The resulting type after applying the / operator.

fn div(self, scalar_val: T) -> Series<T>

Performs the / operation.

impl<T> Div for Series<T>

where T: Div<Output = T> + BlackJackData,

Support series + series

type Output = Result<Series<T>, BlackJackError>

The resulting type after applying the / operator.

fn div(self, other: Series<T>) -> Self::Output

Performs the / operation.

impl<T> DivAssign<T> for Series<T>

where T: Num + Copy + BlackJackData + Send + Sync + DivAssign<T>, Vec<T>: IntoParallelIterator<Item = T>, <Vec<T> as IntoParallelIterator>::Iter: IndexedParallelIterator,

Support series += scalar

fn div_assign(&mut self, scalar_val: T)

Performs the /= operation.

impl<T> DivAssign for Series<T>

where T: BlackJackData + DivAssign,

fn div_assign(&mut self, other: Series<T>)

Performs the /= operation.

impl<T: BlackJackData> From<&Series<T>> for SeriesMeta

fn from(series: &Series<T>) -> SeriesMeta

Converts to this type from the input type.

impl<T> From<Range<T>> for Series<T>

where T: BlackJackData, Range<T>: Iterator, Vec<T>: FromIterator<<Range<T> as Iterator>::Item>,

fn from(range: Range<T>) -> Series<T>

Converts to this type from the input type.

impl<T> Index<Range<usize>> for Series<T>

where T: BlackJackData,

type Output = [T]

The returned type after indexing.

fn index(&self, idx: Range<usize>) -> &[T]

Performs the indexing (container[index]) operation.

impl<T> Index<usize> for Series<T>

where T: BlackJackData,

type Output = T

The returned type after indexing.

fn index(&self, idx: usize) -> &T

Performs the indexing (container[index]) operation.

impl<T: BlackJackData> IndexMut<usize> for Series<T>

fn index_mut(&mut self, idx: usize) -> &mut T

Performs the mutable indexing (container[index]) operation.

impl IntoIterator for Series<String>

type Item = String

The type of the elements being iterated over.

type IntoIter = IntoIter<String>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Series<f32>

type Item = f32

The type of the elements being iterated over.

type IntoIter = IntoIter<f32>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Series<f64>

type Item = f64

The type of the elements being iterated over.

type IntoIter = IntoIter<f64>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Series<i32>

type Item = i32

The type of the elements being iterated over.

type IntoIter = IntoIter<i32>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Series<i64>

type Item = i64

The type of the elements being iterated over.

type IntoIter = IntoIter<i64>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> Mul<T> for Series<T>

where T: Num + Copy + BlackJackData + Send + Sync, Vec<T>: IntoParallelIterator<Item = T>, <Vec<T> as IntoParallelIterator>::Iter: IndexedParallelIterator,

Support series * scalar

type Output = Series<T>

The resulting type after applying the * operator.

fn mul(self, scalar_val: T) -> Series<T>

Performs the * operation.

impl<T> Mul for Series<T>

where T: Mul<Output = T> + BlackJackData,

Support series + series

type Output = Result<Series<T>, BlackJackError>

The resulting type after applying the * operator.

fn mul(self, other: Series<T>) -> Self::Output

Performs the * operation.

impl<T> MulAssign<T> for Series<T>

where T: Num + Copy + BlackJackData + Send + Sync + MulAssign<T>, Vec<T>: IntoParallelIterator<Item = T>, <Vec<T> as IntoParallelIterator>::Iter: IndexedParallelIterator,

fn mul_assign(&mut self, scalar_val: T)

Performs the *= operation.

impl<T> MulAssign for Series<T>

where T: BlackJackData + MulAssign,

fn mul_assign(&mut self, other: Series<T>)

Performs the *= operation.

impl<T> PartialEq for Series<T>

where T: BlackJackData + PartialEq,

fn eq(&self, other: &Series<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for Series<T>

where T: BlackJackData + PartialOrd,

fn partial_cmp(&self, other: &Series<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Serialize for Series<T>

where T: BlackJackData + Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> Sub<T> for Series<T>

where T: Num + Copy + BlackJackData + Send + Sync + Sub, Vec<T>: IntoParallelIterator<Item = T>, <Vec<T> as IntoParallelIterator>::Iter: IndexedParallelIterator,

Support series - scalar

type Output = Series<T>

The resulting type after applying the - operator.

fn sub(self, scalar_val: T) -> Series<T>

Performs the - operation.

impl<T> Sub for Series<T>

where T: Sub<Output = T> + BlackJackData,

Support series + series

type Output = Result<Series<T>, BlackJackError>

The resulting type after applying the - operator.

fn sub(self, other: Series<T>) -> Self::Output

Performs the - operation.

impl<T> SubAssign<T> for Series<T>

where T: Num + Copy + BlackJackData + Send + Sync + SubAssign<T>, Vec<T>: IntoParallelIterator<Item = T>, <Vec<T> as IntoParallelIterator>::Iter: IndexedParallelIterator,

Support series -= scalar

fn sub_assign(&mut self, scalar_val: T)

Performs the -= operation.

impl<T> SubAssign for Series<T>

where T: BlackJackData + SubAssign,

fn sub_assign(&mut self, other: Series<T>)

Performs the -= operation.

impl<T> StructuralPartialEq for Series<T>

where T: BlackJackData,