Draw an A3 Amino Acid Sequence Visualization

Renders an A3 object (from rtemis.a3) as an interactive ECharts amino-acid sequence diagram. The sequence is wrapped into rows in a meander/serpentine path, with optional site, region, PTM, processing, and variant annotations overlaid as distinct series and collected in an upper-right annotation column, matching rtemislive. Legend headings use native rich text and remain available in vector SVG exports through save_drawing().

Usage

draw_a3(
  x,
  n_per_row = 21L,
  residue_spacing = 0.3,
  marker_size = 28,
  font_size = 18,
  line_width = 2,
  show_markers = TRUE,
  show_labels = TRUE,
  position_every = 10L,
  region_opacity = 0.3,
  ptm_placement = "radial",
  residue_fill = NULL,
  residue_stroke = NULL,
  label_color = NULL,
  pos_label_color = NULL,
  variant_color = NULL,
  disease_variant_color = NULL,
  enable_zoom = TRUE,
  title = NULL,
  grid = NULL,
  theme = NULL,
  width = NULL,
  height = NULL,
  element_id = NULL,
  filename = NULL
)

Arguments

x: A3 object from rtemis.a3::create_A3() or rtemis.a3::read_A3json().
n_per_row: Integer [2, Inf): Number of residues per wrapped row. Reduce this for larger residues on narrow surfaces.
residue_spacing: Numeric (0, Inf): Horizontal spacing multiplier. Values below 1 compress the layout; 1 gives natural hex spacing.
marker_size: Numeric (0, Inf): Preferred residue circle diameter in pixels; reduced with related marks when needed to fit the drawing surface.
font_size: Numeric (0, Inf): Base font size in pixels for residue and position labels.
line_width: Numeric (0, Inf): Backbone line width in pixels.
show_markers: Logical: Whether to render the backbone line and residue circles.
show_labels: Logical: Whether to render single-letter residue labels.
position_every: Optional Integer [1, Inf): Show a numeric position label every N residues. NULL disables position labels.
region_opacity: Numeric [0, 1]: Opacity of region band overlays.
ptm_placement: Character {"radial", "innerRadial", "outerRadial"}: Placement of PTM symbols relative to the residue circle. "radial" centers on the circle edge; "innerRadial" places inside; "outerRadial" places outside.
residue_fill: Optional Character: Residue circle fill color.
residue_stroke: Optional Character: Residue circle stroke and backbone line color.
label_color: Optional Character: Default residue label text color.
pos_label_color: Optional Character: Position label text color.
variant_color: Optional Character: Label color for variant residues.
disease_variant_color: Optional Character: Label color for disease-associated variant residues (takes precedence over variant_color). NULL color arguments follow the light/dark A3 theme.
enable_zoom: Logical: Whether to enable Shift+scroll zoom.
title: Optional Character: Chart title.
grid: Optional Grid: Override any plot-area margin. The defaults (margins matching rtemislive, with right driven by legend width) are merged with the properties of the supplied Grid object, so only the fields you set are changed — e.g. Grid(left = 8, top = 8). legend_top is re-derived from the final grid top automatically.
theme: Optional Theme: Theme override. NULL auto-detects light/dark mode; NA uses raw ECharts defaults.
width: Optional Numeric or Character: Widget width.
height: Optional Numeric or Character: Widget height. Auto-computed from layout bounds and marker_size when NULL.
element_id: Optional Character: Explicit DOM element ID for the widget container. NULL lets htmlwidgets generate one.
filename: Optional Character: If provided, save the widget to this file via save_drawing().

Value

htmlwidget: Widget object.

Details

The annotation column stays at the upper right on every surface. Residue markers, labels, and annotations shrink together to avoid overlap. Row wrapping remains fixed. Browser height follows the layout unless supplied; SVG and panel dimensions remain bounded. A custom grid retains its layout.

Corresponds to createA3EChartsOption() in src/lib/a3/visualization/echarts.ts.

Examples

if (requireNamespace("rtemis.a3", quietly = TRUE)) {
  a <- rtemis.a3::create_A3(
    "MAEPRQEFEVMEDHAGTYGLGDRK",
    site = list(
      Active_site = rtemis.a3::annotation_position(c(5L, 17L))
    ),
    region = list(
      Domain = rtemis.a3::annotation_range(
        matrix(c(3L, 10L, 15L, 22L), ncol = 2, byrow = TRUE)
      )
    )
  )
  draw_a3(a)
}