Introduction

The NAIR package contains a number of functions supplementary to buildRepSeqNetwork() that can be used to perform additional downstream tasks.

Simulate Data for Demonstration

We simulate some toy data for demonstration.

We simulate data consisting of two samples with 100 observations each, for a total of 200 observations (rows).

set.seed(42)
library(NAIR)
dir_out <- tempdir()

toy_data <- simulateToyData()
head(toy_data)
#>        CloneSeq CloneFrequency CloneCount SampleID
#> 1 TTGAGGAAATTCG    0.007873775       3095  Sample1
#> 2 GGAGATGAATCGG    0.007777102       3057  Sample1
#> 3 GTCGGGTAATTGG    0.009094910       3575  Sample1
#> 4 GCCGGGTAATTCG    0.010160859       3994  Sample1
#> 5 GAAAGAGAATTCG    0.009336593       3670  Sample1
#> 6 AGGTGGGAATTCG    0.010369470       4076  Sample1

nrow(toy_data)
#> [1] 200

Before we go through the various functions, the code below shows an example of how some of them might be used together.

library(magrittr) # For pipe operator (%>%)
toy_data %>%
  filterInputData("CloneSeq", drop_matches = "\\W") %>%
  buildNet("CloneSeq") %>%
  addNodeStats("all") %>%
  addClusterMembership("greedy", cluster_id_name = "cluster_greedy") %>%
  addClusterMembership("leiden", cluster_id_name = "cluster_leiden") %>%
  addClusterStats("cluster_leiden", "CloneSeq", "CloneCount") %>%
  addPlots(color_nodes_by = c("cluster_leiden", "cluster_greedy"), 
           color_scheme = "Viridis"
  ) %>%
  labelClusters("cluster_leiden", cluster_id_col = "cluster_leiden") %>%
  labelClusters("cluster_greedy", cluster_id_col = "cluster_greedy") %>%
  saveNetwork(output_dir = tempdir(), output_name = "my_network")

`addPlots()`

addPlots() can be used to generate plots of a network graph.

net <- buildRepSeqNetwork(toy_data, "CloneSeq")
net <- addPlots(net, color_nodes_by = "SampleID")

See this article for more details.

`addNodeStats()`

addNodeStats() can be used to compute node-level network properties for a network.

net <- addNodeStats(net, stats_to_include = "all")

See this article for more details.

`addClusterStats()`

addClusterStats() can be used to perform cluster analysis for a network. It performs clustering, records the cluster membership of the nodes, and computes cluster properties.

net <- addClusterStats(net, cluster_fun = "walktrap",
                       cluster_id_name = "cluster_walktrap")

See this article for more details.

`addClusterMembership()`

addClusterMembership() can be used to perform clustering and record the cluster membership of the nodes without computing cluster properties. It is useful for performing multiple instances of clustering with different algorithms.

net <- addClusterMembership(net, 
                            cluster_fun = "leiden",
                            cluster_id_name = "cluster_leiden"
)
net <- addClusterMembership(net, 
                            cluster_fun = "louvain",
                            cluster_id_name = "cluster_louvain"
)

Refer here for more details.

`addClusterLabels()`

addClusterLabels() can be used to label the clusters in a plot.

net <- addPlots(net,
                color_nodes_by = "cluster_louvain",
                color_scheme = "Viridis"
)
net <- labelClusters(net,
                     cluster_id_col = "cluster_louvain",
                     top_n_clusters = 7,
                     size = 7
)
net$plots$cluster_louvain
#> Warning: Removed 115 rows containing missing values or values outside the scale range
#> (`geom_text()`).

Refer here for more details.

`labelNodes()`

labelNodes() can be used to label the nodes in network plots.

set.seed(42)
small_sample <- simulateToyData(1, sample_size = 10, prefix_length = 1)
net <- buildNet(small_sample, "CloneSeq", plot_title = NULL)
net <- labelNodes(net, "CloneSeq", size = 4)
net$plots[[1]]

`saveNetwork()`

saveNetwork() can be used to save a list of network objects. Also prints any plots to a PDF containing one plot per page.

saveNetwork(net, output_dir = dir_out, output_type = "individual")

The parameters output_dir, output_type, output_name, pdf_width and pdf_height have the same behavior as they do in the buildRepSeqNetwork() function.

`saveNetworkPlots()`

saveNetworkPlots() can be used to save the plots for a network to a PDF containing one plot per page.

saveNetworkPlots(net$plots, outfile = file.path(dir_out, "plots.pdf"))

`loadDataFromFileList()`

loadDataFromFileList() can be used to load data from multiple files and combine them into a single data frame.

dat <- loadDataFromFileList(list.files(my_dir), input_type = "rds")

The primary parameter accepts a character vector containing file paths or a list containing file paths and connections. Each element corresponds to a single file. Each file is assumed to contain the data for a single sample, with observations indexed by row, and with the same columns across samples.

The supported values of input_type are "rds", "rda", "csv", "csv2", "tsv" and "table". Each value specifies a different function to load the files. The respective functions are readRDS(), load(), read.csv(), read.csv2(), read.delim(), and read.table().

Text formats

For text formats (values of input_type other than "rds" and "rda"), non-default argument values can be specified to the optional parameters of the reading function using the read.args argument. It accepts a named list of argument values.

loadDataFromFileList(list.files(my_dir),
                     input_type = "table",
                     read.args = list(
                       header = TRUE,
                       sep = " ",
                       dec = ",",
                       na.strings = "NA!",
                       row.names = 1,
                       col.names = c("RowID", 
                                     "CloneSeq", "CloneFrequency",
                                     "CloneCount", "VGene"
                       )
                     )
)

See ?utils::read.table() for the parameters and their accepted values. Note that read.csv(), read.csv2() and read.delim() are identical to read.table() other than their default argument values. Some examples of useful parameters include:

header: Whether the first row contains column names.
sep: The character separating consecutive values in each row.
dec: The character used as a decimal point.
quote: The character(s) used as quotes within character strings.
na.strings: The character string representing NA values.
row.names: The row names or the column containing the row names.
col.names: The column names, for files without a header row.
colClasses: For manually specifying the class of each column.
as.is: For specifying the character columns to be converted to factors.
nrows: Max number of rows (specification can improve memory usage)

RData format

For the "rda" input type, the data_symbols parameter accepts a character vector specifying the name of each sample’s data frame within its respective Rdata file (i.e., the name of the data frame in the R environment). A single character string can be used if each sample’s data frame has the same name.

save(df_sample1, file = file_1)
save(df_sample2, file = file_2)
save(df_sample3, file = file_3)
loadDataFromFileList(c(file_1, file_2, file_3),
                     input_type = "rda",
                     data_symbols = c("df_sample1",
                                      "df_sample2",
                                      "df_sample3"
                     )
)

`combineSamples()`

combineSamples() has the same default behavior as loadDataFromFileList(), but possesses additional parameters that give it extra functionality, such as the ability to filter data and assign sample/subject/group IDs to each data file, which are then included as variables in the combined data frame.

dat <- combineSamples(list.files(my_dir),
                      input_type = "rds",
                      min_seq_length = 7,
                      drop_matches = "[*|_]",
                      subset_cols = c("CloneSeq", "CloneCount", "VGene"),
                      sample_ids = 1:5,
                      subject_ids = c(1, 2, 2, 3, 3),
                      group_ids = c(1, 1, 1, 2, 2)
)

`filterInputData()`

filterInputData() can be used to filter data prior to performing network analysis.

filtered_data <- filterInputData(toy_data, 
                                 seq_col = "CloneSeq", 
                                 min_seq_length = 13,
                                 drop_matches = "GGGG", 
                                 subset_cols = c("CloneFrequency", "SampleID"),
                                 count_col = "CloneCount",
                                 verbose = TRUE
)
#> Warning: The `count_col` argument of `filterInputData()` is deprecated as of NAIR 1.0.1.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.
#> Input data contains 200 rows.
#> Removing sequences with length fewer than 13 characters... Done. 136 rows remaining.
#> Removing sequences containing matches to "GGGG"... Done. 105 rows remaining.

The function has parameters data, seq_col, min_seq_length, drop_matches and subset_cols, all of which behave in the same manner as seen in buildRepSeqNetwork(). In addition, the count_col parameter can be used to specify a column containing the clone count or UMI count. If specified, observations with NA values in this column will be removed from the data.

`aggregateIdenticalClones()`

aggregateIdenticalClones() can be used on bulk AIRR-seq data to aggregate data rows containing the same clone sequence, with the clone counts and clone frequencies being added together. Aggregation can be restricted to being performed only within groups that are defined based on specified grouping variables.

my_data <- data.frame(
  clone_seq = c("ATCG", rep("ACAC", 2), rep("GGGG", 4)),
  clone_count = rep(1, 7),
  clone_freq = rep(1/7, 7),
  time_point = c("t_0", rep(c("t_0", "t_1"), 3)),
  subject_id = c(rep(1, 5), rep(2, 2))
)

# group clones by time point and subject ID
data_agg_time_subject <-
  aggregateIdenticalClones(my_data,
                           clone_col = "clone_seq",
                           count_col = "clone_count",
                           freq_col = "clone_freq",
                           grouping_cols = c("subject_id", "time_point")
  )

`getNeighborhood()`

getNeighborhood() can be used to extract a subset of observations with receptor sequences sufficiently similar to a target sequence.

nbd <- getNeighborhood(toy_data,
                       seq_col = "CloneSeq",
                       target_seq = "GGGGGGGAATTGG"
)

`generateNetworkObjects()`

generateNetworkObjects() can be used to construct the minimal output possible from buildRepSeqNetwork(). It does not filter the input data, produce plots, compute network properties, perform cluster analysis or save data.

net <- generateNetworkObjects(toy_data, "CloneSeq")

The function has parameters data, seq_col, dist_type, dist_cutoff and drop_isolated_nodes, all of which have the same behavior and default values as seen in buildRepSeqNetwork().

`generateNetworkGraph()`

generateNetworkGraph() can be used to generate the network igraph from the adjacency matrix.

net$igraph <- generateNetworkGraph(net$adjacency_matrix)

`generateAdjacencyMatrix()`

generateAdjacencyMatrix() can be used to compute the network adjacency matrix from the list of receptor sequences.

output$adjacency_matrix <- generateAdjacencyMatrix(toy_data$CloneSeq)

# use same settings from original call to buildRepSeqNetwork()
net$adjacency_matrix <- generateAdjacencyMatrix(
  net$node_data$CloneSeq,
  dist_type = net$details$dist_type,
  dist_cutoff = net$details$dist_cutoff,
  drop_isolated_nodes = net$details$drop_isolated_nodes
)

The parameters dist_type, dist_cutoff and drop_isolated_nodes have the same behavior and default values as in buildRepSeqNetwork().

Supplementary Functions

Introduction

Simulate Data for Demonstration

addPlots()

addNodeStats()

addClusterStats()

addClusterMembership()

addClusterLabels()

labelNodes()

saveNetwork()

saveNetworkPlots()

loadDataFromFileList()

Text formats

RData format

combineSamples()

filterInputData()

aggregateIdenticalClones()

getNeighborhood()

generateNetworkObjects()

generateNetworkGraph()

generateAdjacencyMatrix()

`addPlots()`

`addNodeStats()`

`addClusterStats()`

`addClusterMembership()`

`addClusterLabels()`

`labelNodes()`

`saveNetwork()`

`saveNetworkPlots()`

`loadDataFromFileList()`

`combineSamples()`

`filterInputData()`

`aggregateIdenticalClones()`

`getNeighborhood()`

`generateNetworkObjects()`

`generateNetworkGraph()`

`generateAdjacencyMatrix()`