Struct polars::series::Series

source · [−]
pub struct Series(pub Arc<dyn SeriesTrait + 'static>);
Expand description

Series

The columnar data type for a DataFrame.

Most of the available functions are defined in the SeriesTrait trait.

The Series struct consists of typed ChunkedArray’s. To quickly cast a Series to a ChunkedArray you can call the method with the name of the type:

let s: Series = [1, 2, 3].iter().collect();
// Quickly obtain the ChunkedArray wrapped by the Series.
let chunked_array = s.i32().unwrap();

Arithmetic

You can do standard arithmetic on series.

let s = Series::new("a", [1 , 2, 3]);
let out_add = &s + &s;
let out_sub = &s - &s;
let out_div = &s / &s;
let out_mul = &s * &s;

Or with series and numbers.

let s: Series = (1..3).collect();
let out_add_one = &s + 1;
let out_multiply = &s * 10;

// Could not overload left hand side operator.
let out_divide = 1.div(&s);
let out_add = 1.add(&s);
let out_subtract = 1.sub(&s);
let out_multiply = 1.mul(&s);

Comparison

You can obtain boolean mask by comparing series.

let s = Series::new("dollars", &[1, 2, 3]);
let mask = s.equal(1).unwrap();
let valid = [true, false, false].iter();
assert!(mask
    .into_iter()
    .map(|opt_bool| opt_bool.unwrap()) // option, because series can be null
    .zip(valid)
    .all(|(a, b)| a == *b))

See all the comparison operators in the CmpOps trait

Iterators

The Series variants contain differently typed ChunkedArray’s. These structs can be turned into iterators, making it possible to use any function/ closure you want on a Series.

These iterators return an Option<T> because the values of a series may be null.

use polars_core::prelude::*;
let pi = 3.14;
let s = Series::new("angle", [2f32 * pi, pi, 1.5 * pi].as_ref());
let s_cos: Series = s.f32()
                    .expect("series was not an f32 dtype")
                    .into_iter()
                    .map(|opt_angle| opt_angle.map(|angle| angle.cos()))
                    .collect();

Creation

Series can be create from different data structures. Below we’ll show a few ways we can create a Series object.

// Series can be created from Vec's, slices and arrays
Series::new("boolean series", &[true, false, true]);
Series::new("int series", &[1, 2, 3]);
// And can be nullable
Series::new("got nulls", &[Some(1), None, Some(2)]);

// Series can also be collected from iterators
let from_iter: Series = (0..10)
    .into_iter()
    .collect();

Tuple Fields

0: Arc<dyn SeriesTrait + 'static>

Implementations

Sample a fraction between 0.0-1.0 of this ChunkedArray.

Returns a reference to the Arrow ArrayRef

Convert a chunk in the Series to the correct Arrow type. This conversion is needed because polars doesn’t use a 1 on 1 mapping for logical/ categoricals, etc.

iterate over Series as AnyValue.

Panics

This will panic if the array is not rechunked first.

Unpack to ChunkedArray of dtype i8

Unpack to ChunkedArray i16

Unpack to ChunkedArray

let s = Series::new("foo", [1i32 ,2, 3]);
let s_squared: Series = s.i32()
    .unwrap()
    .into_iter()
    .map(|opt_v| {
        match opt_v {
            Some(v) => Some(v * v),
            None => None, // null value
        }
}).collect();

Unpack to ChunkedArray of dtype i64

Unpack to ChunkedArray of dtype f32

Unpack to ChunkedArray of dtype f64

Unpack to ChunkedArray of dtype u8

Unpack to ChunkedArray of dtype u16

Unpack to ChunkedArray of dtype u32

Unpack to ChunkedArray of dtype u64

Unpack to ChunkedArray of dtype bool

Unpack to ChunkedArray of dtype utf8

Unpack to ChunkedArray of dtype binary

Unpack to ChunkedArray of dtype Time

Unpack to ChunkedArray of dtype Date

Unpack to ChunkedArray of dtype datetime

Unpack to ChunkedArray of dtype duration

Unpack to ChunkedArray of dtype list

Unpack to ChunkedArray of dtype categorical

source

pub fn struct_(&self) -> Result<&StructChunked, PolarsError>

Unpack to ChunkedArray of dtype struct

Extend with a constant value.

Round underlying floating point array to given decimal.

Floor underlying floating point array to the lowest integers smaller or equal to the float value.

Ceil underlying floating point array to the highest integers smaller or equal to the float value.

Clamp underlying values to the min and max values.

Clamp underlying values to the max value.

Clamp underlying values to the min value.

Convert the values of this Series to a ListChunked with a length of 1, So a Series of: [1, 2, 3] becomes [[1, 2, 3]]

Create a new empty Series

Rename series.

Shrink the capacity of this array to fit its length.

Append arrow array of same datatype.

Append in place. This is done by adding the chunks of other to this Series.

See ChunkedArray::append and ChunkedArray::extend.

Extend the memory backed by this array with the values from other.

See ChunkedArray::extend and ChunkedArray::append.

Only implemented for numeric types

Cast [Series] to another [DataType]

Compute the sum of all values in this Series. Returns None if the array is empty or only contains null values.

If the DataType is one of {Int8, UInt8, Int16, UInt16} the Series is first cast to Int64 to prevent overflow issues.

let s = Series::new("days", &[1, 2, 3]);
assert_eq!(s.sum(), Some(6));

Returns the minimum value in the array, according to the natural order. Returns an option because the array is nullable.

let s = Series::new("days", [1, 2, 3].as_ref());
assert_eq!(s.min(), Some(1));

Returns the maximum value in the array, according to the natural order. Returns an option because the array is nullable.

let s = Series::new("days", [1, 2, 3].as_ref());
assert_eq!(s.max(), Some(3));

Explode a list or utf8 Series. This expands every item to a new row..

Check if float value is NaN (note this is different than missing/ null)

Check if float value is NaN (note this is different than missing/ null)

Check if float value is finite

Check if float value is infinite

Create a new ChunkedArray with values from self where the mask evaluates true and values from other where the mask evaluates false

Cast a datelike Series to their physical representation. Primitives remain unchanged

  • Date -> Int32
  • Datetime-> Int64
  • Time -> Int64
  • Categorical -> UInt32

Take by index if ChunkedArray contains a single chunk.

Safety

This doesn’t check any bounds. Null validity is checked.

Take by index. This operation is clone.

Safety

Out of bounds access doesn’t Error but will return a Null value

Filter by boolean mask. This operation clones data.

Get the sum of the Series as a new Series of length 1.

If the DataType is one of {Int8, UInt8, Int16, UInt16} the Series is first cast to Int64 to prevent overflow issues.

Get an array with the cumulative max computed at every element

Get an array with the cumulative min computed at every element

Get an array with the cumulative sum computed at every element

If the DataType is one of {Int8, UInt8, Int16, UInt16} the Series is first cast to Int64 to prevent overflow issues.

Get an array with the cumulative product computed at every element

If the DataType is one of {Int8, UInt8, Int16, UInt16, Int32, UInt32} the Series is first cast to Int64 to prevent overflow issues.

Get the product of an array.

If the DataType is one of {Int8, UInt8, Int16, UInt16} the Series is first cast to Int64 to prevent overflow issues.

Cast throws an error if conversion had overflows

convert numerical values to their absolute value

Get the head of the Series.

Get the tail of the Series.

Compute the unique elements, but maintain order. This requires more work than a naive Series::unique.

Returns an estimation of the total (heap) allocated size of the Series in bytes.

Implementation

This estimation is the sum of the size of its buffers, validity, including nested arrays. Multiple arrays may share buffers and bitmaps. Therefore, the size of 2 arrays is not the sum of the sizes computed from this function. In particular, StructArray’s size is an upper bound.

When an array is sliced, its allocated size remains constant because the buffer unchanged. However, this function will yield a smaller number. This is because this function returns the visible size of the buffer, not its total capacity.

FFI buffers are included in this estimation.

Check if series are equal. Note that None == None evaluates to false

Check if all values in series are equal where None == None evaluates to true. Two Datetime series are not equal if their timezones are different, regardless if they represent the same UTC time or not.

Get a pointer to the underlying data of this Series. Can be useful for fast comparisons.

Methods from Deref<Target = dyn SeriesTrait + 'static>

Trait Implementations

The resulting type after applying the + operator.
Performs the + operation. Read more
The resulting type after applying the + operator.
Performs the + operation. Read more
The resulting type after applying the + operator.
Performs the + operation. Read more
The resulting type after applying the + operator.
Performs the + operation. Read more
Converts this type into a mutable reference of the (usually inferred) input type.

We don’t implement Deref so that the caller is aware of converting to Series

Converts this type into a shared reference of the (usually inferred) input type.
Converts this type into a shared reference of the (usually inferred) input type.

Apply a closure F elementwise.

Apply a closure elementwise. The closure gets the index of the element as first argument.

Apply a closure elementwise. The closure gets the index of the element as first argument.

Apply a closure elementwise and cast to a Numeric ChunkedArray. This is fastest when the null check branching is more expensive than the closure application. Read more
Apply a closure on optional values and cast to Numeric ChunkedArray without null values.
Apply a closure elementwise including null values.
Apply a closure elementwise and write results to a mutable slice.

Create a boolean mask by checking for equality.

Create a boolean mask by checking for inequality.

Create a boolean mask by checking if self > rhs.

Create a boolean mask by checking if self >= rhs.

Create a boolean mask by checking if self < rhs.

Create a boolean mask by checking if self <= rhs.

Check for equality and regard missing values as equal.
Check for equality and regard missing values as equal.
Check for equality.
Check for inequality.
Greater than comparison.
Greater than or equal comparison.
Less than comparison.
Less than or equal comparison
Check for equality and regard missing values as equal.
Check for equality.
Check for inequality.
Greater than comparison.
Greater than or equal comparison.
Less than comparison.
Less than or equal comparison
Replace None values with a give value T.
Create a ChunkedArray with a single value.
Returns the mean value in the array. Returns None if the array is empty or only contains null values. Read more
Aggregate a given quantile of the ChunkedArray. Returns None if the array is empty or only contains null values. Read more
Returns the mean value in the array. Returns None if the array is empty or only contains null values. Read more
Aggregate a given quantile of the ChunkedArray. Returns None if the array is empty or only contains null values. Read more
Compute the variance of this ChunkedArray/Series.
Compute the standard deviation of this ChunkedArray/Series.
Compute the variance of this ChunkedArray/Series.
Compute the standard deviation of this ChunkedArray/Series.
Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more
The resulting type after dereferencing.
Dereferences the value.
Formats the value using the given formatter. Read more
let s: Series = [1, 2, 3].iter().collect();
let out = &s / &s;
The resulting type after applying the / operator.
The resulting type after applying the / operator.
Performs the / operation. Read more
The resulting type after applying the / operator.
Performs the / operation. Read more
The resulting type after applying the / operator.
Performs the / operation. Read more
Converts to this type from the input type.
Converts to this type from the input type.
Converts to this type from the input type.
Converts to this type from the input type.
Converts to this type from the input type.
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Panics

Panics if Series have different lengths.

Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Creates a value from an iterator. Read more
Literal expression.
let s: Series = [1, 2, 3].iter().collect();
let out = &s * &s;
The resulting type after applying the * operator.
The resulting type after applying the * operator.
Performs the * operation. Read more
The resulting type after applying the * operator.
Performs the * operation. Read more
The resulting type after applying the * operator.
Performs the * operation. Read more
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.

For any ChunkedArray and Series

Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Initialize by name and values.
Checked integer division. Computes self / rhs, returning None if rhs == 0 or the division results in overflow.
This method tests for self and other values to be equal, and is used by ==. Read more
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more
let s: Series = [1, 2, 3].iter().collect();
let out = &s / &s;
The resulting type after applying the % operator.
The resulting type after applying the % operator.
Performs the % operation. Read more
The resulting type after applying the % operator.
Performs the % operation. Read more
Create a DataFrame with the unique values of this Series and a column "counts" with dtype IdxType Read more

Apply a rolling quantile to a Series.

Apply a rolling max to a Series.

Apply a rolling variance to a Series.

Apply a rolling std_dev to a Series.

Apply a rolling mean to a Series. See: ChunkedArray::rolling_mean. Read more
Apply a rolling sum to a Series.
Apply a rolling median to a Series.
Apply a rolling min to a Series.
The resulting type after applying the - operator.
Performs the - operation. Read more
The resulting type after applying the - operator.
Performs the - operation. Read more
The resulting type after applying the - operator.
Performs the - operation. Read more
The resulting type after applying the - operator.
Performs the - operation. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
source

fn __clone_box(&self, Private) -> *mut ()

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The alignment of pointer.
The type for initializers.
Initializes a with the given initializer. Read more
Dereferences the given pointer. Read more
Mutably dereferences the given pointer. Read more
Drops the object pointed to by the given pointer. Read more
Extract hour from underlying NaiveDateTime representation. Returns the hour number from 0 to 23. Read more
Extract minute from underlying NaiveDateTime representation. Returns the minute number from 0 to 59. Read more
Extract second from underlying NaiveDateTime representation. Returns the second number from 0 to 59. Read more
Returns the number of nanoseconds since the whole non-leap second. The range from 1,000,000,000 to 1,999,999,999 represents the leap second. Read more
Extract day from underlying NaiveDateTime representation. Returns the day of month starting from 1. Read more
Returns the weekday number where monday = 0 and sunday = 6
Returns the ISO week number starting from 1. The return value ranges from 1 to 53. (The last week of year differs by years.) Read more
Returns the day of year starting from 1. Read more
Extract year from underlying NaiveDateTime representation. Returns the year number in the calendar date. Read more
Extract ordinal year from underlying NaiveDateTime representation. Returns the year number in the calendar date. Read more
Extract quarter from underlying NaiveDateTime representation. Quarters range from 1 to 4. Read more
Extract month from underlying NaiveDateTime representation. Returns the month number starting from 1. Read more
Format Date/Datetimewith a fmt rule. See chrono strftime/strptime.
Convert date(time) object to timestamp in TimeUnit.
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.