Skip to content

data

Small example datasets, as polars DataFrames: from ggrust.data import penguins.

Each name reads its CSV file shipped with ggrust on access and returns a new DataFrame. Sources and licenses are in THIRD_PARTY_NOTICES.md; the files are written by scripts/make_datasets.R. Categorical columns that are R factors in the source are pl.Enum columns with the same level order, so plots show the levels as ggplot2 does.

  • penguins: 344 Palmer Archipelago penguins, 3 species (CC0).
  • mpg: fuel economy of 234 cars, 1999 and 2008 (ggplot2's mpg, MIT).
  • economics: monthly US economic series, 1967 to 2015 (ggplot2's economics, MIT).
  • iris: Fisher's 150 iris flowers, 3 species (public domain).

An unknown name raises DatasetNotFoundError with a close match (ggrust.data.pengiuns); from ggrust.data import pengiuns raises Python's own ImportError, which drops that message.

What it does not do: download anything, or cache frames (each access reads the file, a millisecond or two, so callers never share a frame).

Examples:

>>> from ggrust import *
>>> from ggrust.data import penguins
>>> penguins.shape
(344, 8)
>>> plot = ggplot(penguins, aes("flipper_length_mm", "body_mass_g", color="species")) + (
...     geom_point(na_rm=True)
... )

economics module-attribute

economics = shape: (574, 6)
┌────────────┬─────────┬────────────┬─────────┬─────────┬──────────┐
│ date       ┆ pce     ┆ pop        ┆ psavert ┆ uempmed ┆ unemploy │
│ ---        ┆ ---     ┆ ---        ┆ ---     ┆ ---     ┆ ---      │
│ date       ┆ f64     ┆ f64        ┆ f64     ┆ f64     ┆ i64      │
╞════════════╪═════════╪════════════╪═════════╪═════════╪══════════╡
│ 1967-07-01 ┆ 506.7   ┆ 198712.0   ┆ 12.6    ┆ 4.5     ┆ 2944     │
│ 1967-08-01 ┆ 509.8   ┆ 198911.0   ┆ 12.6    ┆ 4.7     ┆ 2945     │
│ 1967-09-01 ┆ 515.6   ┆ 199113.0   ┆ 11.9    ┆ 4.6     ┆ 2958     │
│ 1967-10-01 ┆ 512.2   ┆ 199311.0   ┆ 12.9    ┆ 4.9     ┆ 3143     │
│ 1967-11-01 ┆ 517.4   ┆ 199498.0   ┆ 12.8    ┆ 4.7     ┆ 3066     │
│ …          ┆ …       ┆ …          ┆ …       ┆ …       ┆ …        │
│ 2014-12-01 ┆ 12062.0 ┆ 319746.157 ┆ 7.6     ┆ 12.9    ┆ 8717     │
│ 2015-01-01 ┆ 12046.0 ┆ 319928.646 ┆ 7.7     ┆ 13.2    ┆ 8903     │
│ 2015-02-01 ┆ 12082.4 ┆ 320074.511 ┆ 7.9     ┆ 12.9    ┆ 8610     │
│ 2015-03-01 ┆ 12158.3 ┆ 320230.786 ┆ 7.4     ┆ 12.0    ┆ 8504     │
│ 2015-04-01 ┆ 12193.8 ┆ 320402.295 ┆ 7.6     ┆ 11.5    ┆ 8526     │
└────────────┴─────────┴────────────┴─────────┴─────────┴──────────┘

Two-dimensional data structure representing data as a table with rows and columns.

Parameters:

  • data (dict, Sequence, ndarray, Series, or pandas.DataFrame) –

    Two-dimensional data in various forms; dict input must contain Sequences, Generators, or a range. Sequence may contain Series or other Sequences.

  • schema (Sequence of str, (str,DataType) pairs, or a {str:DataType,} dict) –

    The schema of the resulting DataFrame. The schema may be declared in several ways:

    • As a dict of {name:type} pairs; if type is None, it will be auto-inferred.
    • As a list of column names; in this case types are automatically inferred.
    • As a list of (name,type) pairs; this is equivalent to the dictionary form.

    The order of the schema determines the column order of the frame. When passing a dict, its insertion order is respected. To override specific column data types by name without changing column order, use schema_overrides instead.

    If you supply a list of column names that does not match the names in the underlying data, the names given here will overwrite them. The number of names given in the schema should match the underlying data dimensions.

    If set to None (default), the schema is inferred from the data.

  • schema_overrides (dict, default: None ) –

    Support type specification or override of one or more columns; note that any dtypes inferred from the schema param will be overridden.

    The number of entries in the schema should match the underlying data dimensions, unless a sequence of dictionaries is being passed, in which case a partial schema can be declared to prevent specific fields from being loaded.

  • strict (bool, default: True ) –

    Throw an error if any data value does not exactly match the given or inferred data type for that column. If set to False, values that do not match the data type are cast to that data type or, if casting is not possible, set to null instead.

  • orient ((col, row), default: 'col' ) –

    Whether to interpret two-dimensional data as columns or as rows. If None, the orientation is inferred by matching the columns and data dimensions. If this does not yield conclusive results, column orientation is used.

  • infer_schema_length (int or None) –

    The maximum number of rows to scan for schema inference. If set to None, the full data may be scanned (this can be slow). This parameter only applies if the input data is a sequence or generator of rows; other input is read as-is.

  • nan_to_null (bool, default: False ) –

    If the data comes from one or more numpy arrays, can optionally convert input data np.nan values to null instead. This is a no-op for all other input data.

  • height (int or None, default: None ) –

    Allows constructing DataFrames with 0 width and a specified height. If passed with data, ensures the resulting DataFrame has this height.

    .. warning:: This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Notes

Polars explicitly does not support subclassing of its core data types. See the following GitHub issue for possible workarounds: https://github.com/pola-rs/polars/issues/2846#issuecomment-1711799869

Examples:

Constructing a DataFrame from a dictionary:

>>> data = {"a": [1, 2], "b": [3, 4]}
>>> df = pl.DataFrame(data)
>>> df
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Notice that the dtypes are automatically inferred as polars Int64:

>>> df.dtypes
[Int64, Int64]

To specify a more detailed/specific frame schema you can supply the schema parameter with a dictionary of (name,dtype) pairs...

>>> data = {"col1": [0, 2], "col2": [3, 7]}
>>> df2 = pl.DataFrame(data, schema={"col1": pl.Float32, "col2": pl.Int64})
>>> df2
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 0.0  ┆ 3    │
│ 2.0  ┆ 7    │
└──────┴──────┘

...a sequence of (name,dtype) pairs...

>>> data = {"col1": [1, 2], "col2": [3, 4]}
>>> df3 = pl.DataFrame(data, schema=[("col1", pl.Float32), ("col2", pl.Int64)])
>>> df3
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

...or a list of typed Series.

>>> data = [
...     pl.Series("col1", [1, 2], dtype=pl.Float32),
...     pl.Series("col2", [3, 4], dtype=pl.Int64),
... ]
>>> df4 = pl.DataFrame(data)
>>> df4
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

Constructing a DataFrame from a numpy ndarray, specifying column names:

>>> import numpy as np
>>> data = np.array([(1, 2), (3, 4)], dtype=np.int64)
>>> df5 = pl.DataFrame(data, schema=["a", "b"], orient="col")
>>> df5
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Constructing a DataFrame from a list of lists, row orientation specified:

>>> data = [[1, 2, 3], [4, 5, 6]]
>>> df6 = pl.DataFrame(data, schema=["a", "b", "c"], orient="row")
>>> df6
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

iris module-attribute

iris = shape: (150, 5)
┌──────────────┬─────────────┬──────────────┬─────────────┬───────────┐
│ sepal_length ┆ sepal_width ┆ petal_length ┆ petal_width ┆ species   │
│ ---          ┆ ---         ┆ ---          ┆ ---         ┆ ---       │
│ f64          ┆ f64         ┆ f64          ┆ f64         ┆ enum      │
╞══════════════╪═════════════╪══════════════╪═════════════╪═══════════╡
│ 5.1          ┆ 3.5         ┆ 1.4          ┆ 0.2         ┆ setosa    │
│ 4.9          ┆ 3.0         ┆ 1.4          ┆ 0.2         ┆ setosa    │
│ 4.7          ┆ 3.2         ┆ 1.3          ┆ 0.2         ┆ setosa    │
│ 4.6          ┆ 3.1         ┆ 1.5          ┆ 0.2         ┆ setosa    │
│ 5.0          ┆ 3.6         ┆ 1.4          ┆ 0.2         ┆ setosa    │
│ …            ┆ …           ┆ …            ┆ …           ┆ …         │
│ 6.7          ┆ 3.0         ┆ 5.2          ┆ 2.3         ┆ virginica │
│ 6.3          ┆ 2.5         ┆ 5.0          ┆ 1.9         ┆ virginica │
│ 6.5          ┆ 3.0         ┆ 5.2          ┆ 2.0         ┆ virginica │
│ 6.2          ┆ 3.4         ┆ 5.4          ┆ 2.3         ┆ virginica │
│ 5.9          ┆ 3.0         ┆ 5.1          ┆ 1.8         ┆ virginica │
└──────────────┴─────────────┴──────────────┴─────────────┴───────────┘

Two-dimensional data structure representing data as a table with rows and columns.

Parameters:

  • data (dict, Sequence, ndarray, Series, or pandas.DataFrame) –

    Two-dimensional data in various forms; dict input must contain Sequences, Generators, or a range. Sequence may contain Series or other Sequences.

  • schema (Sequence of str, (str,DataType) pairs, or a {str:DataType,} dict) –

    The schema of the resulting DataFrame. The schema may be declared in several ways:

    • As a dict of {name:type} pairs; if type is None, it will be auto-inferred.
    • As a list of column names; in this case types are automatically inferred.
    • As a list of (name,type) pairs; this is equivalent to the dictionary form.

    The order of the schema determines the column order of the frame. When passing a dict, its insertion order is respected. To override specific column data types by name without changing column order, use schema_overrides instead.

    If you supply a list of column names that does not match the names in the underlying data, the names given here will overwrite them. The number of names given in the schema should match the underlying data dimensions.

    If set to None (default), the schema is inferred from the data.

  • schema_overrides (dict, default: None ) –

    Support type specification or override of one or more columns; note that any dtypes inferred from the schema param will be overridden.

    The number of entries in the schema should match the underlying data dimensions, unless a sequence of dictionaries is being passed, in which case a partial schema can be declared to prevent specific fields from being loaded.

  • strict (bool, default: True ) –

    Throw an error if any data value does not exactly match the given or inferred data type for that column. If set to False, values that do not match the data type are cast to that data type or, if casting is not possible, set to null instead.

  • orient ((col, row), default: 'col' ) –

    Whether to interpret two-dimensional data as columns or as rows. If None, the orientation is inferred by matching the columns and data dimensions. If this does not yield conclusive results, column orientation is used.

  • infer_schema_length (int or None) –

    The maximum number of rows to scan for schema inference. If set to None, the full data may be scanned (this can be slow). This parameter only applies if the input data is a sequence or generator of rows; other input is read as-is.

  • nan_to_null (bool, default: False ) –

    If the data comes from one or more numpy arrays, can optionally convert input data np.nan values to null instead. This is a no-op for all other input data.

  • height (int or None, default: None ) –

    Allows constructing DataFrames with 0 width and a specified height. If passed with data, ensures the resulting DataFrame has this height.

    .. warning:: This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Notes

Polars explicitly does not support subclassing of its core data types. See the following GitHub issue for possible workarounds: https://github.com/pola-rs/polars/issues/2846#issuecomment-1711799869

Examples:

Constructing a DataFrame from a dictionary:

>>> data = {"a": [1, 2], "b": [3, 4]}
>>> df = pl.DataFrame(data)
>>> df
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Notice that the dtypes are automatically inferred as polars Int64:

>>> df.dtypes
[Int64, Int64]

To specify a more detailed/specific frame schema you can supply the schema parameter with a dictionary of (name,dtype) pairs...

>>> data = {"col1": [0, 2], "col2": [3, 7]}
>>> df2 = pl.DataFrame(data, schema={"col1": pl.Float32, "col2": pl.Int64})
>>> df2
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 0.0  ┆ 3    │
│ 2.0  ┆ 7    │
└──────┴──────┘

...a sequence of (name,dtype) pairs...

>>> data = {"col1": [1, 2], "col2": [3, 4]}
>>> df3 = pl.DataFrame(data, schema=[("col1", pl.Float32), ("col2", pl.Int64)])
>>> df3
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

...or a list of typed Series.

>>> data = [
...     pl.Series("col1", [1, 2], dtype=pl.Float32),
...     pl.Series("col2", [3, 4], dtype=pl.Int64),
... ]
>>> df4 = pl.DataFrame(data)
>>> df4
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

Constructing a DataFrame from a numpy ndarray, specifying column names:

>>> import numpy as np
>>> data = np.array([(1, 2), (3, 4)], dtype=np.int64)
>>> df5 = pl.DataFrame(data, schema=["a", "b"], orient="col")
>>> df5
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Constructing a DataFrame from a list of lists, row orientation specified:

>>> data = [[1, 2, 3], [4, 5, 6]]
>>> df6 = pl.DataFrame(data, schema=["a", "b", "c"], orient="row")
>>> df6
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

mpg module-attribute

mpg = shape: (234, 11)
┌──────────────┬────────┬───────┬──────┬───┬─────┬─────┬─────┬─────────┐
│ manufacturer ┆ model  ┆ displ ┆ year ┆ … ┆ cty ┆ hwy ┆ fl  ┆ class   │
│ ---          ┆ ---    ┆ ---   ┆ ---  ┆   ┆ --- ┆ --- ┆ --- ┆ ---     │
│ str          ┆ str    ┆ f64   ┆ i64  ┆   ┆ i64 ┆ i64 ┆ str ┆ str     │
╞══════════════╪════════╪═══════╪══════╪═══╪═════╪═════╪═════╪═════════╡
│ audi         ┆ a4     ┆ 1.8   ┆ 1999 ┆ … ┆ 18  ┆ 29  ┆ p   ┆ compact │
│ audi         ┆ a4     ┆ 1.8   ┆ 1999 ┆ … ┆ 21  ┆ 29  ┆ p   ┆ compact │
│ audi         ┆ a4     ┆ 2.0   ┆ 2008 ┆ … ┆ 20  ┆ 31  ┆ p   ┆ compact │
│ audi         ┆ a4     ┆ 2.0   ┆ 2008 ┆ … ┆ 21  ┆ 30  ┆ p   ┆ compact │
│ audi         ┆ a4     ┆ 2.8   ┆ 1999 ┆ … ┆ 16  ┆ 26  ┆ p   ┆ compact │
│ …            ┆ …      ┆ …     ┆ …    ┆ … ┆ …   ┆ …   ┆ …   ┆ …       │
│ volkswagen   ┆ passat ┆ 2.0   ┆ 2008 ┆ … ┆ 19  ┆ 28  ┆ p   ┆ midsize │
│ volkswagen   ┆ passat ┆ 2.0   ┆ 2008 ┆ … ┆ 21  ┆ 29  ┆ p   ┆ midsize │
│ volkswagen   ┆ passat ┆ 2.8   ┆ 1999 ┆ … ┆ 16  ┆ 26  ┆ p   ┆ midsize │
│ volkswagen   ┆ passat ┆ 2.8   ┆ 1999 ┆ … ┆ 18  ┆ 26  ┆ p   ┆ midsize │
│ volkswagen   ┆ passat ┆ 3.6   ┆ 2008 ┆ … ┆ 17  ┆ 26  ┆ p   ┆ midsize │
└──────────────┴────────┴───────┴──────┴───┴─────┴─────┴─────┴─────────┘

Two-dimensional data structure representing data as a table with rows and columns.

Parameters:

  • data (dict, Sequence, ndarray, Series, or pandas.DataFrame) –

    Two-dimensional data in various forms; dict input must contain Sequences, Generators, or a range. Sequence may contain Series or other Sequences.

  • schema (Sequence of str, (str,DataType) pairs, or a {str:DataType,} dict) –

    The schema of the resulting DataFrame. The schema may be declared in several ways:

    • As a dict of {name:type} pairs; if type is None, it will be auto-inferred.
    • As a list of column names; in this case types are automatically inferred.
    • As a list of (name,type) pairs; this is equivalent to the dictionary form.

    The order of the schema determines the column order of the frame. When passing a dict, its insertion order is respected. To override specific column data types by name without changing column order, use schema_overrides instead.

    If you supply a list of column names that does not match the names in the underlying data, the names given here will overwrite them. The number of names given in the schema should match the underlying data dimensions.

    If set to None (default), the schema is inferred from the data.

  • schema_overrides (dict, default: None ) –

    Support type specification or override of one or more columns; note that any dtypes inferred from the schema param will be overridden.

    The number of entries in the schema should match the underlying data dimensions, unless a sequence of dictionaries is being passed, in which case a partial schema can be declared to prevent specific fields from being loaded.

  • strict (bool, default: True ) –

    Throw an error if any data value does not exactly match the given or inferred data type for that column. If set to False, values that do not match the data type are cast to that data type or, if casting is not possible, set to null instead.

  • orient ((col, row), default: 'col' ) –

    Whether to interpret two-dimensional data as columns or as rows. If None, the orientation is inferred by matching the columns and data dimensions. If this does not yield conclusive results, column orientation is used.

  • infer_schema_length (int or None) –

    The maximum number of rows to scan for schema inference. If set to None, the full data may be scanned (this can be slow). This parameter only applies if the input data is a sequence or generator of rows; other input is read as-is.

  • nan_to_null (bool, default: False ) –

    If the data comes from one or more numpy arrays, can optionally convert input data np.nan values to null instead. This is a no-op for all other input data.

  • height (int or None, default: None ) –

    Allows constructing DataFrames with 0 width and a specified height. If passed with data, ensures the resulting DataFrame has this height.

    .. warning:: This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Notes

Polars explicitly does not support subclassing of its core data types. See the following GitHub issue for possible workarounds: https://github.com/pola-rs/polars/issues/2846#issuecomment-1711799869

Examples:

Constructing a DataFrame from a dictionary:

>>> data = {"a": [1, 2], "b": [3, 4]}
>>> df = pl.DataFrame(data)
>>> df
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Notice that the dtypes are automatically inferred as polars Int64:

>>> df.dtypes
[Int64, Int64]

To specify a more detailed/specific frame schema you can supply the schema parameter with a dictionary of (name,dtype) pairs...

>>> data = {"col1": [0, 2], "col2": [3, 7]}
>>> df2 = pl.DataFrame(data, schema={"col1": pl.Float32, "col2": pl.Int64})
>>> df2
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 0.0  ┆ 3    │
│ 2.0  ┆ 7    │
└──────┴──────┘

...a sequence of (name,dtype) pairs...

>>> data = {"col1": [1, 2], "col2": [3, 4]}
>>> df3 = pl.DataFrame(data, schema=[("col1", pl.Float32), ("col2", pl.Int64)])
>>> df3
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

...or a list of typed Series.

>>> data = [
...     pl.Series("col1", [1, 2], dtype=pl.Float32),
...     pl.Series("col2", [3, 4], dtype=pl.Int64),
... ]
>>> df4 = pl.DataFrame(data)
>>> df4
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

Constructing a DataFrame from a numpy ndarray, specifying column names:

>>> import numpy as np
>>> data = np.array([(1, 2), (3, 4)], dtype=np.int64)
>>> df5 = pl.DataFrame(data, schema=["a", "b"], orient="col")
>>> df5
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Constructing a DataFrame from a list of lists, row orientation specified:

>>> data = [[1, 2, 3], [4, 5, 6]]
>>> df6 = pl.DataFrame(data, schema=["a", "b", "c"], orient="row")
>>> df6
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

penguins module-attribute

penguins = shape: (344, 8)
┌───────────┬───────────┬──────────────┬──────────────┬──────────────┬─────────────┬────────┬──────┐
│ species   ┆ island    ┆ bill_length_ ┆ bill_depth_m ┆ flipper_leng ┆ body_mass_g ┆ sex    ┆ year │
│ ---       ┆ ---       ┆ mm           ┆ m            ┆ th_mm        ┆ ---         ┆ ---    ┆ ---  │
│ enum      ┆ enum      ┆ ---          ┆ ---          ┆ ---          ┆ i64         ┆ enum   ┆ i64  │
│           ┆           ┆ f64          ┆ f64          ┆ i64          ┆             ┆        ┆      │
╞═══════════╪═══════════╪══════════════╪══════════════╪══════════════╪═════════════╪════════╪══════╡
│ Adelie    ┆ Torgersen ┆ 39.1         ┆ 18.7         ┆ 181          ┆ 3750        ┆ male   ┆ 2007 │
│ Adelie    ┆ Torgersen ┆ 39.5         ┆ 17.4         ┆ 186          ┆ 3800        ┆ female ┆ 2007 │
│ Adelie    ┆ Torgersen ┆ 40.3         ┆ 18.0         ┆ 195          ┆ 3250        ┆ female ┆ 2007 │
│ Adelie    ┆ Torgersen ┆ null         ┆ null         ┆ null         ┆ null        ┆ null   ┆ 2007 │
│ Adelie    ┆ Torgersen ┆ 36.7         ┆ 19.3         ┆ 193          ┆ 3450        ┆ female ┆ 2007 │
│ …         ┆ …         ┆ …            ┆ …            ┆ …            ┆ …           ┆ …      ┆ …    │
│ Chinstrap ┆ Dream     ┆ 55.8         ┆ 19.8         ┆ 207          ┆ 4000        ┆ male   ┆ 2009 │
│ Chinstrap ┆ Dream     ┆ 43.5         ┆ 18.1         ┆ 202          ┆ 3400        ┆ female ┆ 2009 │
│ Chinstrap ┆ Dream     ┆ 49.6         ┆ 18.2         ┆ 193          ┆ 3775        ┆ male   ┆ 2009 │
│ Chinstrap ┆ Dream     ┆ 50.8         ┆ 19.0         ┆ 210          ┆ 4100        ┆ male   ┆ 2009 │
│ Chinstrap ┆ Dream     ┆ 50.2         ┆ 18.7         ┆ 198          ┆ 3775        ┆ female ┆ 2009 │
└───────────┴───────────┴──────────────┴──────────────┴──────────────┴─────────────┴────────┴──────┘

Two-dimensional data structure representing data as a table with rows and columns.

Parameters:

  • data (dict, Sequence, ndarray, Series, or pandas.DataFrame) –

    Two-dimensional data in various forms; dict input must contain Sequences, Generators, or a range. Sequence may contain Series or other Sequences.

  • schema (Sequence of str, (str,DataType) pairs, or a {str:DataType,} dict) –

    The schema of the resulting DataFrame. The schema may be declared in several ways:

    • As a dict of {name:type} pairs; if type is None, it will be auto-inferred.
    • As a list of column names; in this case types are automatically inferred.
    • As a list of (name,type) pairs; this is equivalent to the dictionary form.

    The order of the schema determines the column order of the frame. When passing a dict, its insertion order is respected. To override specific column data types by name without changing column order, use schema_overrides instead.

    If you supply a list of column names that does not match the names in the underlying data, the names given here will overwrite them. The number of names given in the schema should match the underlying data dimensions.

    If set to None (default), the schema is inferred from the data.

  • schema_overrides (dict, default: None ) –

    Support type specification or override of one or more columns; note that any dtypes inferred from the schema param will be overridden.

    The number of entries in the schema should match the underlying data dimensions, unless a sequence of dictionaries is being passed, in which case a partial schema can be declared to prevent specific fields from being loaded.

  • strict (bool, default: True ) –

    Throw an error if any data value does not exactly match the given or inferred data type for that column. If set to False, values that do not match the data type are cast to that data type or, if casting is not possible, set to null instead.

  • orient ((col, row), default: 'col' ) –

    Whether to interpret two-dimensional data as columns or as rows. If None, the orientation is inferred by matching the columns and data dimensions. If this does not yield conclusive results, column orientation is used.

  • infer_schema_length (int or None) –

    The maximum number of rows to scan for schema inference. If set to None, the full data may be scanned (this can be slow). This parameter only applies if the input data is a sequence or generator of rows; other input is read as-is.

  • nan_to_null (bool, default: False ) –

    If the data comes from one or more numpy arrays, can optionally convert input data np.nan values to null instead. This is a no-op for all other input data.

  • height (int or None, default: None ) –

    Allows constructing DataFrames with 0 width and a specified height. If passed with data, ensures the resulting DataFrame has this height.

    .. warning:: This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Notes

Polars explicitly does not support subclassing of its core data types. See the following GitHub issue for possible workarounds: https://github.com/pola-rs/polars/issues/2846#issuecomment-1711799869

Examples:

Constructing a DataFrame from a dictionary:

>>> data = {"a": [1, 2], "b": [3, 4]}
>>> df = pl.DataFrame(data)
>>> df
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Notice that the dtypes are automatically inferred as polars Int64:

>>> df.dtypes
[Int64, Int64]

To specify a more detailed/specific frame schema you can supply the schema parameter with a dictionary of (name,dtype) pairs...

>>> data = {"col1": [0, 2], "col2": [3, 7]}
>>> df2 = pl.DataFrame(data, schema={"col1": pl.Float32, "col2": pl.Int64})
>>> df2
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 0.0  ┆ 3    │
│ 2.0  ┆ 7    │
└──────┴──────┘

...a sequence of (name,dtype) pairs...

>>> data = {"col1": [1, 2], "col2": [3, 4]}
>>> df3 = pl.DataFrame(data, schema=[("col1", pl.Float32), ("col2", pl.Int64)])
>>> df3
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

...or a list of typed Series.

>>> data = [
...     pl.Series("col1", [1, 2], dtype=pl.Float32),
...     pl.Series("col2", [3, 4], dtype=pl.Int64),
... ]
>>> df4 = pl.DataFrame(data)
>>> df4
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

Constructing a DataFrame from a numpy ndarray, specifying column names:

>>> import numpy as np
>>> data = np.array([(1, 2), (3, 4)], dtype=np.int64)
>>> df5 = pl.DataFrame(data, schema=["a", "b"], orient="col")
>>> df5
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Constructing a DataFrame from a list of lists, row orientation specified:

>>> data = [[1, 2, 3], [4, 5, 6]]
>>> df6 = pl.DataFrame(data, schema=["a", "b", "c"], orient="row")
>>> df6
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

DatasetNotFoundError

DatasetNotFoundError(
    message: str, *, name: str, available: list[str]
)

Bases: ggrust.errors.GgrustError, builtins.AttributeError

Raised when ggrust.data has no dataset of the asked name.

It is an AttributeError, so from ggrust.data import name raises ImportError as for any missing module attribute.

Parameters:

  • message (str) –

    The full message: the name, the available datasets and a close match.

  • name (str) –

    The name that was asked for.

  • available (list of str) –

    The dataset names.

Examples:

>>> import ggrust.data
>>> from ggrust.errors import DatasetNotFoundError
>>> try:
...     frame = ggrust.data.pengiuns
... except DatasetNotFoundError as error:
...     print(error.available)
['economics', 'iris', 'mpg', 'penguins']

did_you_mean

did_you_mean(word: str, candidates: Iterable[str]) -> str

Return "; did you mean 'x'?" for the closest candidate, or "".

Same rule as the engine's suggestions: about one edit (insertion, deletion, substitution or swap of neighbours) per three letters, none for one- and two-letter words; case differences alone always match. No suggestion when several candidates are equally close or word starts several of them.

Parameters:

  • word (str) –

    The misspelt name.

  • candidates (iterable of str) –

    The accepted names.

Returns:

  • str –

    The suggestion, ready to append to a message.