Vizitig is:

• A command line interface (CLI) to administrate, build and annotate genomic or transcriptomic graphs and update them.
• A web interface to visualize and manipulate those graphs.
• A Python library for programmatic interaction with graphs.

Installation

Vizitig can be installed with:

pip install vizitig

To enable auto-complete for vizitig commands, you should then run

activate-global-python-argcomplete

This should work for major distributions. It is however mostly battle-tested on Linux.

Some systems (such as Debian) will prevent you from running this command as it could be incompatible with your system Python library. To avoid the issue, you should run the command within a virtual environment.

Installation of Vizitig upstream

To install the latest version of Vizitig (upstream), use the following instructions. It will clone the code and install all required dependencies for Vizitig to run. Make sure to have the Python venv package installed.

git clone https://gitlab.inria.fr/pydisk/examples/vizitig
cd vizitig
make install
source venv/bin/activate
activate-global-python-argcomplete

Note that upstream Vizitig might have some unstable features. To contribute to the Vizitig codebase you also need to install other tools (such as ruff, mypy, etc.). To install all those dependencies:

pip install .[all]

Vizitig custom binaries

Some parts of Vizitig are pre-compiled libraries written in Rust. This library will be automatically installed on your computer if you have cargo installed. This library is called Vizibridge. Vizitig should run without it, but it will be vastly slower on build and annotation tasks. Additional indexes are provided by this library.

pip install vizibridge

To check if Vizibridge is installed, you can run:

pip show vizibridge

If it is not installed, you can install Vizibridge for your system with the following script. Be aware that this will install the full Rust compilation toolchain.

The following script assumes pip and venv are already installed.

The following bash script installs vizibridge on your machine:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.bashrc # this is to refresh the path
cargo install maturin
python3 -m venv venv
source venv/bin/activate
git clone https://gitlab.inria.fr/cpaperma/vizibridge
cd vizibridge; maturin build --release
pip install target/wheels/vizibridge**.whl

The visual interface

With the venv activated, type:

vizitig run

and the web interface will appear. Note that on some distributions of Ubuntu, GNOME cannot access the browser, so you will need to open the browser yourself and go to: http://localhost:4242. This issue may appear on other distributions as well.

In the graphical user interface (GUI), you can select, rename, copy, download or delete existing graphs. Other transformations to the graphs can be made, for example coloring or annotating operations (see dedicated chapters). Users can also access saved visualizations: once the graph is loaded, visual operations can be applied to it (see dedicated chapter). The state of this visualization can be saved using the "Save" blue button.

Back on the first interface page, users can also add graphs (exports from another instance of Vizitig) or a BCALM file that will be ingested. Users can name their graphs. Drag and drop works for sending files into Vizitig.

Visualization states

By default, two visualization modes open: the band graph and the table. The table has an action set by default, which is "selection not hide". In other terms, the table will show you the selection made in other tabs.

The band graph is a graph visualization where bands represent nodes (the size of the band is proportional to the size of the sequence associated to a node) and connections between bands represent the edges. The former version of the band graph (the simple graph) does the opposite: nodes are represented by squares and edges are materialized between nodes.

The graph visualizations benefit from default functions. Start and Stop buttons will activate/deactivate the dynamicity of the visualization. The Center button will center the user's point of view on the barycenter of the graph. The Linearize button will help visually unfold the currently loaded nodes. Note that this implementation is likely quadratic and will start taking a lot of time above 2000 loaded nodes.

The CLI

Before running any CLI command, you should activate the virtual environment in which Vizitig runs. To do so, you can type the following while in the Vizitig folder:

source venv/bin/activate

The CLI is rather self-contained with documentation:

vizitig -h

Will provide the following:

usage: vizitig [-h] {info,rename,add,rm,index,color,annotate,build,run,algo,create} ...

A CLI interface to vizitig

positional arguments:
  {info,rename,add,rm,index,color,annotate,build,run,algo,create}
    info                Get information about available graphs
    rename              Rename a graph
    add                 Add an already built Vizitig Graph
    rm                  Remove an already built Vizitig Graph
    index               Index utilities of graph.
    color               Color an existing graph with sequence data from files, folders, or a CSV manifest.
    annotate            Add genomic annotations to an existing graph.
    build               Build a new graph from a single BCALM/GGCAT file.
    run                 Run Vizitig locally
    algo                Algorithms for Vizitig. Please note that you need to compute the algorithms in the back before using them in the front.
    create              Build a new Vizitig graph from a structured folder of sequence files.

options:
  -h, --help            show this help message and exit

Each subcommand has its own help.

Environment variables

It is possible to use environment variables to change the global behavior of Vizitig:

• VIZITIG_DEFAULT_INDEX: set the default index type chosen among SQLiteIndex or RustIndex (the default).
• VIZITIG_DIR: set the main data directory of Vizitig (default is ~/.vizitig).
• VIZITIG_NO_PARALLEL_INDEX: if set, do not build the index using Python multiprocessing (default False on Linux and True elsewhere).
• VIZITIG_NO_TMP_INDEX: if set, will not use a temporary index when performing some annotation operations.
• VIZITIG_PROC_NUMBER: the number of subprocesses used in index building.
• VIZITIG_PYTHON_ONLY: if set to any value, do not use Vizibridge (compiled binaries).
• VIZITIG_TMP_DIR: set the temporary data directory of Vizitig (default is the choice of the tempfile standard module on the system).
• VIZITIG_WORK_MEM: the maximal size of a shard (but could be used for other parts of the code).

To change the value of one of those variables, use the export command. Note that the variable will be changed for the current session, but will go back to its default value if you close the virtual environment.

export VIZITIG_PYTHON_ONLY=False

Building and ingesting graphs

To build a new graph from a BCALM or GGCAT file, run (within the venv):

vizitig build /path/to/some/bcalm/file

The kmer size k is estimated from the input file if not provided. We recommend using k = 21. The compiled version will work for any k < 64. Beyond this, only specific values of k are available: 113, 127, 239, 241, 251, 255, 487, 491, 499, 509, 511, 1021, 1023.

You can find those values in the AvailableKmerSize variable of vizitig.types.

Example vizitig build commands:

vizitig build my_bcalm.fa

or

vizitig build my_bcalm.fa -k 21 -n mini_bcalm  # mini_bcalm will be the name of the graph

It can take some time and disk space, but should not use too much memory.

To get information about already created graphs, simply run:

vizitig info

The vizitig query language

Note on Color and Expe keywords : In version 1.1, the metadata key to track sample id is documented and implement as 'Color', while this feature has been promoted as 'Expe' in the preprint paper for Vizitig. The change from 'Color' to 'Expe' will be effective in a future version of Vizitig.

While in the web user interface, a query field is available. Two execution modes are available for queries. After typing a query, you can:

• Execute the query on the graph by clicking the green "Fetch nodes" button. This will fetch all the corresponding nodes from the database to the user interface (from disk to RAM) and display them.
• Execute the query on the loaded nodes by clicking the blue "Add filter" button, naming your filter and adding it. In any visualization instance, you can then click "Add action" and select your filter. This action will only apply to loaded nodes. If you load new nodes, the actions will be applied to them as well.

In the CLI (command-line interface), only the first mode is available. Instead of displaying nodes, the CLI will return a list of node IDs.

The query language is simple. It contains three operators: AND, OR, and NOT. These are logical operators that correspond to conjunction, disjunction, and complement. Their meaning may differ from everyday usage, so we suggest looking at this page if you are not familiar with mathematical logic. The Venn diagram in the "Diagrammatic representations" section sums things up nicely.

Operators can be used between or in front of formulas. Formulas are composed of the name of the metadata (see the annotations section for more details) followed by its value in parentheses.

Query for all nodes tagged with the gene DRA_012:

Gene(DRA_012)

Query for all nodes not tagged with this metadata:

NOT Gene(DRA_012)

Query for nodes in sample 1 or in sample 2:

Expe(sample1) OR Expe(sample2)

Query for nodes in both sample 1 and sample 2 (nodes shared by the 2 samples):

Expe(sample1) AND Expe(sample2)

Parentheses can be used to group expressions. Query blocks in parentheses work just like a classic metadata query. For instance, to get all nodes that are in sample 1 or sample 2, but not in sample 3:

(Expe(sample1) OR Expe(sample2)) AND NOT Expe(sample3)

Additional query operators are available:

• NodeId(1234): return the node with a specific ID. Supports enumeration: NodeId(12, 22, 234).
• Kmer(ACGTCGT): return the node containing that exact k-mer (requires an index to be fast).
• Seq(ACGT): return all nodes containing the given subsequence.
• Degree(2): return all nodes with exactly 2 neighbors (client-side only).
• All: return all nodes in the graph (by default, limited to 1000 nodes).

Knowing what to type to find a specific metadata may be complicated if you have unusual data, so we built a metadata explorer that you can open in the visualization by clicking the blue metadata button. First, choose the type of metadata you want to see, then click on the corresponding line. It will add the right query for it in the query field. All that remains is adding logical operators and parentheses to build a functional query.

More details can be found in doc/query.md.

Graph annotations

To color a graph (that is, to mark some nodes with metadata) you can use the color subcommand. This command is designed to let users keep track of the origin sample of their data. It differs from the other annotation features explained below because it only requires a reference sequence and no annotation data.

We advise you to use a graph file as input for this command, even though a classic FASTA or .fna file will generally work as well.

If you want to add abundances to the graph, use the --abundances flag of the color command. In this case, provide a BCALM file. It must use the default BCALM parameters with regard to abundance (no special formatting and no --all-abundance-counts).

The recommended workflow is the following:

• Build a graph with all your sequences. You can easily build the DBG graph of several sequences using ggcat or BCALM.
• Use vizitig build to ingest the graph into Vizitig.
• Use vizitig color with your initial sequences (or their graph) to keep track of the origin sample of each sequence.
• Use vizitig annotate to add annotations using GTF or GFF files and reference sequences. You can also provide transcript or exon sequences alone or with annotations.

vizitig color -h

usage: vizitig color [-h] [-f file] [--folder folder] [--csv_file csv_file] [-m name] [-d description] [-c color] [-b N] [-abundances] graph

positional arguments:
  graph                 Name of the target graph. List available graphs with: vizitig info

options:
  -h, --help            show this help message and exit
  -f file, --file file  Path to a sequence file (FASTA or BCALM format) to use for coloring.
  --folder folder       Path to a folder. Every parsable file will be used to color the graph.
                        Each file's name is used as the color name unless -m is provided.
                        For per-file color and description control, use --csv instead.
  --csv_file csv_file   Path to a tab-separated CSV manifest for coloring.
                        Expected columns: file_path, color, description.
                        Also supports abundance ingestion across multiple files.
  -m name, --metadata_name name
                        Color name to assign to the ingested data. Required when using -f; optional with --folder.
  -d description, --metadata-description description
                        Human-readable description of this color/metadata entry.
  -c color, --color color
                        Display color to use in the visualization (e.g. 'red', '#ff0000'). Defaults to None.
  -b N, --buffer-size N
                        Memory buffer size (number of records). (default: 1000000)
  -abundances           Ingest per-kmer abundances from a BCALM file (expects 'km:f:value' fields).
                        Incompatible with --folder; use --csv for multi-file abundance ingestion.

The typical usage would be:

vizitig color -f my/awesome/file.fa -d "This contains some cure against cancer somehow" -m "sample1" my_graph_name

After this, you will be able to fetch all the nodes of the graph that correspond to this sample using the following query:

Expe(sample1)

More complex options exist to add metadata to a graph. One is suited for transcriptomic references, the other for genomic references.

Transcript and exon references

To add metadata with transcriptomic or exonic references, use vizitig annotate.

vizitig annotate -h

usage: vizitig annotate [-h] [-g genome_ref] [-m gtf] [-e exons] [-t transcripts] [-p probes] [-pt type] [-so value] graph

positional arguments:
  graph                 Name of the target graph. List available graphs with: vizitig info

options:
  -h, --help            show this help message and exit
  -g genome_ref, --genome genome_ref
                        Path to a (possibly compressed) FASTA file containing a reference genome.
  -m gtf, --metadata gtf
                        Path to a (possibly compressed) GTF/GFF annotation file.
                        Required with --genome; optional with --exons or --transcripts.
  -e exons, --exons exons
                        Path to a FASTA file containing exon reference sequences.
  -t transcripts, --transcripts transcripts
                        Path to a FASTA file containing transcript reference sequences.
  -p probes, --probes probes
                        Path to a probe file. Use with --probes_type.
  -pt type, --probes_type type
                        Type of the probe input. Must be used alongside --probes.
  -so value, --select_only value
                        Restrict annotation to a specific feature type. Can be repeated: -so gene -so transcript.

The typical usage for transcript annotation would be:

vizitig annotate -t my_data/transcript_ref.fa -m my_data/transcript_annot.gtf my_graph

Vizitig will proceed as follows:

• If a metadata file and reference sequences are provided: for each metadata line found in transcript_annot.gtf, Vizitig will look for the matching transcript or gene in transcript_ref.fa. If found, it will tag all nodes corresponding to the reference sequence with that metadata.
• If transcript or exon references are provided alone, every sequence will be added. Note that for exons, they will be named Exon1, Exon2, ... ExonN. Transcripts will be named after their ID in the reference sequence.

Note: The parsers are made for NCBI data. Contact the developers if you need a specific parser.

If your GTF file contains a transcript with ID NM_010111, you can query the corresponding nodes with:

Transcript(NM_010111)

Otherwise you can always use the metadata explorer in the web interface to see how your metadata were formatted.

Genomic references

To add metadata with genomic references, use vizitig annotate with the --genome flag:

vizitig annotate -g my_data/genome_ref.fa -m my_data/annot.gtf my_graph

Vizitig will proceed as follows: for each metadata line found in annot.gtf, it will look for the corresponding sequence in the reference file. When found, it will tag all nodes that correspond to the reference sequence with that metadata. Note that it reads the reference sequence sequentially and will need to load the reading frame into RAM (max 2.5 MB). If you happen to work with genomic references larger than 3 million bases per gene (e.g., in plants), contact the developers.

If your GTF file contains an exon with ID DRA_0172, you can query the corresponding nodes with:

Exon(DRA_0172)

The create command

The create command provides a streamlined pipeline to build a Vizitig graph directly from a structured folder of sequence files. It handles building per-sample graphs, merging them into a global graph, coloring each sample, and indexing — all in one step.

The input folder must follow this structure:

RNA_seq_folder
├── co_assemble
│   └── reference_file.fa
├── sample1
│   ├── reads1.fa
│   └── reads2.fa
└── sample2
    ├── reads1.fa
    └── reads2.fa

Each subfolder (except co_assemble) becomes a named color in the final graph. The co_assemble subfolder is reserved for reference data whose k-mers are not subject to the occurrence threshold.

vizitig create -h

usage: vizitig create [-h] [-k k] [-f depth] [-n name] [-c]
                      [--edge-annotation] [-u]
                      folder

positional arguments:
  folder               Path to the input folder structured as described above.

options:
  -h, --help           show this help message and exit
  -k k, --kmer-size k  Kmer size used to build the graphs. (default: 31)
  -f depth, --filter depth
                       Minimum occurrence count for a kmer to be retained in the graph.
                       Not applied to kmers from the co_assemble folder. (default: 1)
  -n name, --name name
                       Name of the resulting graph. Defaults to the input folder name if left empty.
  -c, --cleanup        Remove intermediate graph files after the build completes. (default: True)
  --edge-annotation    Annotate edges with strand orientation signs (--, -+, +-, ++).
  -u, --undirected-edges
                       Store the de Bruijn graph as an undirected graph (graph is directed by default).

The typical usage would be:

vizitig create RNA_seq_folder -k 31 -f 2 -n my_graph

Running a small example

Vizitig comes with a set of data that can be used to explore the tool. By default, the mini_bcalm.fa file is available. It is a minimal subset of a human gene.

To use this example, go into your Vizitig folder using a command line tool, activate the venv and run Vizitig.

Assuming your Vizitig folder is in your home folder and you opened a terminal there (otherwise adapt the path), run:

cd vizitig

to go into your Vizitig folder.

Then:

source venv/bin/activate

will activate the venv (virtual environment) to allow Vizitig and all its dependencies to run.

Then:

make small_ex

will build the graph, color it with origin sequences, and add the gene annotations. This command calls the small_ex target of the Makefile, which executes the build, color and annotation steps.

To use Vizitig, you can finally run:

vizitig run

A web application will open and you can select the mini_bcalm graph. You can select the genes or transcripts you want to display for a targeted visualization.

In any case, as soon as a graph node is displayed, you can unfold every neighbor node from the currently displayed nodes.

Removing graphs

You can delete a graph from the web interface, or via the command line.

With the venv activated and in the Vizitig folder, remove a graph with:

vizitig rm graph_name

For instance, deleting the mini_bcalm graph would require:

make rm mini_bcalm

Running a coloring example using FASTA data — COVID example

This section provides a complete end-to-end example that users can reproduce themselves. We provide the data.

To run this example, you will need to download the following files: click here.

Please note that we do not claim ownership of the data, nor the relevance of the data naming. This dataset was created for the purpose of showing a small existing example only.

You can also conduct the same process with your own files.

We will build a new graph from four FASTA files. In our case, they are named:

• SARS_CoV_alpha.fna
• SARS_CoV_beta.fna
• SARS_CoV_Spike_alpha.fna
• SARS_CoV_Spike_beta.fna

This dataset is composed of alpha and beta COVID genomes, as well as their associated spike proteins.

Open a terminal in the Vizitig folder.

1. Build a graph with our files.
   The first step is to build a BCALM/GGCAT graph. We advise using ggcat. The following command takes the FASTA files as input.

ggcat build data/covid/SARS_CoV_* -e -s 1 --kmer-length 21 -o data/covid_example

The SARS_CoV_* wildcard matches all files starting with SARS_CoV_ — in our case, all four files.

The -e and -s parameters are important, as they allow ggcat to build the edges of our graph.

2. Launch the Vizitig environment.
   Make sure to be in the parent folder of the Vizitig and data folders with your command line tool.

source vizitig/venv/bin/activate
cd vizitig

3. Ingest the graph into Vizitig.

vizitig build ../data/covid_example -n covid_example

4. Build the index for the graph.

vizitig index build covid_example

5. Color the graph with the genomes.

We color the graph with the initial sequences. The graph will be tagged with 4 colors, allowing us to see the origin sequence of each node.

vizitig color -f ../data/covid/SARS_CoV_alpha.fna -m "Covid_Alpha" covid_example
vizitig color -f ../data/covid/SARS_CoV_beta.fna -m "Covid_Beta" covid_example
vizitig color -f ../data/covid/SARS_CoV_Spike_alpha.fna -m "Spike_Protein_Alpha" covid_example
vizitig color -f ../data/covid/SARS_CoV_Spike_beta.fna -m "Spike_Protein_Beta" covid_example

6. Launch Vizitig.

vizitig run

7. Use Vizitig.

You can now select the covid_example graph in the top-left panel. You can search for a specific sub-sequence or k-mer and unfold the graph. Several visualization types are opened by default. You can reopen them using the visualization menu.

Visual operations on graphs

Once data is loaded in the visualization part of Vizitig, users can apply visual transformations to this data. This is done using filters and actions.

Filters

Filters allow users to save a query in the front-end and then apply a visual transformation. The green "Add as filter" button adds the currently written query as a filter. A dialog opens where users can set a name for their filter.

The blue "Filter" button opens a filter manager that exposes the currently existing filters and their associated queries, and allows deleting existing filters.

Filters are saved in the graph. When exchanging a graph between users, the filters are preserved.

Several filters are available by default:

• All: selects all nodes.
• Partial: selects the neighbors of loaded nodes.
• Tips: selects the nodes that have only one neighbor.
• Self loop: selects the nodes that have an edge with themselves.
• Selection: all the selected nodes at a given time.
• Dynamic selection: all the currently selected nodes.

Note that the dynamic selection filter is dynamic and will update on new selections.

When using classic selection, you can type Selection in the query field to export the current selection as a list of nodes. Users can then create a filter that saves this list of nodes.

Actions

Actions are used to apply visual transformations to the data. An action is always associated with a filter. If users do not want to filter nodes and want to apply a transformation to the whole graph, they can use the All filter.

Available actions depend on the type of visualization the user is currently working with.

Actions are self-explanatory, except for a few:

• Sashimi (for simple graph) or Sashimi Line (for band graph): allows displaying the abundance associated with a given color. Users must input a color in the "Abundance from" field. The color must exist in the graph and have abundance data associated with it. Note that the color in the graph is not the same as the color selected for the visual transformation.
• Center: recenters the user view on the barycenter, but applies no other transformation.

Vizitig as a library and Python command-line interface

Most graph operations are directly accessible from Python. It is a thin wrapper around NetworkDisk, which is a NetworkX-on-disk implementation storing graphs in a normalized way in a database.

from vizitig import info as vizinfo

L = vizinfo.graphs_list()  # get the list of available graphs
d = vizinfo.graph_info(L[0])  # return a dict with information about the graph
G = vizinfo.get_graph(L[0])  # get the networkdisk graph

You can also access a graph directly by its name. Use vizitig info to list all available graph names:

vizitig info

If you know the name of your graph, you can access it with:

from vizitig import *

G = get_graph("name_of_your_graph")  # name of the graph without extension

For the mini bcalm graph provided with Vizitig, that would be:

from vizitig import *

G = get_graph("mini_bcalm")  # the extension is .db

Metadata are stored within the graph data and are also accessible:

GM = G.metadata  # the description and list of all metadata
GM.color_list  # list of all the sequences your colored your graph with

To save space in the graph, nodes labeled by metadata contain the key i. For instance:

G.find_all_nodes(0)  # return all the nodes tagged with G.graph["meta_list"][0]

You can also search for a precise k-mer as follows:

G.find_one_node("GCTGCT...ACGT")

Or you can fetch all nodes that contain a subsequence as follows:

G.find_all_node(seq=lambda e:e.like("%TGCAGCAC%"))

The last one will perform a sequential scan over the database as it is not indexed, so it will be rather slow. All other queries are performed with an appropriate index accelerating them. This means that searching by k-mer is much faster than searching by a subsequence.

Compatibility with NetworkX

NetworkDisk, the package on which Vizitig relies, is compatible with the standard Python graph library NetworkX. Therefore, any Vizitig graph can use the algorithms provided by NetworkX. There are many algorithms available in NetworkX. Here is a quick example:

from networkx import diameter
from vizitig.info import get_graph

G = get_graph("mini_bcalm")
diameter(G)
>>> 34

Note that NetworkX functions take the graph as an argument, and are not methods called on the graph object.

Compiled binaries included

Some parts of Vizitig are compiled and packaged through the vizibridge module. This module can be toggled off and reverted to a pure Python implementation by setting the environment variable VIZITIG_PYTHON_ONLY to any non-empty value. Part of the optimizations provided by Vizibridge include sequence computations (for instance, the enumeration of the k-mers of a sequence). The performance improvement is considerable on medium to large graphs, but is currently limited to Linux on x86_64 machines.