tsg 0.1.8

Deep Learning Processing Library for Biological Data
Documentation

TSG - Transcript Segment Graph

TSG is a Rust library and command-line tool for creating, manipulating, and analyzing transcript segment graphs. It provides a comprehensive framework for modeling segmented transcript data, analyzing non-linear splicing events, and working with genomic structural variants.

Features

  • Parse and write TSG format files
  • Build and manipulate transcript segment graphs
  • Support for multiple graphs within a single file
  • Analyze paths and connectivity between transcript segments
  • Support for various element types: nodes, edges, groups, and chains
  • Export graphs to DOT format for visualization
  • Traverse the graph to identify valid transcript paths
  • Read identity tracking to ensure biological validity
  • Build graphs from chains and validate path traversals
  • Support for genomic coordinates with strand information
  • Support for read evidence with types
  • Inter-graph links for fusion events and other cross-graph relationships

Installation

Library

Add this to your Cargo.toml:

[dependencies]
tsg = "0.1.0"

Command-line Tool

Install the CLI tool:

cargo install tsg

Library Usage

Loading a TSG file

use tsg::graph::TSGraph;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load graph from a TSG file
    let graph = TSGraph::from_file("path/to/file.tsg")?;

    // Access graph elements
    println!("Number of graphs: {}", graph.get_graphs().len());
    println!("Number of nodes: {}", graph.get_nodes().len());
    println!("Number of edges: {}", graph.get_edges().len());

    // Export to DOT format for visualization
    let dot = graph.to_dot()?;
    std::fs::write("graph.dot", dot)?;

    // Save modified graph
    graph.write_to_file("output.tsg")?;

    Ok(())
}

Working with Multiple Graphs

use tsg::graph::{TSGraph, NodeData, EdgeData};
use bstr::BString;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut graph = TSGraph::new();

    // Define multiple graphs
    graph.add_graph("gene_a", Some("BRCA1 transcripts"))?;
    graph.add_graph("gene_b", Some("BRCA2 transcripts"))?;

    // Add nodes to different graphs
    let node1 = NodeData {
        id: "gene_a:n1".into(),
        reference_id: "chr17".into(),
        ..Default::default()
    };

    let node2 = NodeData {
        id: "gene_b:n1".into(),
        reference_id: "chr13".into(),
        ..Default::default()
    };

    graph.add_node(node1)?;
    graph.add_node(node2)?;

    // Add edges within each graph
    let edge1 = EdgeData {
        id: "gene_a:e1".into(),
        ..Default::default()
    };

    graph.add_edge("gene_a:n1".into(), "gene_a:n2".into(), edge1)?;

    // Add inter-graph link (e.g., for fusion transcript)
    graph.add_link("fusion1", "gene_a:n3", "gene_b:n1", "fusion", None)?;

    // Write to file
    graph.write_to_file("multi_graph.tsg")?;

    Ok(())
}

Building Graphs from Chains

use tsg::graph::{TSGraph, Group};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create chains for different graphs
    let chains = vec![
        Group::Chain {
            id: "gene_a:chain1".into(),
            elements: vec!["gene_a:n1".into(), "gene_a:e1".into(), "gene_a:n2".into()],
            attributes: HashMap::new(),
        },
        Group::Chain {
            id: "gene_b:chain1".into(),
            elements: vec!["gene_b:n1".into(), "gene_b:e1".into(), "gene_b:n2".into()],
            attributes: HashMap::new(),
        },
    ];

    // Build graphs from chains
    let graph = TSGraph::from_chains(chains)?;

    // Write to file
    graph.write_to_file("output.tsg")?;

    Ok(())
}

Finding Valid Paths Through Specific Graphs

use tsg::graph::TSGraph;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let graph = TSGraph::from_file("transcript.tsg")?;

    // Find all valid paths through a specific graph
    let paths = graph.traverse_graph("gene_a")?;

    for (i, path) in paths.iter().enumerate() {
        println!("Path {}: {}", i+1, path);
    }

    Ok(())
}

CLI Usage

The TSG command-line tool provides a convenient interface for common operations:

# Display help
tsg --help

# Parse and validate a TSG file
tsg validate path/to/file.tsg

# List all graphs in a TSG file
tsg list-graphs path/to/file.tsg

# Convert a specific graph to DOT format for visualization
tsg dot --graph=gene_a path/to/file.tsg > gene_a.dot

# Extract statistics from a TSG file
tsg stats path/to/file.tsg

# Find all paths through a specific graph
tsg paths --graph=gene_a path/to/file.tsg

# Find all inter-graph links
tsg links path/to/file.tsg

TSG File Format

The TSG format is a tab-delimited text format representing transcript assemblies as graphs. It supports multiple independent graphs within a single file.

Multi-Graph Support

TSG supports multiple graphs within a single file using a graph namespace approach. Each element in the file can be associated with a specific graph using a graph ID prefix:

graph_id:element_id

For example, gene_a:n1 refers to node n1 in the graph identified as "gene_a".

Record Types

Each line in a TSG file starts with a letter denoting the record type:

  • H - Header information (including graph definitions)
  • N - Node definition (exon or transcript segment)
  • E - Edge definition (splice junction or structural variant)
  • U - Unordered group (set of elements)
  • P - Path (ordered traversal through the graph)
  • C - Chain (alternating nodes and edges)
  • A - Attribute for any element (metadata)
  • L - Inter-graph link (connections between different graphs)

Conceptual Model

In the TSG model:

  1. Graphs (G) represent independent transcript graphs, each with its own set of nodes and edges.
  2. Chains (C) are used to build each graph's structure.
  3. Paths (P) are traversals through the constructed graphs.
  4. Links (L) establish relationships between elements in different graphs.

This distinction is important: chains define what each graph is, paths define ways to traverse each graph, and links define relationships between graphs.

Example with Multiple Graphs

# Global headers
H  TSG  1.0
H  reference  GRCh38

# First graph
G  gene_a  name:Z:BRCA1  locus:Z:chr17q21.31

# Nodes for gene_a
N  n1  chr17:+:41196312-41196402  read1:SO,read2:SO  ACGTACGT
N  n2  chr17:+:41199660-41199720  read2:IN,read3:IN  TGCATGCA
N  n3  chr17:+:41203080-41203134  read1:SI,read2:SI  CTGACTGA

# Edges for gene_a
E  e1  n1  n2  chr17,chr17,41196402,41199660,splice
E  e2  n2  n3  chr17,chr17,41199720,41203080,splice

# Chains for gene_a
C  chain1  n1  e1  n2  e2  n3

# Paths for gene_a
P  transcript1  n1+  e1+  n2+  e2+  n3+

# Sets for gene_a
U  exon_set  n1  n2  n3

# Attributes for gene_a elements
A  N  n1  expression:f:10.5
A  N  n1  ptc:i:10
A  P  transcript1  tpm:f:8.2

# Second graph
G  gene_b  name:Z:BRCA2  locus:Z:chr13q13.1

# Nodes for gene_b
N  n1  chr13:+:32315480-32315652  read4:SO,read5:SO  GATTACA
N  n2  chr13:+:32316528-32316800  read4:IN,read5:IN  TACGATCG
N  n3  chr13:+:32319077-32319325  read4:SI,read5:SI  CGTACGTA

# Edges for gene_b
E  e1  n1  n2  chr13,chr13,32315652,32316528,splice
E  e2  n2  n3  chr13,chr13,32316800,32319077,splice

# Chains for gene_b
C  chain1  n1  e1  n2  e2  n3

# Paths for gene_b
P  transcript1  n1+  e1+  n2+  e2+  n3+

# Sets for gene_b
U  exon_set  n1  n2  n3

# Attributes for gene_b elements
A  P  transcript1  tpm:f:3.7

# Inter-graph links (appears after all graph sections)
L  fusion1  gene_a:n3  gene_b:n1  fusion  type:Z:chromosomal

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Apache-2.0