1.1 Installing and loading data🔗ℹ

Use Racket 9.3 or later. Install the core package from the Racket catalog:

  raco pkg install --auto datasets-core

From a checkout of the repository, use raco pkg install ./datasets-core instead.

The repository contains two independently installable packages at its root: datasets-core/ and datasets/. Each has an info.rkt declaring a multi-collection package. They contribute different modules to the same datasets collection; package names and module paths need not match. The core package provides datasets/core.

Dataset identifiers are symbols, such as 'iris; column names are strings, such as "sepal-length". Bundled datasets load from installed files and never contact a server; see Downloaded datasets for datasets that are downloaded. There is no need to install R or run an import script.

1.2 Working with columns🔗ℹ

Use dataset-table-column to obtain a column, then ordinary vector operations to inspect its values. A vector index is zero-based.

A selection keeps the source rows and places columns in the order you request:

The column vectors and their strings are immutable. Keep derived results in new values rather than changing the bundled observations. Empty selections, duplicate names, and unknown names are errors; see Registry and loading for the selection rules.

1.3 Recognizing missing observations🔗ℹ

The airquality dataset contains missing ozone and solar-radiation measurements. A missing observation is represented by dataset-missing, a dedicated value recognized by dataset-missing?. It differs from #f, zero, and +nan.0.

Make any filtering decision explicit. For example, the following collects only observed ozone values; it does not modify the original table:

1.4 Reading metadata and category levels🔗ℹ

dataset-info returns an immutable hash whose keys are strings. Its "columns" entry is a list in source column order. Each entry describes one variable, including its normalized name, original spelling, semantic type, units, missing-value count, and category levels.

Labels remain strings in the table. The level list records their intended order; it does not assert that a categorical variable is ordinal. Metadata on a selected table still describes the complete source dataset. See Metadata fields for the field definitions.

1.5 Counting people and indexing months🔗ℹ

A row does not always represent one person. Titanic contains 32 contingency cells, each combining a class, sex, age group, and survival outcome. Its "frequency" column counts people, including zero for empty cells:

AirPassengers instead has one row per calendar month. Year and month are explicit columns, and passenger counts are in thousands:

The Dataset Catalog and Provenance records these conventions alongside source citations and transformation notes. Consult it before interpreting a variable or comparing a dataset with another library’s version.

1.6 Datasets from other packages🔗ℹ

Other packages add datasets to the same catalog. Such a package contributes a directory to the datasets collection, conventionally datasets/suffix-data for a package named datasets-suffix, containing an info.rkt, a registry file, and a data directory with one gzip-compressed .rktd file per dataset:

#lang info

(define datasets-registries '("registry.rktd"))

Once raco setup has indexed the package, dataset-names, dataset-info and load-dataset-table include its datasets, and dataset-packages lists it. Each entry carries the fields in Metadata fields, with package naming the package and tier set to bundled. Names are shared across all installed packages, so two packages declaring the same name is an error naming both. The maintainer importer writes this layout with scripts/import-data.py –package name –target dir.

1.7 Downloaded datasets🔗ℹ

Some datasets are too large to ship in a package. Their metadata is installed like any other, so dataset-names, dataset-info and the catalog describe them without a network connection, but their data is downloaded the first time it is loaded. Such a dataset has tier fetch; its fetch metadata pins the SHA-256 of the file to download.

The first load-dataset-table of a fetch-tier dataset downloads the file, checks its SHA-256, and stores it in the cache; later loads read the cache and contact no server. Every load checks the data’s SHA-256. A failed or mismatched download leaves nothing behind.

The cache is (dataset-cache-directory): "racket-datasets" in Racket’s cache directory, or the directory named by DATASETS_HOME.

fetch-dataset downloads without loading, and dataset-cached? says whether a load would need the network. To use datasets on a machine without network access, fetch them elsewhere, copy the cache directory, and point DATASETS_HOME at the copy. To make sure a load never downloads, pass #:download? #f; a dataset that is not cached is then an error that says how to fetch it. clear-dataset-cache deletes downloaded files, for one dataset or all, and nothing else.