1.2.1.1 Series🔗ℹ

A series is a typed, one-dimensional column. series infers a dtype or takes #:dtype; polars-null marks missing entries.

> (series '(1 2 3 4 5) #:name "ints")

shape: (5,) Series: 'ints' [i64] [ 1 2 3 4 5 ]

> (define s1 (series '(1 2 3 4 5) #:name "ints"))

> (define s2 (series '(1 2 3 4 5) #:name "uints" #:dtype 'u64))

> (list (dtype s1) (dtype s2))

'(int64 uint64)

1.2.1.2 Dataframe🔗ℹ

A dataframe is a collection of equal-length, uniquely named series.

> (define df     (~> (dataframe          (list (series '("Alice Archer" "Ben Brown" "Chloe Cooper" "Daniel Donovan")                        #:name "name")                (series (list (datetime 1997 1 10) (datetime 1985 2 15)                              (datetime 1983 3 22) (datetime 1981 4 30))                        #:name "birthdate")                (series '(57.9 72.5 53.6 83.1) #:name "weight")                (series '(1.56 1.77 1.65 1.75) #:name "height")))         (with-columns (cast "birthdate" 'date))))

> df

shape: (4, 4) ┌────────────────┬────────────┬────────┬────────┐ │ name           ┆ birthdate  ┆ weight ┆ height │ │ ---            ┆ ---        ┆ ---    ┆ ---    │ │ str            ┆ date       ┆ f64    ┆ f64    │ ╞════════════════╪════════════╪════════╪════════╡ │ Alice Archer   ┆ 1997-01-10 ┆ 57.9   ┆ 1.56   │ │ Ben Brown      ┆ 1985-02-15 ┆ 72.5   ┆ 1.77   │ │ Chloe Cooper   ┆ 1983-03-22 ┆ 53.6   ┆ 1.65   │ │ Daniel Donovan ┆ 1981-04-30 ┆ 83.1   ┆ 1.75   │ └────────────────┴────────────┴────────┴────────┘

1.2.1.3 Schema🔗ℹ

> (for ([name (column-names df)])     (printf "~a: ~a\n" name (dtype (ref df #:columns name))))

name: string birthdate: date weight: float64 height: float64

The #:dtype of each series plays the role of schema / schema_overrides:

> (dataframe    (list (series '("Alice" "Ben" "Chloe" "Daniel") #:name "name")          (series '(27 39 41 43) #:name "age" #:dtype 'u8)))

shape: (4, 2) ┌────────┬─────┐ │ name   ┆ age │ │ ---    ┆ --- │ │ str    ┆ u8  │ ╞════════╪═════╡ │ Alice  ┆ 27  │ │ Ben    ┆ 39  │ │ Chloe  ┆ 41  │ │ Daniel ┆ 43  │ └────────┴─────┘

API gap: no schema accessor on a dataframe.

1.2.1.4 Data types🔗ℹ

Dtype spellings accepted by series’ #:dtype:

Categorical and Enum values read back as symbols (Categorical, Enum and Decimal). A Decimal column, read from Parquet, has dtype '(decimal precision scale) and exact rational values, but no #:dtype spelling.

Long spellings ('int32, 'float64, 'string, …) are accepted too. Values that mix ints and floats promote to 'f64; see dtype promotion.

API gap: cast is asymmetric with series here — it accepts only the long spellings, so (cast "v" 'f64) is an error where (series '(1) #:dtype 'f64) is fine.

> (dtype (cast (series '(1 2 3)) 'float64))

'float64

> (dtype (cast (series '(1 2 3)) 'f64))

->compat-dtype: unsupported cast target 'f64