Skip to contents

Save List of Network Objects

saveNetwork.Rd

Given a list of network objects such as that returned by buildRepSeqNetwork() or generateNetworkObjects, saves its contents according to the specified file format scheme.

Usage

saveNetwork(
  net,
  output_dir,
  output_type = "rds",
  output_name = "MyRepSeqNetwork",
  pdf_width = 12,
  pdf_height = 10,
  verbose = FALSE,
  output_filename = deprecated()
)

Arguments

net

A list of network objects returned by buildRepSeqNetwork() or generateNetworkObjects().

output_dir

A file path specifying the directory in which to write the file(s).

output_type

A character string specifying the file format scheme to use when writing output to file. Valid options are "individual", "rds" and "rda". See detials.

output_name

A character string. All files saved will have file names beginning with this value.

pdf_width

If the list contains plots, this controls the width of each plot when writing to pdf. Passed to the width argument of the pdf function.

pdf_height

If the list contains plots, this controls the height of each plot when writing to pdf. Passed to the height argument of the pdf function.

verbose

Logical. If TRUE, generates messages about the tasks performed and their progress, as well as relevant properties of intermediate outputs. Messages are sent to stderr().

output_filename

[Deprecated] Equivalent to output_name.

Details

The list net must contain the named elements igraph (of class igraph), adjacency_matrix (a matrix or dgCMatrix encoding edge connections), and node_data (a data.frame containing node metadata), all corresponding to the same network. The list returned by buildRepSeqNetwork() and generateNetworkObjects() is an example of a valid input for the net argument.

The additional elements cluster_data (a data.frame) and plots (a list containing objects of class ggraph and possibly one matrix named graph_layout) will also be saved, if present.

By default, the list net is saved to a compressed data file in the RDS format, while any plots present are printed to a single pdf containing one plot per page.

The name of each saved file begins with the value of output_name. When output_type is one of "rds" or "rda", only two files are saved (the rds/rda and the pdf); for each file, output_name is followed by the appropriate file extension.

When output_type = "individual", each element of net is saved as a separate file, where output_name is followed by:

  • _NodeMetadata.csv for node_data

  • _ClusterMetadata.csv for cluster_data

  • _EdgeList.txt for igraph

  • _AdjacencyMatrix.mtx for adjacency_matrix

  • _Plots.rda for plots

  • _GraphLayout.txt for plots$graph_layout

  • _Details.rds for details

node_data and cluster_data are saved using write.csv(), with row.names being TRUE for node_data and FALSE for cluster_data. The igraph is saved using write_graph() with format = "edgelist". The adjacency matrix is saved using writeMM(). The graph layout is saved using write() with ncolumns = 2.

Value

Returns TRUE if output is saved, otherwise returns FALSE (with a warning if output_dir is non-null and the specified directory does not exist and could not be created).

References

Hai Yang, Jason Cham, Brian Neal, Zenghua Fan, Tao He and Li Zhang. (2023). NAIR: Network Analysis of Immune Repertoire. Frontiers in Immunology, vol. 14. doi: 10.3389/fimmu.2023.1181825

Webpage for the NAIR package

Author

Brian Neal (Brian.Neal@ucsf.edu)

Examples

set.seed(42)
toy_data <- simulateToyData()

net <- buildRepSeqNetwork(
  toy_data,
  seq_col = "CloneSeq",
  node_stats = TRUE,
  cluster_stats = TRUE,
  color_nodes_by = c("transitivity", "SampleID")
)

# save as single RDS file
saveNetwork(
  net,
  output_dir = tempdir(),
  verbose = TRUE
)
#> List of network objects saved to file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork.rds
#> Network graph plots printed to pdf file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork.pdf
#> [1] TRUE

saveNetwork(
  net,
  output_dir = tempdir(),
  output_type = "individual",
  verbose = TRUE
)
#> Network details saved to data file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork_Details.txt
#> Node metadata saved to file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork_NodeMetadata.csv
#> Cluster metadata saved to file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork_ClusterMetadata.csv
#> Network igraph saved in edgelist format to file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork_EdgeList.txt
#> Adjacency matrix saved to file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork_AdjacencyMatrix.mtx
#> List of network graph plots named 'plots' saved to data file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork_Plots.rda
#> List 'net' saved to file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork.rda
#> Network graph plots printed to pdf file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork.pdf
#> Graph layout for plots saved to file:
#>   /tmp/Rtmp3GaxiR/MyRepSeqNetwork_GraphLayout.txt
#> [1] TRUE

# \dontshow{
# clean up temp files
file.remove(
  file.path(
    tempdir(),
    c("MyRepSeqNetwork_NodeMetadata.csv",
      "MyRepSeqNetwork_ClusterMetadata.csv",
      "MyRepSeqNetwork_EdgeList.txt",
      "MyRepSeqNetwork_AdjacencyMatrix.mtx",
      "MyRepSeqNetwork_Details.txt",
      "MyRepSeqNetwork_Plots.rda",
      "MyRepSeqNetwork_GraphLayout.txt",
      "MyRepSeqNetwork.pdf",
      "MyRepSeqNetwork.rds"
    )
  )
)
#> [1] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
# }