diff --git a/R/foreign.R b/R/foreign.R index 0cf7c447f0..6c96a1a920 100644 --- a/R/foreign.R +++ b/R/foreign.R @@ -151,6 +151,9 @@ write.graph.fromraw <- function(buffer, file) { #' @keywords graphs #' @family foreign #' @export +#' @cdocs igraph_read_graph_dimacs_flow igraph_read_graph_dl igraph_read_graph_edgelist +#' @cdocs igraph_read_graph_gml igraph_read_graph_graphdb igraph_read_graph_graphml +#' @cdocs igraph_read_graph_lgl igraph_read_graph_ncol igraph_read_graph_pajek read_graph <- function(file, format = c( "edgelist", "pajek", "ncol", "lgl", "graphml", "dimacs", "graphdb", "gml", "dl" @@ -184,21 +187,34 @@ read_graph <- function(file, format = c( #' Writing the graph to a file in some format #' #' `write_graph()` is a general function for exporting graphs to foreign -#' file formats, however not many formats are implemented right now. +#' file formats. The recommended formats for data exchange are GraphML and GML. #' #' @param graph The graph to export. #' @param file A connection or a string giving the file name to write the graph #' to. #' @param format Character string giving the file format. Right now #' `pajek`, `graphml`, `dot`, `gml`, `edgelist`, -#' `lgl`, `ncol` and `dimacs` are implemented. As of igraph 0.4 +#' `lgl`, `ncol`, `leda` and `dimacs` are implemented. As of igraph 0.4 #' this argument is case insensitive. #' @param \dots Other, format specific arguments, see below. -#' @return A NULL, invisibly. +#' @return A `NULL``, invisibly. #' @section Edge list format: The `edgelist` format is a simple text file, -#' with one edge in a line, the two vertex ids separated by a space character. +#' with one edge per line, the two zero-based numerical vertex IDs separated +#' by a space character. Note that vertices are indexed starting with zero. #' The file is sorted by the first and the second column. This format has no #' additional arguments. +#' @section NCOL format: This format is a plain text edge list in which vertices +#' are referred to by name rather than numerical ID. Edge weights may be +#' optionally written. Additional parameters: +#' \describe{ +#' \item{names}{The name of a vertex attribute to take vertex names from or +#' `NULL` to use zero-based numerical IDs.} +#' \item{weights}{The name of an edge attribute to take edge weights from or +#' `NULL` to omit edge weights.} +#' } +#' @section Pajek format: The `pajek` format is provided for interoperability +#' with the Pajek software only. Since the format does not have a formal +#' specification, it is not recommended for general data exchange or archival. #' @author Gabor Csardi \email{csardi.gabor@@gmail.com} #' @seealso [read_graph()] #' @references Adai AT, Date SV, Wieland S, Marcotte EM. LGL: creating a map of @@ -207,6 +223,9 @@ read_graph <- function(file, format = c( #' @family foreign #' @export #' @keywords graphs +#' @cdocs igraph_write_graph_dimacs_flow igraph_write_graph_dot igraph_write_graph_edgelist +#' @cdocs igraph_write_graph_gml igraph_write_graph_graphml igraph_write_graph_leda +#' @cdocs igraph_write_graph_lgl igraph_write_graph_ncol igraph_write_graph_pajek #' @examples #' #' g <- make_ring(10) diff --git a/man/read_graph.Rd b/man/read_graph.Rd index 6cb6ec0b9a..6c553b3a7f 100644 --- a/man/read_graph.Rd +++ b/man/read_graph.Rd @@ -75,3 +75,5 @@ Gabor Csardi \email{csardi.gabor@gmail.com} } \concept{foreign} \keyword{graphs} +\section{Related documentation in the C library}{\href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_read_graph_dimacs_flow}{\code{igraph_read_graph_dimacs_flow()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_read_graph_dl}{\code{igraph_read_graph_dl()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_read_graph_edgelist}{\code{igraph_read_graph_edgelist()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_read_graph_gml}{\code{igraph_read_graph_gml()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_read_graph_graphdb}{\code{igraph_read_graph_graphdb()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_read_graph_graphml}{\code{igraph_read_graph_graphml()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_read_graph_lgl}{\code{igraph_read_graph_lgl()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_read_graph_ncol}{\code{igraph_read_graph_ncol()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_read_graph_pajek}{\code{igraph_read_graph_pajek()}}.} + diff --git a/man/write.graph.Rd b/man/write.graph.Rd index 75798fb66c..c7376de875 100644 --- a/man/write.graph.Rd +++ b/man/write.graph.Rd @@ -20,7 +20,7 @@ to.} \item{format}{Character string giving the file format. Right now \code{pajek}, \code{graphml}, \code{dot}, \code{gml}, \code{edgelist}, -\code{lgl}, \code{ncol} and \code{dimacs} are implemented. As of igraph 0.4 +\code{lgl}, \code{ncol}, \code{leda} and \code{dimacs} are implemented. As of igraph 0.4 this argument is case insensitive.} \item{...}{Other, format specific arguments, see below.} diff --git a/man/write_graph.Rd b/man/write_graph.Rd index 891d8b06c1..e3e2571bc8 100644 --- a/man/write_graph.Rd +++ b/man/write_graph.Rd @@ -20,25 +20,44 @@ to.} \item{format}{Character string giving the file format. Right now \code{pajek}, \code{graphml}, \code{dot}, \code{gml}, \code{edgelist}, -\code{lgl}, \code{ncol} and \code{dimacs} are implemented. As of igraph 0.4 +\code{lgl}, \code{ncol}, \code{leda} and \code{dimacs} are implemented. As of igraph 0.4 this argument is case insensitive.} \item{\dots}{Other, format specific arguments, see below.} } \value{ -A NULL, invisibly. +A `NULL``, invisibly. } \description{ \code{write_graph()} is a general function for exporting graphs to foreign -file formats, however not many formats are implemented right now. +file formats. The recommended formats for data exchange are GraphML and GML. } \section{Edge list format}{ The \code{edgelist} format is a simple text file, -with one edge in a line, the two vertex ids separated by a space character. +with one edge per line, the two zero-based numerical vertex IDs separated +by a space character. Note that vertices are indexed starting with zero. The file is sorted by the first and the second column. This format has no additional arguments. } +\section{NCOL format}{ + This format is a plain text edge list in which vertices +are referred to by name rather than numerical ID. Edge weights may be +optionally written. Additional parameters: +\describe{ +\item{names}{The name of a vertex attribute to take vertex names from or +\code{NULL} to use zero-based numerical IDs.} +\item{weights}{The name of an edge attribute to take edge weights from or +\code{NULL} to omit edge weights.} +} +} + +\section{Pajek format}{ + The \code{pajek} format is provided for interoperability +with the Pajek software only. Since the format does not have a formal +specification, it is not recommended for general data exchange or archival. +} + \examples{ g <- make_ring(10) @@ -66,3 +85,5 @@ Gabor Csardi \email{csardi.gabor@gmail.com} } \concept{foreign} \keyword{graphs} +\section{Related documentation in the C library}{\href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_write_graph_dimacs_flow}{\code{igraph_write_graph_dimacs_flow()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_write_graph_dot}{\code{igraph_write_graph_dot()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_write_graph_edgelist}{\code{igraph_write_graph_edgelist()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_write_graph_gml}{\code{igraph_write_graph_gml()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_write_graph_graphml}{\code{igraph_write_graph_graphml()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_write_graph_leda}{\code{igraph_write_graph_leda()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_write_graph_lgl}{\code{igraph_write_graph_lgl()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_write_graph_ncol}{\code{igraph_write_graph_ncol()}}, \href{https://igraph.org/c/html/latest/igraph-Foreign.html#igraph_write_graph_pajek}{\code{igraph_write_graph_pajek()}}.} +