1% File src/library/utils/man/edit.data.frame.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2015 R Core Team
4% Distributed under GPL 2 or later
5
6\name{edit.data.frame}
7\alias{edit.data.frame}
8\alias{edit.matrix}
9\title{Edit Data Frames and Matrices}
10\description{
11  Use data editor on data frame or matrix contents.
12}
13\usage{
14\method{edit}{data.frame}(name, factor.mode = c("character", "numeric"),
15     edit.row.names = any(row.names(name) != 1:nrow(name)), \dots)
16
17\method{edit}{matrix}(name, edit.row.names = !is.null(dn[[1]]), \dots)
18}
19\arguments{
20  \item{name}{A data frame or (numeric, logical or character) matrix.}
21  \item{factor.mode}{How to handle factors (as integers or using
22    character levels) in a data frame.  Can be abbreviated.}
23  \item{edit.row.names}{logical. Show the row names (if they exist) be
24    displayed as a separate editable column?  It is an error to ask for
25    this on a matrix with \code{NULL} row names.}
26  \item{\dots}{further arguments passed to or from other methods.}
27}
28\details{
29  At present, this only works on simple data frames containing numeric,
30  logical or character vectors and factors, and numeric, logical or
31  character matrices.  Any other mode of matrix will give an error, and
32  a warning is given when the matrix has a class (which will be discarded).
33
34  Data frame columns are coerced on input to \emph{character} unless
35  numeric (in the sense of \code{is.numeric}), logical or factor.  A
36  warning is given when classes are discarded.  Special characters
37  (tabs, non-printing ASCII, etc.) will be displayed as escape sequences.
38
39  Factors columns are represented in the spreadsheet as either numeric
40  vectors (which are more suitable for data entry) or character vectors
41  (better for browsing). After editing, vectors are padded with
42  \code{NA} to have the same length and factor attributes are restored.
43  The set of factor levels can not be changed by editing in numeric
44  mode; invalid levels are changed to \code{NA} and a warning is issued.
45  If new factor levels are introduced in character mode, they are added
46  at the end of the list of levels in the order in which they
47  encountered.
48
49  It is possible to use the data-editor's facilities to select the mode
50  of columns to swap between numerical and factor columns in a data
51  frame.  Changing any column in a numerical matrix to character will
52  cause the result to be coerced to a character matrix.  Changing
53  the mode of logical columns is not supported.
54
55  For a data frame, the row names will be taken from the original object
56  if \code{edit.row.names = FALSE} and the number of rows is unchanged,
57  and from the edited output if \code{edit.row.names = TRUE} and there
58  are no duplicates.  (If the \code{row.names} column is incomplete, it
59  is extended by entries like \code{row223}.)  In all other cases the
60  row names are replaced by \code{seq(length = nrows)}.
61
62  For a matrix, colnames will be added (of the form \code{col7}) if
63  needed.  The rownames will be taken from the original object if
64  \code{edit.row.names = FALSE} and the number of rows is unchanged
65  (otherwise \code{NULL}), and from the edited output if
66  \code{edit.row.names = TRUE}.  (If the \code{row.names} column is
67  incomplete, it is extended by entries like \code{row223}.)
68
69  Editing a matrix or data frame will lose all attributes apart from the
70  row and column names.
71}
72\value{
73  The edited data frame or matrix.
74}
75\author{ Peter Dalgaard }
76\note{
77  \code{fix(dataframe)} works for in-place editing by calling this
78  function.
79
80  If the data editor is not available, a dump of the object is presented
81  for editing using the default method of \code{edit}.
82
83  At present the data editor is limited to 65535 rows.
84}
85\seealso{\code{\link{data.entry}}, \code{\link{edit}}}
86\examples{
87\dontrun{
88edit(InsectSprays)
89edit(InsectSprays, factor.mode = "numeric")
90}
91}
92
93\keyword{utilities}
94