The R Project SVN R-packages

Rev

Rev 3282 | Rev 3358 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 3282 Rev 3324
Line 1... Line 1...
1 
\name{sqlite.data.frame}
 1 
\name{sqlite.data.frame}
2 
\alias{sqlite.data.frame}
 2 
\alias{sqlite.data.frame}
3 
\alias{sdf}
 3 
\alias{sdf}
4 
%- Also NEED an '\alias' for EACH other topic documented here.
 - 
 
5 
\title{SQLite Data Frame}
 4 
\title{SQLite Data Frame}
6 
\description{ Creates an sqlite data frame (SDF) from ordinary data frame.  }
 5 
\description{ Creates an sqlite data frame (SDF) from ordinary data frames.  }
7 
\usage{
 6 
\usage{
8 
sqlite.data.frame(x, name=NULL)
 7 
sqlite.data.frame(x, name=NULL)
9 
}
 8 
}
- 
 
 9 
\arguments{
- 
 
 10 
  \item{x}{The object to be coerced into a data frame which is then stored in a
- 
 
 11 
SQLite database. \code{as.data.frame} is called first on x before creating
- 
 
 12 
the SDF database. }
- 
 
 13 
  \item{name}{The internal name of the SDF. If none is provided, a generic
- 
 
 14 
name \emph{data}<n> is used (e.g. data1, data2, etc). Each SDF should have a unique
- 
 
 15 
internal name and also be a valid R symbol. Numbers are appended to names in case of duplicates,
- 
 
 16 
e.g. if name arg is \emph{iris}, and it already exists, then the
- 
 
 17 
new SDF will have a name \emph{iris1}. If it still exists, then the name
- 
 
 18 
will be \emph{iris2}, and so on. }
- 
 
 19 
}
10 
\details{
 20 
\details{
- 
 
 21 
SQLite data frames (SDF's) are data frames whose data are stored in a SQLite database.
- 
 
 22 
SQLite is an open source, powerful (considering its size), light weight data base engine.
- 
 
 23 
It stores each database (composed of tables, indices, etc.) in a single file. Since a
- 
 
 24 
single SDF occupies a whole database, each SDF will be contained in a single file.
11 
 
 25 
 
- 
 
 26 
Each SDF file contains the following tables:
- 
 
 27 
\itemize{
- 
 
 28 
\item{sdf_attributes}{a key-value table that contains the SDF attributes. Currently,
- 
 
 29 
only \emph{name} is used representing the SDF's internal name.}
- 
 
 30 
\item{sdf_data}{contains the actual data. Factors and ordered variables are stored as
- 
 
 31 
integers. Their levels are stored in other tables. Numeric (real) are stored as double,
- 
 
 32 
characters as text and integers as int's. Currently, complex numbers are not supported.
- 
 
 33 
Column names correspond exactly to the variable names of the ordinary data frames. E.g.
- 
 
 34 
Petal.Length will have a column name Petal.Length in the table. This is possible
- 
 
 35 
because SQLite allows almost any kind of column name as long as it is quoted by
- 
 
 36 
square brakets ([ ]). You're on your own if you try to be a smartass on this. Also,
- 
 
 37 
an extra column named \emph{row name} (with the space between the words), of type
- 
 
 38 
text is used to store the data frame row names is set as the table's primary key.
- 
 
 39 
So please don't use \emph{row name} as a variable name.}
- 
 
 40 
\item{[factor <colname>] and [ordered <colname>]}{stores the levels and level labels
- 
 
 41 
for each factor variable in the SDF. One such table will be created for every
- 
 
 42 
factor or ordered var, even if two variables share the same level labels. Besides
- 
 
 43 
storing the level data, it is used to mark a column as being a factor.}
12 
}
 44 
}
13 
\value{
 45 
 
- 
 
 46 
SDF's are managed in a workspace separate from R's. When SQLiteDF is loaded, it searches
- 
 
 47 
for the file \code{workspace.db} in the current working directory. This file contains
- 
 
 48 
a list of SDF's created/used in the previous session (i.e. SQLiteDF sessions are automatically
14 
  \item{x}{The object to be converted into a data frame and then stored in a
49 
saved), including their full and relative path and attach information.
15 
SQLite database. }
 50 
Workspace is managed using the SQLite engine
- 
 
 51 
by opening \code{workspace.db} as the main database and then attaching (SQLite's attach) the SDF's.
16 
  \item{name}{The name of the SDF. If none is provided, a generic
 52 
Unfortunately, the number of attached databases is limited to 31 (actually 32, but 1 is reserved
17 
name \emph{data}<n> is used. Names will be appended with numbers to prevent
 53 
for the temp db). Therefore, SDF's are \emph{scored} according to the number of times
- 
 
 54 
it has been used. When the maximum allowed attachment is reached, the least used attached
- 
 
 55 
SDF's is detached and the needed one is attached in its place. The packaged SQLite3 static library
- 
 
 56 
has been modified to have 31 maximum attachments, because the default is 10.
- 
 
 57 
 
- 
 
 58 
Back to when SQLiteDF is loaded, after opening \code{workspace.db}, the SDF's stored in the list
18 
duplicates. E.g. if name arg is \emph{iris}, and it already exists, then the
 59 
are sorted according to their number of uses in the previous session and then the
19 
new SDF will have a name \emph{iris1}. If it still exists, then the name
 60 
first 30 are attached. The relative path is used for finding the SDF file. If the file
- 
 
 61 
cannot be found, it is deleted from the SQLiteDF workspace (with a warning message). The
20 
will be \emph{iris2}, and so on.
 62 
scores are then all reset.
- 
 
 63 
 
- 
 
 64 
A sqlite.data.frame object is basically list with the following elements:
- 
 
 65 
\itemize{
- 
 
 66 
\item{iname}{the internal name of the SDF.}
- 
 
 67 
\item{row.names}{A sqlite.vector of mode character containing the row names of the SDF}
- 
 
 68 
\item{class}{The S3 class vector \code{c("sqlite.data.frame", "data.frame")}}
21 
}
 69 
}
22 
}
 70 
}
- 
 
 71 
\value{
- 
 
 72 
A S3 object representing the SDF. The SDF database will be created in the same directory
23 
\references{ ~put references to the literature/web site here ~ }
 73 
with file name derived by appending the extension \emph{db} to the passed internal
- 
 
 74 
name, or the default internal name if none is provided.
- 
 
 75 
}
24 
\author{Miguel A. R. Manese}
 76 
\author{Miguel A. R. Manese}
25 
\note{
 77 
\note{
26 
A SDF is created by creating a sqlite database, with the specified name
 78 
The full path is used to avoid attaching the same db which may have different relative path
27 
as the filename with a db extension (e.g. data1.db). Each SDF is contained in
 79 
after the user changes directory after loading SQLiteDF (see \code{attachSdf}.
- 
 
 80 
}
- 
 
 81 
\seealso{
- 
 
 82 
    \code{\link[SQLiteDF]{lsSdf}}
- 
 
 83 
    \code{\link[SQLiteDF]{getSdf}}
- 
 
 84 
    \code{\link[SQLiteDF]{attachSdf}}
28 
a separate database. The name of the stored in the SDF.
 85 
    \code{\link[SQLiteDF]{detachSdf}}
29 
}
 86 
}
30 
\seealso{ ~~objects to See Also as \code{\link{help}}, ~~~ }
 - 
 
31 
\examples{
 87 
\examples{
32 
    library(datasets)
 88 
    library(datasets)
33 
    iris.sdf <- sqlite.data.frame(iris)
 89 
    iris.sdf <- sqlite.data.frame(iris)
34 
    names(iris.sdf)
 90 
    names(iris.sdf)
35 
    class(iris.sdf)
 91 
    class(iris.sdf)