pyMSAviz: MSA Visualization Python Package

Below are common usage patterns for the pymsaviz CLI.

1. Simple visualization with a specific color scheme:

pymsaviz -i ./example/HIGD2A.fa -o cli_example01.png --color_scheme Identity

2. Wrapped visualization with consensus and character counts:

pymsaviz -i ./example/MRGPRG.fa -o cli_example02.png --wrap_length 80 \
         --color_scheme Taylor --show_consensus --show_count

3. Focused region with grid and custom consensus color:

pymsaviz -i ./example/MRGPRG.fa -o cli_example03.png --start 100 --end 160 \
         --color_scheme Flower --show_grid --show_consensus --consensus_color tomato

# Example 1
pymsaviz -i ./example/HIGD2A.fa -o cli_example01.png --color_scheme Identity

# Example 2
pymsaviz -i ./example/MRGPRG.fa -o cli_example02.png --wrap_length 80 \
         --color_scheme Taylor --show_consensus --show_count

# Example 3
pymsaviz -i ./example/MRGPRG.fa -o cli_example03.png --start 100 --end 160 \
         --color_scheme Flower --show_grid --show_consensus --consensus_color tomato

The MsaViz class is the primary interface for visualizing Multiple Sequence Alignments (MSAs). It provides methods for configuring plot parameters, applying color schemes, highlighting specific positions based on identity thresholds, and adding annotations or markers to the visualization.

Key capabilities include:

• Coloring: Use available_color_schemes to see supported schemes, set_plot_params for general styling, or set_custom_color_scheme and set_custom_color_func for fine-grained control.
• Highlighting: Use set_highlight_pos to highlight specific indices or set_highlight_pos_by_ident_thr to highlight positions that meet a specific consensus identity threshold.
• Annotations: Add visual elements using add_markers or add_text_annotation.
• Output: Generate plots using plotfig or save them directly to a file using savefig.

from pymsaviz.msaviz import MsaViz

# Initialize MsaViz (assuming an MSA object is provided during initialization)
viz = MsaViz(msa)

# Example workflow
viz.set_plot_params(color_scheme='default')
viz.set_highlight_pos_by_ident_thr(0.5)
viz.add_markers(positions=[10, 20])
viz.savefig('output.png')

The core API for customizing MSA visualizations is the MsaViz class. You can initialize it with an MSA file and various parameters to control the layout, color scheme, and displayed information.

Key parameters for MsaViz include:

• msa_file: Path to the MSA file.
• wrap_length: Number of characters before wrapping the sequence.
• color_scheme: One of the supported color schemes (e.g., 'Taylor', 'Zappo', 'Clustal').
• show_consensus: Boolean to show the consensus sequence.
• show_count: Boolean to show sequence character counts on the right side.
• show_grid: Boolean to show a grid.
• end: The end position of the MSA to visualize.

from pymsaviz import MsaViz, get_msa_testdata

msa_file = get_msa_testdata("HIGD2A.fa")
# Create a visualization object with wrapping and character counts
mv = MsaViz(msa_file, wrap_length=60, show_count=True)
# Save the result to a file
mv.savefig("api_example01.png")

You can enhance your MSA plots by adding markers at specific positions or ranges, and text annotations for specific regions.

Adding Markers

Use add_markers() to place markers. It accepts:

• A list of positions (integers) or ranges (tuples).
• color: The color of the marker.
• marker: The marker symbol (e.g., 'o', '+', 'x').

Adding Text Annotations

Use add_text_annotation() to label regions. It accepts:

• A tuple representing the range (start, end).
• text: The string to display.
• text_color: Color of the text.
• range_color: Color of the highlighted range.

from pymsaviz import MsaViz, get_msa_testdata

msa_file = get_msa_testdata("MRGPRG.fa")
mv = MsaViz(msa_file, end=180, wrap_length=60, show_consensus=True)

# Example: Adding markers at specific points and ranges
mv.add_markers([10, 20], color="orange", marker="o")
mv.add_markers([30, (40, 50), 55], color="green", marker="+")

# Example: Adding text annotations for a region
mv.add_text_annotation((76, 102), "Gap Region", text_color="red", range_color="red")

mv.savefig("api_example03.png")

The following options are available for the pymsaviz CLI tool:

Available Color Schemes: Clustal, Zappo, Taylor, Flower, Blossom, Sunset, Ocean, Hydrophobicity, HelixPropensity, StrandPropensity, TurnPropensity, BuriedIndex, Nucleotide, Purine/Pyrimidine, Identity, None

$ pymsaviz --help
usage: pymsaviz [options] -i msa.fa -o msa_viz.png

MSA(Multiple Sequence Alignment) visualization CLI tool

optional arguments:
  -i I, --infile I    Input MSA file
  -o O, --outfile O   Output MSA visualization file (*.png|*.jpg|*.svg|*.pdf)
  --format            MSA file format (Default: 'fasta')
  --color_scheme      Color scheme (Default: 'Zappo')
  --start             Start position of MSA visualization (Default: 1)
  --end               End position of MSA visualization (Default: 'MSA Length')
  --wrap_length       Wrap length (Default: None)
  --wrap_space_size   Space size between wrap MSA plot area (Default: 3.0)
  --label_type        Label type ('id'[default]|'description')
  --show_grid         Show grid (Default: OFF)
  --show_count        Show seq char count without gap on right side (Default: OFF)
  --show_consensus    Show consensus sequence (Default: OFF)
  --consensus_color   Consensus identity bar color (Default: '#1f77b4')
  --consensus_size   Consensus identity bar height size (Default: 2.0)
  --sort              Sort MSA order by NJ tree constructed from MSA distance matrix (Default: OFF)
  --dpi               Figure DPI (Default: 300)
  -v, --version       Print version information
  -h, --help          Show this help message and exit