Datasets to try¶

mosaica.datasets fetches a dataset from its publisher, prepares the files its declaration names, builds the database and opens it, skipping each step whose output is still current. Datasets to try lists the datasets with their views, fields, layers and sizes, and mosaica demo NAME... runs load for each and opens their map in a browser. The datasets that are downloaded and prepared need the demo extra, mosaica[demo].

load ¶

load(
    name: str,
    dir: str | PathLike | None = None,
    sample: int | None = None,
    port: int | None = None,
    progress: bool = True,
) -> Database

Fetch, prepare and build a dataset where that has not been done, and open it.

name: one of names().
dir: the directory datasets are kept under, each in a directory of its own name; root() by default.
sample: build from part of the dataset, as describe(name).sample says. The sample is prepared and built beside the whole, from the same fetched files.
port: the port its server listens on, as mosaica.create() takes it.
progress: False draws no progress bars.

A step whose inputs changed since it ran, such as a newer recipe or another mosaica binary, runs again from the start, and the database it makes replaces the one there, writes made to it included.

db = mosaica.datasets.load("geonames", sample=1_000_000)
db.view("world").count()

prepared ¶

prepared(
    name: str,
    dir: str | PathLike | None = None,
    sample: int | None = None,
    progress: bool = True,
) -> Path

Fetch and prepare a dataset where that has not been done, and return the path of its declaration, schema.toml, beside the files it names.

Use it to build and serve the dataset with a mosaica.toml of your own. dir, sample and progress are load's.

names ¶

names() -> list[str]

The names of the datasets, smallest first.

describe ¶

describe(name: str) -> Dataset

The catalogue's entry for one dataset.

root ¶

root() -> Path

Where datasets are kept: MOSAICA_DATASETS when set, else mosaica/datasets in the user's cache directory.

Dataset `dataclass` ¶

One dataset of the catalogue, and what it takes to make.

name, title, items, licence, publisher: what it is.
download: the bytes fetched where the files are not on disk; a checkout of the repository holds those of the two samples. GBIF's whole-snapshot figures are modelled from a 64-part sample and from the ladder's build of an earlier snapshot; the rest were measured.
personas: who mosaica demo offers to view the dataset as, the first by default.
disk: the bytes on disk once built, the fetched files and the bundle included.
bundle: the bytes of the built bundle.
needs: the modules making it imports besides this package's own, which the demo extra installs.
sample: what sample=N keeps, or None where the dataset takes no sample.
per_sample: the bytes downloaded and on disk for each unit of sample=N, as (download, disk), where a sample downloads less than the whole, or None.
fetch, prepare: how load makes it. fetch puts the files a sample needs in a directory, or finds them in a checkout, and returns their paths, the declaration first where there is nothing to prepare. prepare writes schema.toml and the files it names from them, and its module's source and DECLARATION are the recipe, so a change to either prepares the dataset again. It is None where the fetched files are those already.

Persona `dataclass` ¶

Someone to view a dataset as: mosaica demo lists them in its "Viewing as" picker, and db.viewer(persona.terms) reads as one in Python.

id: the persona's name in the page's address, as in ?as=gb.
label, description: what the picker shows.
terms: the access terms the persona holds, or None for one who reads everything.