Snailz Docs

Skip to content

# Snailz

`snailz` is a synthetic data generator that models a study of snails in the Pacific Northwest which are growing to unusual size as a result of exposure to pollution. The package generates fully-reproducible datasets of varying sizes and with varying statistical properties, and is intended for classroom use. For example, an instructor can give each learner a unique dataset to analyze, while learners can test their analysis pipelines using datasets they generate themselves.

> The Story

> Years ago, logging companies dumped toxic waste in a remote region of Vancouver Island. As the containers leaked and the pollution spread, some snails in the region began growing unusually large. Your team is now collecting and analyzing specimens from affected regions to determine if exposure to pollution is responsible.

## Usage:

    usage: snailz [-h]
                  [--defaults]
              [--outdir OUTDIR]
                  [--override OVERRIDE [OVERRIDE ...]]
              [--params PARAMS]
                  [--profile]

    options:
      -h, --help            show this help message and exit
      --defaults            show default parameters as JSON
      --outdir OUTDIR       output directory
      --override OVERRIDE [OVERRIDE ...]
                            name=value parameters to override defaults
      --params PARAMS       specify JSON parameter file
      --profile             enable profiling

See the documentation of the `Parameters` class for a description of data generation parameters.

## Schema

An asterisk beside the name of a field indicates that the value may be missing (i.e., the field may be `NULL` in the final database).

table | field | type | purpose
--- | --- | --- | ---
grid | ident | text | unique identifier for each survey grid
| size | int | height and width of survey grid in cells
| spacing | float | size of survey grid cell (meters)
| lat0 | float | southernmost latitude of grid (fractional degrees)
| lon0 | float | westernmost longitude of grid (fractional degrees)
grid_cells | grid_id | text | foreign key reference to grid
| lat | float | foreign key reference to grid cell
| lon | float | foreign key reference to grid cell
| value | float | pollution measurement in that grid cell
machine | ident | text | unique identifier for each piece of laboratory equipment
| name | text | name of piece of laboratory equipment
person | ident | text | unique identifier for member of staff
| family | text | family name of staff member
| personal | text | personal name of staff member
| supervisor_id | text* | foreign key reference to person's supervisor
rating | person_id | text | foreign key reference to person
| machine_id | text | foreign key reference to machine
| certified | bool | whether person is certified to use machine
assay | ident | text | unique identifier for soil assay
| lat | float | foreign key reference to grid cell
| lon | float | foreign key reference to grid cell
| person_id | text | foreign key reference to person who did assay
| machine_id | text | foreign key reference to machine used to do assay
| performed* | date | date that assay was done
assay_readings | assay_id | text | foreign key reference to assay
| reading_id | int | serial number within assay
| contents | text | "C" or "T" showing control or treatment
| reading | float | pollution measurement
species | reference | text | reference genome
| susc_locus | int | location of susceptible locus within genome
| susc_base | text | base that causes significant mutation at that locus
species_loci | ident | int | unique locus serial number
| locus | int | locus where mutation might occur
specimen | ident | text | unique identifier for specimen
| lat | float | foreign key reference to grid cell
| lon | float | foreign key reference to grid cell
| genome | text | specimen genome
| mass | float | specimen mass (g)
| diameter | float | specimen diameter (mm)
| collected* | date | when specimen was collected

## Colophon

`snailz` was inspired by the Palmer Penguins dataset and by conversations with Rohan Alexander about his book Telling Stories with Data.

My thanks to everyone who built the tools this project relies on, including:

- faker for synthesizing data.
- mkdocs for documentation.
- ruff for checking the code.
- sqlite and sqlite-utils for persistence.
- taskipy for running tasks.
- uv for managing packages and the virtual environment.

The snail logo was created by sunar.ko.

## Acknowledgments

- Greg Wilson is a programmer, author, and educator based in Toronto. He was the co-founder and first Executive Director of Software Carpentry and received ACM SIGSOFT's Influential Educator Award in 2020.