Sequence Length

The min_seq_length parameter specifies the minimum TCR/BCR sequence length (in number of characters). Sequences with lengths below this value are dropped prior to analysis. An argument value of NULL bypasses this filter. This filter applies to the sequence in the column specified by seq_col.

By default, min_seq_length is set to 3.

net <- buildNet(toy_data, "CloneSeq", min_seq_length = 10)

Sequence Content

The optional drop_matches parameter can be used to remove TCR/BCR sequences matching a specified pattern. It accepts a character string containing a regular expression specifying the pattern of content to search for. Each sequence in the column specified by seq_col is checked for a pattern match using grep(). If a match is found, the sequence is removed prior to analysis.

net <- buildNet(toy_data, "CloneSeq", drop_matches = "\\W")

Distance Function

The default method for quantifying the similarity between TCR/BCR sequences is the Hamming distance, which is computed using hamDistBounded(). It calculates the number of differences between two sequences of the same length. For each position in one sequence, the character in that position is checked to see whether it differs from the character in the same position of the other sequence. If the sequences have different lengths, the shorter sequence is extended by adding non-matching characters to make it the same length as the longer sequence.

The Levenshtein distance, which is computed using levDistBounded(), can be used as an alternative measurement to determine the similarity between sequences. It calculates the minimum number of single-character edits (insertions, deletions and transformations) needed to transform one sequence into the other. This method is particularly useful for comparing sequences of different lengths and can account for insertions and deletions. When constructing a network based on the similarity of CDR-3 nucleotide sequences, it is preferable to use the Levenshtein distance instead of the default Hamming distance by specifying dist_type = "lev". However, the Levenshtein distance requires significantly more computation than the Hamming distance, which may be challenging when working with large data sets having long TCR/BCR sequences.

net <- buildNet(toy_data, "CloneSeq", dist_type = "lev")

Distance Cutoff

The function specified by dist_type quantifies the similarity between TCR/BCR sequences as a nonnegative distance, with values closer to 0 indicating greater similarity.

Each node in the network graph corresponds to a row of the AIRR-Seq data. By default, two nodes are connected by an edge if the distance between their TCR/BCR sequences does not exceed 1. This cutoff value is specified by the dist_cutoff parameter, which controls the stringency of the network construction and affects the number and density of edges in the network. A lower cutoff requires greater sequence similarity to form an edge connection. If dist_cutoff = 0, two sequences must be identical in order for their nodes to be joined by an edge.

net <- buildNet(toy_data, "CloneSeq", dist_cutoff = 0)

Keep/Remove Isolated Nodes

By default, only nodes that are joined by an edge connection to at least one other node will be kept in the network.

If drop_isolated_nodes = FALSE, then all nodes are kept in the network, including those that do not have any edge connections to other nodes.

net <- buildNet(toy_data, "CloneSeq", drop_isolated_nodes = FALSE)

Network Metadata

details records argument values supplied in the call to buildRepSeqNetwork():

net$details
#> $seq_col
#> [1] "CloneSeq"
#> 
#> $dist_type
#> [1] "hamming"
#> 
#> $dist_cutoff
#> [1] 1
#> 
#> $drop_isolated_nodes
#> [1] TRUE
#> 
#> $nodes_in_network
#> [1] 122
#> 
#> $min_seq_length
#> [1] 3
#> 
#> $drop_matches
#> [1] "NULL"

nodes_in_network records the number of nodes in the network. Additional network information is included when cluster analysis is performed.

Node Metadata

node_data is a data frame containing metadata for the network nodes, where each row corresponds to a node in the network graph:

head(net$node_data)
#>         CloneSeq CloneFrequency CloneCount SampleID degree transitivity
#> 2  GGAGATGAATCGG    0.007777102       3057  Sample1      1          NaN
#> 5  GAAAGAGAATTCG    0.009336593       3670  Sample1      3    0.3333333
#> 8  GGGGAGAAATTGG    0.006220155       2445  Sample1      2    1.0000000
#> 11 GGGGGAGAATTGC    0.012969469       5098  Sample1      4    0.6666667
#> 12 GGGGGGGAATTGC    0.009079646       3569  Sample1     10    0.3555556
#> 13 AGGGGGAAATTGG    0.014941093       5873  Sample1      5    0.1000000
#>    eigen_centrality centrality_by_eigen betweenness centrality_by_betweenness
#> 2        0.00000000          0.00000000    0.000000                  0.000000
#> 5        0.00000000          0.00000000  108.000000                108.000000
#> 8        0.04558649          0.04558649    0.000000                  0.000000
#> 11       0.15055366          0.15055366    1.549451                  1.549451
#> 12       0.52691798          0.52691798   73.970918                 73.970918
#> 13       0.14682343          0.14682343   75.439560                 75.439560
#>    authority_score coreness   page_rank
#> 2       0.00000000        1 0.008196721
#> 5       0.00000000        2 0.010578507
#> 8       0.04558649        2 0.003936684
#> 11      0.15055366        4 0.005034736
#> 12      0.52691798        6 0.011491588
#> 13      0.14682343        3 0.008703523

Since buildNet() was called with drop_isolated_nodes = TRUE, some of the original rows are missing. The original row names are preserved, facilitating cross-referencing with the original data.

By default, all variables from the original input data are present. To include only a subset of the original variables, specify those to keep using the subset_cols parameter, which accepts a character vector of column names or a vector of column indices. The sequence column is always included.

Variables for node-level network properties will also be present if computed, as seen here.

Variables present in the node metadata can be used to encode node colors in visualizations.

Cluster Metadata

If buildRepSeqNetwork() is called with cluster_stats = TRUE, the returned list will contain a data frame cluster_data with cluster properties such as node count and mean sequence length, as seen here.

Visual Plots

plots is a list containing any plots created as well as a matrix graph_layout storing the node layout used in the plots. Each plot is named according to the variable used to color the nodes.

names(net$plots)
#> [1] "SampleID"     "transitivity" "coreness"     "graph_layout"

Each plot is a ggraph (a special kind of ggplot).

class(net$plots$uniform_color)
#> [1] "NULL"

Custom plots can be created when calling buildNet() or afterward using addPlots() as described here.

Network Graph and Adjacency Matrix

igraph is an object of class igraph and adjacency_matrix is a dgCMatrix. Both objects encode the nodes and edges of the network graph, each using a different format. These objects are used by other NAIR functions, and are typically not of direct importance to the user.

Output Directory

buildRepSeqNetwork() writes its output to files if a directory path is provided to the output_dir parameter. The specified output directory will be created if it does not already exist.

Output File Format

• By default, the list returned by buildRepSeqNetwork() is saved as a compressed RDS file.
• If the file will be transferred across machines, the RData format is preferred. It can be used by specifying output_type = "rda". The list will be named net in the R environment.
• To use the results outside of R, specify output_type = "individual". Each list element will be saved as a separate file using the following formats:
  • .csv for node_data and cluster_data (using write.csv(), with row.names = FALSE for cluster_data)
  • .mtx for adjacency_matrix
  • .txt for details, igraph and plots$graph_layout
  • .rda (RData) for plots
• Regardless of output_type, plots are printed to a pdf file containing one plot per page. The dimensions (in inches) for each page can be adjusted using the plot_width and plot_height parameters, with the defaults being 12 and 10, respectively.

Output File Name(s)

By default, the name of each saved file begins with MyRepSeqNetwork. This prefix can be changed using the output_name parameter, which accepts a character string.

When output_type is "rds" or "rda", only two files are saved (the data file and the pdf). For each file, output_name is followed by the appropriate file extension. For example, if output_name = "NetworkABC" and output_type = "rds", then the files will be named NetworkABC.rds and NetworkABC.pdf.

• If output_type = "individual", the prefix specified by output_name is followed by:
  • _Details.txt for details
  • _EdgeList.txt for igraph
  • _AdjacencyMatrix.mtx for adjacency_matrix
  • _NodeMetadata.csv for node_data
  • _ClusterMetadata.csv for cluster_data (if present)
  • _Plots.rda for the list plots
  • .pdf for the pdf of the plots
  • _GraphLayout.txt for plots$graph_layout

For example, if output_name = "NetworkABC" and output_type = "individual", then the node metadata is saved as NetworkABC_NodeMetadata.csv, the pdf is saved as NetworkABC.pdf, the list plots is saved as NetworkABC_Plots.rds, and so on.