Struct polars::frame::DataFrame

pub struct DataFrame { /* fields omitted */ }

Implementations

impl DataFrame

pub fn groupby<'g, S: Selection<'g>>(&self, by: S) -> Result<GroupBy<'_, '_>>

Group DataFrame using a Series column.

Example

use polars::prelude::*;
fn groupby_sum(df: &DataFrame) -> Result<DataFrame> {
    df.groupby("column_name")?
    .select("agg_column_name")
    .sum()
}

impl DataFrame

pub fn inner_join(
    &self,
    other: &DataFrame,
    left_on: &str,
    right_on: &str
) -> Result<DataFrame>

Perform an inner join on two DataFrames.

Example

use polars::prelude::*;
fn join_dfs(left: &DataFrame, right: &DataFrame) -> Result<DataFrame> {
    left.inner_join(right, "join_column_left", "join_column_right")
}

pub fn left_join(
    &self,
    other: &DataFrame,
    left_on: &str,
    right_on: &str
) -> Result<DataFrame>

Perform a left join on two DataFrames

Example

use polars::prelude::*;
fn join_dfs(left: &DataFrame, right: &DataFrame) -> Result<DataFrame> {
    left.left_join(right, "join_column_left", "join_column_right")
}

pub fn outer_join(
    &self,
    other: &DataFrame,
    left_on: &str,
    right_on: &str
) -> Result<DataFrame>

Perform an outer join on two DataFrames

Example

use polars::prelude::*;
fn join_dfs(left: &DataFrame, right: &DataFrame) -> Result<DataFrame> {
    left.outer_join(right, "join_column_left", "join_column_right")
}

impl DataFrame

pub fn new<S: IntoSeries>(columns: Vec<S>) -> Result<Self>

Create a DataFrame from a Vector of Series.

Example

use polars::prelude::*;
let s0 = Series::new("days", [0, 1, 2].as_ref());
let s1 = Series::new("temp", [22.1, 19.9, 7.].as_ref());
let df = DataFrame::new(vec![s0, s1]).unwrap();

pub fn schema(&self) -> Schema

Get a reference to the DataFrame schema.

pub fn get_columns(&self) -> &Vec<Series>

Get a reference to the DataFrame columns.

pub fn columns(&self) -> Vec<&str>

Get the column labels of the DataFrame.

pub fn dtypes(&self) -> Vec<ArrowDataType>

Get the data types of the columns in the DataFrame.

pub fn n_chunks(&self) -> Result<usize>

The number of chunks per column

pub fn fields(&self) -> Vec<Field>

Get a reference to the schema fields of the DataFrame.

pub fn shape(&self) -> (usize, usize)

Get (width x height)

Example

use polars::prelude::*;
fn assert_shape(df: &DataFrame, shape: (usize, usize)) {
    assert_eq!(df.shape(), shape)
}

pub fn width(&self) -> usize

Get width of DataFrame

Example

use polars::prelude::*;
fn assert_width(df: &DataFrame, width: usize) {
    assert_eq!(df.width(), width)
}

pub fn height(&self) -> usize

Get height of DataFrame

Example

use polars::prelude::*;
fn assert_height(df: &DataFrame, height: usize) {
    assert_eq!(df.height(), height)
}

pub fn hstack(&mut self, columns: &[Series]) -> Result<&mut Self>

Add multiple Series to a DataFrame This expects the Series to have the same length.

Example

use polars::prelude::*;
fn stack(df: &mut DataFrame, columns: &[Series]) {
    df.hstack(columns);
}

pub fn vstack(&mut self, df: &DataFrame) -> Result<&mut Self>

Concatenate a DataFrame to this DataFrame

pub fn drop_in_place(&mut self, name: &str) -> Result<Series>

Remove column by name

Example

use polars::prelude::*;
fn drop_column(df: &mut DataFrame, name: &str) -> Result<Series> {
    df.drop_in_place(name)
}

pub fn drop(&self, name: &str) -> Result<Self>

Drop a column by name. This is a pure method and will return a new DataFrame instead of modifying the current one in place.

pub fn add_column<S: IntoSeries>(&mut self, column: S) -> Result<&mut Self>

Add a new column to this DataFrame.

pub fn with_column<S: IntoSeries>(&self, column: S) -> Result<Self>

Create a new DataFrame with the column added.

pub fn get(&self, idx: usize) -> Option<Vec<AnyType<'_>>>

Get a row in the DataFrame Beware this is slow.

Example

use polars::prelude::*;
fn example(df: &mut DataFrame, idx: usize) -> Option<Vec<AnyType>> {
    df.get(idx)
}

pub fn select_at_idx(&self, idx: usize) -> Option<&Series>

Select a series by index.

pub fn find_idx_by_name(&self, name: &str) -> Option<usize>

Get column index of a series by name.

pub fn column(&self, name: &str) -> Result<&Series>

Select a single column by name.

pub fn select<'a, S>(&self, selection: S) -> Result<Self> where
    S: Selection<'a>, 

Select column(s) from this DataFrame and return a new DataFrame.

Examples

use polars::prelude::*;

fn example(df: &DataFrame, possible: &str) -> Result<DataFrame> {
    match possible {
        "by_str" => df.select("my-column"),
        "by_tuple" => df.select(("col_1", "col_2")),
        "by_vec" => df.select(vec!["col_a", "col_b"]),
         _ => unimplemented!()
    }
}

pub fn select_series<'a, S>(&self, selection: S) -> Result<Vec<Series>> where
    S: Selection<'a>, 

Select column(s) from this DataFrame and return them into a Vector.

pub fn filter(&self, mask: &BooleanChunked) -> Result<Self>

Take DataFrame rows by a boolean mask.

pub fn take_iter<I>(&self, iter: I, capacity: Option<usize>) -> Result<Self> where
    I: Iterator<Item = usize> + Clone + Sync, 

Take DataFrame value by indexes from an iterator.

Example

use polars::prelude::*;
fn example(df: &DataFrame) -> Result<DataFrame> {
    let iterator = (0..9).into_iter();
    df.take_iter(iterator, None)
}

pub unsafe fn take_iter_unchecked<I>(
    &self,
    iter: I,
    capacity: Option<usize>
) -> Self where
    I: Iterator<Item = usize> + Clone + Sync, 

Take DataFrame values by indexes from an iterator. This doesn't do any bound checking.

Example

use polars::prelude::*;
unsafe fn example(df: &DataFrame) -> DataFrame {
    let iterator = (0..9).into_iter();
    df.take_iter_unchecked(iterator, None)
}

pub fn take_opt_iter<I>(&self, iter: I, capacity: Option<usize>) -> Result<Self> where
    I: Iterator<Item = Option<usize>> + Clone + Sync, 

Take DataFrame values by indexes from an iterator that may contain None values.

Example

use polars::prelude::*;
fn example(df: &DataFrame) -> Result<DataFrame> {
    let iterator = (0..9).into_iter().map(Some);
    df.take_opt_iter(iterator, None)
}

pub unsafe fn take_opt_iter_unchecked<I>(
    &self,
    iter: I,
    capacity: Option<usize>
) -> Self where
    I: Iterator<Item = Option<usize>> + Clone + Sync, 

Take DataFrame values by indexes from an iterator that may contain None values. This doesn't do any bound checking.

Example

use polars::prelude::*;
unsafe fn example(df: &DataFrame) -> DataFrame {
    let iterator = (0..9).into_iter().map(Some);
    df.take_opt_iter_unchecked(iterator, None)
}

pub fn take<T: AsTakeIndex + Sync>(&self, indices: &T) -> Result<Self>

Take DataFrame rows by index values.

Example

use polars::prelude::*;
fn example(df: &DataFrame) -> Result<DataFrame> {
    let idx = vec![0, 1, 9];
    df.take(&idx)
}

pub fn rename(&mut self, column: &str, name: &str) -> Result<&mut Self>

Rename a column in the DataFrame

Example

use polars::prelude::*;
fn example(df: &mut DataFrame) -> Result<&mut DataFrame> {
    let original_name = "foo";
    let new_name = "bar";
    df.rename(original_name, new_name)
}

pub fn sort_in_place(
    &mut self,
    by_column: &str,
    reverse: bool
) -> Result<&mut Self>

Sort DataFrame in place by a column.

pub fn sort(&self, by_column: &str, reverse: bool) -> Result<Self>

Return a sorted clone of this DataFrame.

pub fn replace<S: IntoSeries>(
    &mut self,
    column: &str,
    new_col: S
) -> Result<&mut Self>

Replace a column with a series.

pub fn replace_at_idx<S: IntoSeries>(
    &mut self,
    idx: usize,
    new_col: S
) -> Result<&mut Self>

Replace column at index idx with a series.

Example

use polars::prelude::*;
let s0 = Series::new("foo", &["ham", "spam", "egg"]);
let s1 = Series::new("ascii", &[70, 79, 79]);
let mut df = DataFrame::new(vec![s0, s1]).unwrap();

// Add 32 to get lowercase ascii values
df.replace_at_idx(1, df.select_at_idx(1).unwrap() + 32);

pub fn apply<F, S>(&mut self, column: &str, f: F) -> Result<&mut Self> where
    F: FnOnce(&Series) -> S,
    S: IntoSeries, 

Apply a closure to a column. This is the recommended way to do in place modification.

Example

use polars::prelude::*;
let s0 = Series::new("foo", &["ham", "spam", "egg"]);
let s1 = Series::new("names", &["Jean", "Claude", "van"]);
let mut df = DataFrame::new(vec![s0, s1]).unwrap();

fn str_to_len(str_val: &Series) -> Series {
    str_val.utf8()
        .unwrap()
        .into_iter()
        .map(|opt_name: Option<&str>| {
            opt_name.map(|name: &str| name.len() as u32)
         })
        .collect::<UInt32Chunked>()
        .into_series()
}

// Replace the names column by the length of the names.
df.apply("names", str_to_len);

Results in:

+--------+-------+
| foo    |       |
| ---    | names |
| str    | u32   |
+========+=======+
| "ham"  | 4     |
+--------+-------+
| "spam" | 6     |
+--------+-------+
| "egg"  | 3     |
+--------+-------+

pub fn apply_at_idx<F, S>(&mut self, idx: usize, f: F) -> Result<&mut Self> where
    F: FnOnce(&Series) -> S,
    S: IntoSeries, 

Apply a closure to a column at index idx. This is the recommended way to do in place modification.

Example

use polars::prelude::*;
let s0 = Series::new("foo", &["ham", "spam", "egg"]);
let s1 = Series::new("ascii", &[70, 79, 79]);
let mut df = DataFrame::new(vec![s0, s1]).unwrap();

// Add 32 to get lowercase ascii values
df.apply_at_idx(1, |s| s + 32);

Results in:

+--------+-------+
| foo    | ascii |
| ---    | ---   |
| str    | i32   |
+========+=======+
| "ham"  | 102   |
+--------+-------+
| "spam" | 111   |
+--------+-------+
| "egg"  | 111   |
+--------+-------+

pub fn may_apply_at_idx<F, S>(&mut self, idx: usize, f: F) -> Result<&mut Self> where
    F: FnOnce(&Series) -> Result<S>,
    S: IntoSeries, 

Apply a closure that may fail to a column at index idx. This is the recommended way to do in place modification.

Example

This is the idomatic way to replace some values a column of a DataFrame given range of indexes.

let s0 = Series::new("foo", &["ham", "spam", "egg", "bacon", "quack"]);
let s1 = Series::new("values", &[1, 2, 3, 4, 5]);
let mut df = DataFrame::new(vec![s0, s1]).unwrap();

let idx = &[0, 1, 4];

df.may_apply("foo", |s| {
    s.utf8()?
    .set_at_idx_with(idx, |opt_val| opt_val.map(|string| format!("{}-is-modified", string)))
});

Results in:

+---------------------+--------+
| foo                 | values |
| ---                 | ---    |
| str                 | i32    |
+=====================+========+
| "ham-is-modified"   | 1      |
+---------------------+--------+
| "spam-is-modified"  | 2      |
+---------------------+--------+
| "egg"               | 3      |
+---------------------+--------+
| "bacon"             | 4      |
+---------------------+--------+
| "quack-is-modified" | 5      |
+---------------------+--------+

pub fn may_apply<F, S>(&mut self, column: &str, f: F) -> Result<&mut Self> where
    F: FnOnce(&Series) -> Result<S>,
    S: IntoSeries, 

Apply a closure that may fail to a column. This is the recommended way to do in place modification.

Example

This is the idomatic way to replace some values a column of a DataFrame given a boolean mask.

let s0 = Series::new("foo", &["ham", "spam", "egg", "bacon", "quack"]);
let s1 = Series::new("values", &[1, 2, 3, 4, 5]);
let mut df = DataFrame::new(vec![s0, s1]).unwrap();

// create a mask
let mask = || {
    (df.column("values")?.lt_eq(1) | df.column("values")?.gt_eq(5))
};
let mask = mask().unwrap();

df.may_apply("foo", |s| {
    s.utf8()?
    .set(&mask, Some("not_within_bounds"))
});

Results in:

+---------------------+--------+
| foo                 | values |
| ---                 | ---    |
| str                 | i32    |
+=====================+========+
| "not_within_bounds" | 1      |
+---------------------+--------+
| "spam"              | 2      |
+---------------------+--------+
| "egg"               | 3      |
+---------------------+--------+
| "bacon"             | 4      |
+---------------------+--------+
| "not_within_bounds" | 5      |
+---------------------+--------+

pub fn slice(&self, offset: usize, length: usize) -> Result<Self>

Slice the DataFrame along the rows.

pub fn head(&self, length: Option<usize>) -> Self

Get the head of the DataFrame

pub fn tail(&self, length: Option<usize>) -> Self

Get the tail of the DataFrame

pub fn as_record_batches(&self) -> Result<Vec<RecordBatch>>

Transform the underlying chunks in the DataFrame to Arrow RecordBatches

pub fn iter_record_batches(
    &mut self,
    buffer_size: usize
) -> impl Iterator<Item = RecordBatch> + '_

pub fn reverse(&self) -> Self

Get a DataFrame with all the columns in reversed order

pub fn shift(&self, periods: i32) -> Result<Self>

Shift the values by a given period and fill the parts that will be empty due to this operation with Nones.

See the method on Series for more info on the shift operation.

pub fn fill_none(&self, strategy: FillNoneStrategy) -> Result<Self>

Replace None values with one of the following strategies:

• Forward fill (replace None with the previous value)
• Backward fill (replace None with the next value)
• Mean fill (replace None with the mean of the whole array)
• Min fill (replace None with the minimum of the whole array)
• Max fill (replace None with the maximum of the whole array)

See the method on Series for more info on the fill_none operation.

pub fn pipe<F, B>(self, f: F) -> Result<B> where
    F: Fn(DataFrame) -> Result<B>, 

Pipe different functions/ closure operations that work on a DataFrame together.

pub fn pipe_mut<F, B>(&mut self, f: F) -> Result<B> where
    F: Fn(&mut DataFrame) -> Result<B>, 

Pipe different functions/ closure operations that work on a DataFrame together.

pub fn pipe_with_args<F, B, Args>(self, f: F, args: Args) -> Result<B> where
    F: Fn(DataFrame, Args) -> Result<B>, 

Pipe different functions/ closure operations that work on a DataFrame together.

impl DataFrame

pub fn frame_equal(&self, other: &DataFrame) -> bool

Trait Implementations

impl Clone for DataFrame

fn clone(&self) -> DataFrame

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for DataFrame

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

Formats the value using the given formatter.

impl Display for DataFrame

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

Formats the value using the given formatter.

impl FromIterator<Series> for DataFrame

fn from_iter<T: IntoIterator<Item = Series>>(iter: T) -> Self

Panics

Panics if Series have different lengths.

impl<'_> Index<&'_ str> for DataFrame

type Output = Series

The returned type after indexing.

fn index(&self, index: &str) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<Range<usize>> for DataFrame

type Output = [Series]

The returned type after indexing.

fn index(&self, index: Range<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for DataFrame

type Output = [Series]

The returned type after indexing.

fn index(&self, index: RangeFrom<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeFull> for DataFrame

type Output = [Series]

The returned type after indexing.

fn index(&self, index: RangeFull) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeInclusive<usize>> for DataFrame

type Output = [Series]

The returned type after indexing.

fn index(&self, index: RangeInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for DataFrame

type Output = [Series]

The returned type after indexing.

fn index(&self, index: RangeTo<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<RangeToInclusive<usize>> for DataFrame

type Output = [Series]

The returned type after indexing.

fn index(&self, index: RangeToInclusive<usize>) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<usize> for DataFrame

type Output = Series

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl IndexMut<usize> for DataFrame

Gives mutable access to a DataFrame. Warning: Use with care, if you modify the Series by replacing it with a different lengthed Series you've invalidated the DataFrame.

fn index_mut(&mut self, index: usize) -> &mut Self::Output

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