Revision 18262cc246d37d4b4131be097abad3f5ef98dae7 authored by Duncan Temple Lang on 07 March 2013, 00:00:00 UTC, committed by Gabor Csardi on 07 March 2013, 00:00:00 UTC
1 parent d4b41d2
xmlToDataFrame.Rd
\name{xmlToDataFrame}
\alias{xmlToDataFrame}
\alias{xmlToDataFrame,character,ANY,ANY,ANY,ANY-method}
\alias{xmlToDataFrame,XMLInternalDocument,ANY,ANY,ANY,missing-method}
\alias{xmlToDataFrame,ANY,ANY,ANY,ANY,XMLNodeSet-method}
\alias{xmlToDataFrame,ANY,ANY,ANY,ANY,XMLInternalNodeList-method}
\alias{xmlToDataFrame,ANY,ANY,ANY,ANY,list-method}
\alias{xmlToDataFrame,XMLInternalNodeList,ANY,ANY,ANY,ANY-method}
\alias{xmlToDataFrame,XMLNodeSet,ANY,ANY,ANY,ANY-method}
\alias{xmlToDataFrame,list,ANY,ANY,ANY,ANY-method}
\title{Extract data from a simple XML document}
\description{
This function can be used to extract data from
an XML document (or sub-document) that has a simple, shallow structure
that does appear reasonably commonly.
The idea is that there is a collection of nodes which have
the same fields (or a subset of common fields)
which contain primitive values, i.e. numbers, strings, etc.
Each node corresponds to an "observation" and each of its
sub-elements correspond to a variable.
This function then builds the corresponding data frame,
using the union of the variables in the different observation nodes.
This can handle the case where the nodes do not all have all of the variables.
}
\usage{
xmlToDataFrame(doc, colClasses = NULL, homogeneous = NA,
collectNames = TRUE, nodes = list(),
stringsAsFactors = default.stringsAsFactors())
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{doc}{the XML content. This can be the name of a file containing
the XML, the parsed XML document. If one wants to work on a subset
of nodes, specify these via the \code{nodes} parameter.}
\item{colClasses}{a list/vector giving the names of the R types for the
corresponding variables and this is used to coerce the resulting
column in the data frame to this type. These can be named. This is similar to
the \code{colClasses} parameter for \code{\link[utils]{read.table}}.
If this is given as a list, columns in the data frame
corresponding to elements that are \code{NULL} are omitted from the
answer.
This can be slightly complex to specify if the
different nodes have the "variables" in quite different order
as there is not a well defined order for the variables
corresponding to \code{colClasses}.
}
\item{homogeneous}{a logical value that indicates whether each of the
nodes contains all of the variables (\code{TRUE}) or if there
may be some nodes which have only a subset of them.
The function determines this if the caller does not specify
\code{homogeneous} or uses \code{NA} as the value.
It is a parameter to allow the caller to specify this information
and avoid these "extra" computations. If the caller knows this
information it is more efficient to specify it.
}
\item{collectNames}{a logical value indicating whether we compute the
names by explicitly computing the union of all variable names
or, if \code{FALSE}, we use the names from the node with the most
children.
This latter case is useful when the caller knows that the
there is at least one node with all the variables.
}
\item{nodes}{a list of XML nodes which are to be processed}
\item{stringsAsFactors}{a logical value that controls whether
character vectors are converted to factor objects in the resulting
data frame.}
}
\value{
A data frame.
}
\author{Duncan Temple Lang}
\seealso{
\code{\link{xmlParse}}
\code{\link{getNodeSet}}
}
\examples{
f = system.file("exampleData", "size.xml", package = "XML")
xmlToDataFrame(f, c("integer", "integer", "numeric"))
# Drop the middle variable.
z = xmlToDataFrame(f, colClasses = list("integer", NULL, "numeric"))
# This illustrates how we can get a subset of nodes and process
# those as the "data nodes", ignoring the others.
f = system.file("exampleData", "tides.xml", package = "XML")
doc = xmlParse(f)
xmlToDataFrame(nodes = xmlChildren(xmlRoot(doc)[["data"]]))
# or, alternatively
xmlToDataFrame(nodes = getNodeSet(doc, "//data/item"))
f = system.file("exampleData", "kiva_lender.xml", package = "XML")
doc = xmlParse(f)
dd = xmlToDataFrame(getNodeSet(doc, "//lender"))
}
\keyword{IO}
![swh spinner](/static/img/swh-spinner.gif)
Computing file changes ...