Package {plasmidplot}

Create a plasmid object

Description

A plasmid object holds the plasmid name, its length in base pairs, and the list of features (markers) added with pp_marker(). Plot it with plot.plasmid().

Usage

plasmid(name, length)

Arguments

Value

An object of class plasmid.

Examples

p <- plasmid("pBR322", 4361)
p <- pp_marker(p, 86, 1276, label = "TcR")
plot(p)

Plot a plasmid map

Description

Renders the plasmid as a circular or linear map: a backbone with a base-pair scale, colored feature arcs (with optional arrowheads), callout labels with leader lines, restriction sites, and the plasmid name and size.

Usage

## S3 method for class 'plasmid'
plot(x, style = "angular", bg = NULL, newpage = TRUE, ...)

Arguments

Details

The layout follows the plasmid's topology unless the style says otherwise; see the layout shape parameter in pp_style().

Value

Invisibly, x.

Examples

p <- plasmid("pBR322", 4361) |>
  pp_marker(86, 1276, label = "TcR", arrow = "end") |>
  pp_marker(2535, 3122, label = "ori") |>
  pp_marker(3293, 4153, label = "AmpR", arrow = "start")
plot(p, style = "angular")
plot(p, style = "dark", bg = pp_canvas("dark"))
plot(p, style = pp_style("angular", layout = "linear"))

The background a style is designed for

Description

Styles do not paint a background; the device or surrounding viewport shows through. This returns the ground a style was designed against, so a dark preset can be given one explicitly.

Usage

pp_canvas(style)

Arguments

Value

A color string.

Examples

pp_canvas("dark")
p <- pp_demo_plasmid()
plot(p, style = "neon", bg = pp_canvas("neon"))

Check a palette for colorblind safety and contrast

Description

Runs the measurable checks a categorical palette has to pass, using the same transforms and thresholds the built-in palettes were validated with. Use it on any palette you bring from another package – ggsci, RColorBrewer, viridis, ggpubr – before relying on it.

Usage

pp_check_palette(
  colors,
  mode = c("light", "dark"),
  surface = NULL,
  pairs = c("adjacent", "all"),
  n = 8L
)

Arguments

Details

Five checks are computed. Two of them – CVD separation and the normal-vision floor – decide whether a reader can tell two features apart at all; failing either means the palette is unsafe as it stands. The other three govern how the palette looks and how it sits on the surface, and failing them means the colors are legible but sit outside the band the built-in palettes hold to. The printed summary says which kind failed, because most palettes from other packages miss the cosmetic bands while remaining perfectly readable.

• Lightness band – OKLCH L inside the band for the mode.

• Chroma floor – OKLCH C at or above 0.10, below which a hue reads gray.

• CVD separation – OKLab dE between slots under simulated protanopia and deuteranopia (tritanopia reported alongside). At or above 8 passes; 6 to 8 is a warning band that is sound only with a second channel – on a plasmid map every feature carries a text label, which supplies it. Below 6 fails.

• Normal-vision floor – worst pair at or above dE 15 under ordinary vision. This one is a hard gate: below it, full-color readers cannot tell the two apart either, and a text label does not excuse it.

• Contrast vs surface – WCAG ratio of at least 3:1. A warning here obliges visible labels, which the maps always draw.

Value

An object of class pp_palette_check: a data frame of one row per check with columns check, status ("PASS", "WARN" or "FAIL") and detail, carrying an ok attribute that is FALSE if anything failed.

Examples

pp_check_palette("default")
pp_check_palette("default_dark", mode = "dark")

# A palette brought from elsewhere:
pp_check_palette(c("#E64B35", "#4DBBD5", "#00A087", "#3C5488"))

# A palette function is called with n.
pp_check_palette(function(n) grDevices::hcl.colors(n, "Dark 3"), n = 6)
pp_check_palette(grDevices::palette.colors(8, "Okabe-Ito"))

Draw a demo plasmid map

Description

Plots pp_demo_plasmid() in the given style. Handy for previewing styles; see pp_style() for the list of presets.

Usage

pp_demo(style = "angular")

Arguments

Details

The demo paints the style's own pp_canvas() so the dark presets are legible on a white device; ordinary plotting leaves the background alone.

Value

Invisibly, the demo plasmid object.

Examples

pp_demo("angular")
pp_demo("neon")

Example plasmid used by the demos

Description

Builds a small pBR322 map (positions approximate) without plotting it.

Usage

pp_demo_plasmid()

Value

A plasmid object.

Examples

pp_demo_plasmid()

Common restriction enzymes

Description

The recognition sequences pp_find_sites() searches for.

Usage

pp_enzymes()

Value

A data frame with columns enzyme, site (recognition sequence, IUPAC codes allowed) and cut (0-based cut offset on the top strand within the recognition sequence).

Examples

head(pp_enzymes())
subset(pp_enzymes(), enzyme %in% c("EcoRI", "BamHI"))

Add many features at once from a data frame

Description

A vectorized pp_marker(): one row per feature. Only start and end are required; any other column named after a pp_marker() argument is used, and unknown columns are ignored.

Usage

pp_features(p, df)

Arguments

Value

The updated plasmid object.

Examples

feats <- data.frame(
  start = c(86, 2535, 3293),
  end   = c(1276, 3122, 4153),
  label = c("TcR", "ori", "AmpR"),
  arrow = c("end", "none", "start")
)
plot(pp_features(plasmid("pBR322", 4361), feats))

Find restriction sites in the plasmid sequence

Description

Searches the sequence kept by the readers and adds a pp_site() for each cut position. On a circular plasmid the search wraps the origin, so a site straddling position 1 is not missed.

Usage

pp_find_sites(
  p,
  enzymes = NULL,
  unique_only = TRUE,
  max_sites = 3L,
  show_position = TRUE
)

Arguments

Value

The updated plasmid object.

See Also

pp_site(), pp_enzymes()

Examples

p <- read_genbank(system.file("extdata", "pDemo.gb", package = "plasmidplot"))
p <- pp_find_sites(p, c("EcoRI", "BamHI", "HindIII", "NotI"))
p
plot(p)

# Every unique cutter the built-in table knows about:
plot(pp_find_sites(read_genbank(
  system.file("extdata", "pDemo.gb", package = "plasmidplot"))))

Add a feature marker to a plasmid

Description

Markers are drawn as colored arcs on the plasmid backbone. A marker whose end is smaller than its start is taken to wrap across the origin (position 1). Calls are pipe-friendly: each returns the updated object.

Usage

pp_marker(
  p,
  start,
  end,
  label = NULL,
  color = NULL,
  group = NULL,
  arrow = c("none", "end", "start", "both"),
  offset = 0,
  width = NULL
)

Arguments

Value

The updated plasmid object.

Examples

p <- plasmid("pUC19", 2686) |>
  pp_marker(146, 469, label = "lacZ-alpha", arrow = "end") |>
  pp_marker(1629, 2486, label = "AmpR", arrow = "start")
plot(p)

Built-in categorical palettes

Description

Named color sets that can be passed to pp_style() as palette = "<name>".

Usage

pp_palette(name)

Arguments

Details

A palette is only the colors. The geometry, chrome and typography of a map are a style – see pp_style() – and the two are chosen independently: any palette can be paired with any style. Names ending in ⁠_dark⁠ are stepped for a dark ground and will be washed out on a light one.

Every palette here was checked pair-by-pair under protanopia, deuteranopia and tritanopia simulation against the surface it is meant for, and against a normal-vision separation floor:

• "default" (light), "default_dark" (dark) and "jewel" (light) clear every gate, contrast included.

• "vivid" and "candy" (light) clear every separation gate.

• "muted" (light) clears the separation floors, with its closest colorblind pair in the band that is sound only because each feature also carries a text label – identity here never rests on hue alone.

• "neon_dark" clears contrast and both separation floors on a dark ground. It sits deliberately brighter than the others; that is the look.

Slot order carries the safety, so take the colors in the order given. Palettes of near-neighbor hues (all-brown, all-blue sets) were dropped during development because adjacent features became indistinguishable under red-green colorblindness.

Value

A character vector of hex colors, or of palette names.

Examples

pp_palette()
pp_palette("muted")
plot(pp_demo_plasmid(), style = pp_style("angular", palette = "vivid"))

Mark a single position on the plasmid

Description

Sites are drawn as a radial tick outside the feature ring with a label, the way restriction sites are shown on a classic plasmid map. Unlike pp_marker() they occupy one position rather than a span.

Usage

pp_site(p, position, label = NULL, color = NULL)

Arguments

Value

The updated plasmid object.

See Also

pp_find_sites() to add restriction sites from the sequence.

Examples

p <- plasmid("pUC19", 2686) |>
  pp_marker(146, 469, label = "lacZ", arrow = "end") |>
  pp_site(396, "EcoRI") |>
  pp_site(447, "BamHI")
plot(p)

Create or customize a plasmid map style

Description

A style is built from a handful of shape parameters plus secondary ink and type settings. Set the shape parameters directly; the presets are only named combinations of them, and everything a preset does can be written out by hand.

Usage

pp_style(preset, ...)

Arguments

Value

An object of class pp_style, or a character vector of preset names when called with no arguments.

Shape

These decide the construction of the map. They are the arguments worth reaching for first:

layout

"auto" draws a circular map for a circular plasmid and a linear one for a linear plasmid, following the object's topology. Force it with "circular" or "linear".

anchor

Where features sit relative to the backbone: "center" on it, "outside" clear of it (outward on a circle, above the line on a linear map), or "inside".

backbone

"ring" draws the backbone as a filled band, "line" as a single stroke, "none" omits it.

radius

Circular only: the backbone's radius, in npc units of a square viewport, so the usable maximum is 0.5.

track

Backbone thickness, used when backbone = "ring".

arc

Feature thickness.

gap

Clearance between backbone and features when anchor is "outside" or "inside".

Presets

Every preset is exactly the shape below, plus colors. dark is angular restepped for a dark ground, which is why their shapes match.

Their default palettes are default, except soft (muted), dark and blueprint (default_dark) and neon (neon_dark). A palette is an independent choice – see pp_palette().

Examples

pp_style()
p <- pp_demo_plasmid()

# Compose a style from the shape parameters, no preset involved.
plot(p, style = pp_style(anchor = "outside", backbone = "line",
                         radius = 0.26, arc = 0.05))

# Or start from a preset and change one thing.
plot(p, style = pp_style("angular", arc = 0.09))
plot(p, style = pp_style("minimal", layout = "linear"))

# A palette can be a vector of colors, or a function of n returning n
# colors -- the form ggsci, RColorBrewer and viridis palettes take.
plot(p, style = pp_style("angular", palette = grDevices::hcl.colors(8, "Set2")))
plot(p, style = pp_style("angular",
                         palette = function(n) grDevices::hcl.colors(n, "Dark 3")))

Read a plasmid from an EMBL file

Description

EMBL's feature table uses the same location grammar as GenBank, so complement(...), join(...) and partial boundaries behave identically; only the line prefixes differ.

Usage

read_embl(
  file,
  name = NULL,
  types = NULL,
  skip_types = "source",
  label_from = c("label", "gene", "product", "standard_name", "note", "locus_tag"),
  colors = c("style", "file"),
  color_by = c("feature", "type"),
  arrows = TRUE,
  sequence = TRUE
)

Arguments

Value

A plasmid object.

See Also

read_genbank(), read_plasmid()

Examples

embl <- system.file("extdata", "pDemo.embl", package = "plasmidplot")
p <- read_embl(embl)
p

Read a plasmid from a FASTA file or a bare sequence

Description

FASTA carries no feature table, so the result is a bare backbone: name, length and sequence, with no markers. Add features with pp_marker(), or restriction sites with pp_find_sites(), which needs exactly this.

Usage

read_fasta(file, name = NULL, circular = TRUE, ...)

Arguments

Value

A plasmid object.

Examples

fa <- tempfile(fileext = ".fa")
writeLines(c(">pMini test plasmid", strrep("ATGC", 500)), fa)
p <- read_fasta(fa)
p
unlink(fa)

Read a plasmid from a GenBank file

Description

Parses the LOCUS line for the name and length and the FEATURES block for markers. Handles complement(...), join(...), and the </> partial-boundary markers. A join() whose first segment starts after its last segment ends is kept as an origin-crossing feature.

Usage

read_genbank(
  file,
  name = NULL,
  types = NULL,
  skip_types = "source",
  label_from = c("label", "gene", "product", "standard_name", "note", "locus_tag"),
  colors = c("style", "file"),
  color_by = c("feature", "type"),
  arrows = TRUE,
  sequence = TRUE
)

Arguments

Value

A plasmid object.

See Also

read_snapgene(), read_plasmid(), pp_find_sites()

Examples

gb <- system.file("extdata", "pBR322.gb", package = "plasmidplot")
p <- read_genbank(gb)
p
plot(p)

Read a plasmid from any supported file

Description

Detects the format from the file's content rather than its extension, so a .dna file is read as SnapGene or as plain sequence depending on what it actually contains, and a GenBank record saved as .txt still works.

Usage

read_plasmid(file, ...)

Arguments

Details

Recognized formats: SnapGene (.dna binary), GenBank, EMBL, FASTA, and a bare sequence with no header at all.

Value

A plasmid object.

See Also

read_genbank(), read_snapgene(), read_embl(), read_fasta()

Examples

gb <- system.file("extdata", "pBR322.gb", package = "plasmidplot")
plot(read_plasmid(gb))

Read a plasmid from a SnapGene file

Description

Parses a SnapGene .dna file: sequence length and topology from the sequence segment, and features (name, type, range, strand, color) from the embedded feature table.

Usage

read_snapgene(
  file,
  name = NULL,
  types = NULL,
  skip_types = character(),
  label_from = c("label", "name", "gene", "product", "note"),
  colors = c("style", "file"),
  color_by = c("feature", "type"),
  arrows = TRUE,
  sequence = TRUE
)

Arguments

Details

SnapGene records carry no plasmid name, so the file's base name is used unless name is given.

Value

A plasmid object.

Note

Requires the xml2 package, which is only needed for this reader.

See Also

read_genbank(), read_plasmid()

Examples

if (requireNamespace("xml2", quietly = TRUE)) {
  dna <- system.file("extdata", "pDemo.dna", package = "plasmidplot")
  p <- read_snapgene(dna)
  print(p)
  plot(p, style = "snapgene")

  # Keep the colors the file itself stores, rather than the style's palette.
  plot(read_snapgene(dna, colors = "file"))
}