Lineage

Project Status: Active – The project has reached a usable state and is being actively developed.

Ancestral recombination graph in Asymptote

Installation

Simply add Lineage.asy to your favorite Asymptote search path. The library can be imported with a simple import Lineage statement.

Example

Commented code below (also available in examples/readme.svg).

Lineage example

import Lineage;
settings.outformat = "svg";
// Coordinate represent multiples of 1cm. This is correct for most use cases.
unitsize(1cm);
// Background is transparent by default.
currentlight.background = white;
// Sequences associated with leaves. Can be of type `bool3` to allow missing
// values, represented as non-ancestral markers. `false` -> wild allele,
// true -> derived allele, `default` -> non-ancestral/missing marker.
bool3[] type1 = {true, default, false, default, default};
bool3[] type2 = {true, false, default, false, default};
bool[] type3 = {true, false, true, false, true};
bool[] type4 = {false, false, true, true, false};
bool3[] type5 = {default, true, false, false, false};
// Add leaves to the ARG.
Arg arg = Arg(type1); // ARG must have at least one leaf.
arg.newleaf(type2);
arg.newleaf(type3, 2); // Multiple copies of the same leaf can be added at once.
arg.newleaf(type4);
arg.newleaf(type5);
// Sequence of events. See the reference in the README for details.
arg.recombine(4, new int[] {0, 3}, 1, true);
arg.coalesce(2, 3, 0);
arg.recombine(8, 2);
arg.coalesce(1, 9);
arg.coalesce(5, 7);
arg.coalesce(6, 10, 3, new int[] {90, 0});
arg.coalesce(11, 13, mutation_angles = new int[] {0, 270});
arg.coalesce(0, 14, mutation_angles = new int[] {0, 270});
arg.coalesce(12, 15, mutation_angles = new int[] {90, 0});
// Draw the ARG with custom colors.
arg.draw(
 wild_color = rgb("2a9d90"),
 derived_color = rgb("ff6b6b"),
 nonancestral_color = rgb("fc9120")
);

Acknowledgements

• Asymptote: The Vector Graphics Language.

Reference

Mutation

Methods

• static void draw(path p, int[] markers, pen color = red, bool label = true, real angle = 0)

  Draw a circle representing a mutation event on an edge.

  • p: mutation edge
  • markers: indices of mutating markers
  • color: pen to use to draw the circle representing the mutation
  • label: whether to label the mutation circle with the mutating markers
  • angle: position of the label around the mutation circle

Marker

Fields

• bool3 status

  Status of the marker (false -> wild, true -> derived, default -> non-ancestral).

• pen box_pen

  Pen used to draw the marker.

Methods

• void operator init(bool3 status, pair pos, pen box_pen = linewidth(3bp))

  • status: status of the marker
  • pos: position of the marker
  • box_pen: pen to use to draw the marker

• bool3 getstatus()

  Status of the marker.

• void setnonancestral()

  Set the status of the marker to non-ancestral (default).

• void shiftby(pair p)

  Add p to the position of the marker.

  • p: position shift

• void draw(pen wild_color = blue, pen derived_color = red, pen nonancestral_color = lightblue)

  Draw the marker.

  • wild_color: pen to use to draw the marker if it has the wild allele (true)
  • derived_color: pen to use to draw the marker if it has the derived allele (true)
  • nonancestral_color: pen to use to draw the marker if it is non_ancestral (default)

Sequence

Fields

• Marker[] markers

  Markers making up the sequence.

• Sequence[] children

  Children of the sequence.

• int[] mutations_left_branch

• int[] mutations_right_branch

  Mutating markers.

• real[] mutation_angles

  Position of the labels around the mutation circles. First angle is for left branch.

• pair rightpoint

  Right end of the sequence.

• pair positions

  Position of the sequence. Corresponds to the center of its leftmost marker.

• pen wild_color

• pen derived_color

• pen nonancestral_color

  Pens used to draw markers.

Methods

• void operator init(bool3[] status, pair pos, pen wild_color = blue, pen derived_color = red, pen nonancestral_color = lightblue, Sequence[] children = {}, int[] mutations_left_branch = {}, int[] mutations_right_branch = {}, real[] mutation_angles = {0, 0})

  • status: status of the markers in the sequence (false -> wild, true -> derived, default -> non-ancestral)
  • pos: position of the sequence
  • wild_color: pen used to draw markers with the derived allele (false)
  • derived_color: pen used to draw markers with the derived allele (true)
  • nonancestral_color: pen used to draw markers with the non-ancestral allele (default)
  • children: children of the sequence
  • mutations_left_branch: indices of markers for which the left child branch is a mutation edge
  • mutations_right_branch: indices of markers for which the right child branch is a mutation edge
  • mutation_angles: position of the labels around the mutation circles. First angle is for left branch

• void operator init(Sequence other)

  Copy constructor. Create a new sequence that is a deep copy of another.

  • other: sequence to copy

• int nbmarkers

  Number of markers in the sequence.

• bool3 getstatus(int marker)

  Status of a marker.

• void showguide(string s)

  Draw s over the sequence.

• bool3[] status()

  Status of the markers in the sequence.

• real width()

  Width of the sequence.

• pair center()

  Center of the sequence.

• static Sequence right_of(sequence other, bool3[] status, pen wild_color = blue, pen derived_color = red, pen nonancestral_color = lightblue, real distance = 5)

  Create a new sequence to the left of another.

  • other: sequence relative to which the new one is positioned
  • status: status of the markers of the new sequence
  • wild_color: pen used to draw markers with the derived allele (false)
  • derived_color: pen used to draw markers with the derived allele (true)
  • nonancestral_color: pen used to draw markers with the non-ancestral allele (default)
  • distance: distance between the right endpoint of other and the left endpoint of the new sequence

• void draw(bool draw_mutations = true, bool label_mutations = true, pen edges_color = grey, pen wild_color = blue, pen derived_color = red, pen nonancestral_color = lightblue)

• static void draw(Sequence[] sequences, bool draw_mutations = true, bool label_mutations = true, pen edges_color = grey, pen wild_color = blue, pen derived_color = red, pen nonancestral_color = lightblue)

  Draw a sequence or a vector of sequences.

  • sequences: vector of sequences
  • draw_mutations: draw mutations circles on mutation edges
  • label_mutations: label mutation circles
  • edges_color: pen used to draw edges
  • wild_color: pen used to draw markers with the derived allele (false)
  • derived_color: pen used to draw markers with the derived allele (true)
  • nonancestral_color: pen used to draw markers with the non-ancestral allele (default)

• Sequence coalesce(Sequence other, pair pshilf = (0, 0), real[] mutation_angles = {0, 0})

  Construct a new sequence that results from the coalescence of this sequence with another one.

  • other: sequence with which to coalesce
  • pshift: position shift
  • mutation_angles: position of the labels around the mutation circles. First angle is for left branch.

• Sequence mutate(int mutating_marker, pair pshift = (0, 0))

  Construct a new sequence by mutating a marker in this one.

  • mutating_marker: marker to mutate
  • pshift: position shift

• Sequence recombine(int[] breakpoints, pair pshift = (0, 0), bool flip = false)

• Sequence recombine(int breakpoint, pair pshift = (0, 0), bool flip = false)

  Construct a new sequence by generating a recombination event on this one. If more than one breakpoint is specified, generate multiple crossing overs.

  • breakpoint/breakpoints: positions of crossover events
  • pshift: position shift
  • flip: exchange left and right recombination sequences

Arg

Fields

• Sequence[] sequences

  Sequences contained in the ARG.

Methods

• void operator init(bool3[] leaf)

  Construct an ARG with a single leaf.

• void newleaf(bool3[] status, int n = 1, real distance = 5)

  Add identical leaves to the right of those already present.

  • status: status of the markers in the sequences (false -> wild, true -> derived, default -> non-ancestral)
  • n: number of leaves to add
  • distance: distance between the right endpoint of other and the left endpoint of the new sequence

• void coalesce(int seq_idx1, int seq_idx2, pair pshift = (0, 0), real[] mutation_angles = {0, 0})

• void coalesce(int seq_idx1, int seq_idx2, real yshift, real[] mutation_angles = {0, 0})

  Coalesce two sequences.

  • seq_idx1/seq_idx2: indices of the sequences to coalesce
  • pshift: position shift
  • yshift: position shift along the y-axis
  • mutation_angles: position of the labels around the mutation circles. First angle is for left branch.

• void mutate(int seq_idx, int mutating_marker, pair pshift = (0, 0))

  Mutate a sequence.

  • seq_idx: index of the sequence to mutate
  • mutating_marker: marker to mutate
  • pshift: position shift

• void recombine(int seq_idx, int[] breakpoints, explicit pair pshift = (0, 0), bool flip = false)

• void recombine(int seq_idx, int[] breakpoints, real yshift, bool flip = false)

• void recombine(int seq_idx, int breakpoint, explicit pair pshift = (0, 0), bool flip = false)

• void recombine(int seq_idx, int breakpoint, real yshift, bool flip = false)

  Recombine a sequence. If multiple breakpoints a provided, generate multiple crossing overs.

  • seq_idx: index of the sequence to recombine
  • breakpoint/breakpoints: positions of crossover events
  • pshift: position shift
  • yshift: position shift along the y-axis
  • flip: exchange left and right recombination sequences

• void draw(bool guides = false, bool draw_mutations = true, bool label_mutations = true, pen edges_color = grey, pen wild_color = blue, pen derived_color = red, pen nonancestral_color = lightblue)

  Draw an ARG.

  • guides: if true, label each sequence with its index
  • draw_mutations: draw mutations circles on mutation edges
  • label_mutations: label mutation circles
  • edges_color: pen used to draw edges
  • wild_color: pen used to draw markers with the derived allele (false)
  • derived_color: pen used to draw markers with the derived allele (true)
  • nonancestral_color: pen used to draw markers with the non-ancestral allele (default)