lineage

A Mendelian genetics simulation library and CLI for educational use.

lineage models genes, chromosomes, individuals, and populations at the level of classical genetics. It is designed to be used either as an Erlang/OTP application that emits JSON, or as a Gleam library compiled to JavaScript for use in interactive web-based teaching tools.

Running the CLI

The default target (lineage.gleam, compiled for Erlang/OTP) simulates a population of garden peas (Pisum sativum) over a number of generations and writes the result to disk.

gleam run                  # 10 individuals, 10 generations (defaults)
gleam run -- 100 20        # 100 individuals, 20 generations

A random individual from the final population is chosen as the center of a family tree. Three files are written to the current directory, all sharing one freshly generated UUID as their basename:

• <uuid>.json - the full population keyed by generation number, with each individual’s name (UUID), sex, fertility, parentage, phenotype, and raw genome
• <uuid>-phenotype.svg - the chosen individual’s family tree, rendered with each member’s expressed phenotype icons
• <uuid>-genes.svg - the same family tree, rendered with each member’s raw genotype badges instead

The UUID and the three file paths are printed to stdout once the files have been written.

Running the UI

lineage/ui.gleam is a browser-based Lustre app for interactively exploring a simulated population — browsing individuals by generation, filtering by phenotype, and inspecting a family tree — compiled to JavaScript instead of Erlang/OTP.

gleam build --target=javascript

Then serve the project root with any static file server (opening index.html directly via file:// won’t work, since it loads the compiled app as an ES module) and open it in a browser, e.g.:

python3 -m http.server

index.html loads build/dev/javascript/lineage/lineage/ui.mjs and calls its main function, along with crypto-shim.mjs, which polyfills the Node node:crypto import that gleam_crypto/youid pull in on the JavaScript target.

Core concepts

Gene and alleles

A Gene has a name, a fixed position on a chromosome, a set of valid alleles, and an optional expression rule that maps a list of alleles to a phenotype.

Expression rules

The gene/dominance module provides ready-made expression rules. simple covers classical dominant-recessive inheritance:

import lineage/gene
import lineage/gene/dominance
import gleam/set
import gleam/option

let seed_shape = gene.Gene(
  "Seed shape",
  gene.Autosome(5, 50),
  set.from_list(["R", "w"]),
  option.Some(dominance.simple(#("R", "round"), #("w", "wrinkled"))),
)

Species rules

A SpeciesRules value bundles a genome (list of genes), ploidity, a sex predicate, and a fertility predicate into a single configuration that is passed to individual and population functions.

import lineage/individual

let rules = individual.SpeciesRules(
  individual.no_sex,
  2,
  individual.always_fertile,
  genome,
)

Population simulation

import lineage/population
import lineage/species/pea

let rules = population.PopulationRules(
  population.select_all,
  function.identity,
  fn(_) { 20 },
)

pea.create_multiple(20)
|> population.from_list
|> population.simulate(5, rules)

Garden pea reference species

The lineage/species/pea module provides a ready-to-use definition of Mendel’s seven traits from his original pea experiments: seed shape, stem length, cotyledon colour, flower colour, pod colour, pod form, and flower position.

Project structure

src/
  lineage.gleam                  # CLI entry point
  lineage/
    gene.gleam                   # Gene, Allele, GenePosition types; JSON encode/decode
    gene/dominance.gleam         # Expression rules (simple dominance)
    chromosome.gleam             # Chromosome, ChromosomeSet, gamete formation
    individual.gleam             # Individual, mating, phenotype resolution
    population.gleam             # Population, generational simulation
    heritage.gleam                # Ancestry/family-tree graph
    algorithms.gleam             # Shared collection utilities
    species/pea.gleam            # Pisum sativum species definition
    export/svg.gleam             # Family-tree SVG export
    ui.gleam                     # Browser UI (Lustre, JavaScript target)

Development

gleam run          # Run the CLI with default arguments
gleam test         # Run the test suite
gleam docs build   # Build HTML documentation