README.Rmd

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>",
    fig.path = "README-"
)
options(width = 80)
set.seed(0)
```

frame
=====

[![Build Status (Linux)][travis-badge]][travis]
[![Build Status (Windows)][appveyor-badge]][appveyor]
[![Coverage Status][codecov-badge]][codecov]
[![CRAN Status][cran-badge]][cran]
[![License][apache-badge]][apache]
[![CRAN RStudio Mirror Downloads][cranlogs-badge]][cran]


*frame* is an R package providing a `dataset` type analogous to a
`data.frame` supporting two major extensions: (1) associate keys with one
or more components to each row; (2) use matrix-like objects as columns,
including nested datasets.


Installation
------------

### Stable version

*frame* is [available on CRAN][cran]. To install the latest released version,
run the following command in R:

```r
### install.packages("frame") # not yet, actually
```

### Development version

To install the latest development version, run the following:

```r
devtools::install_github("patperry/r-frame")
```


Usage
-----

### Datasets

The `dataset` type is like a `data.frame` but it allows matrix-like columns,
including sparse matrices and nested datasets.

```{r}
# dataset with a sparse matrix column
(x <- dataset(age = c(35, 70, 12, 42),
              color = c("red", "blue", "black", "green"),
              set = Matrix::sparseMatrix(i = c(1, 1, 2, 3, 3, 4),
                                         j = c(3, 2, 1, 3, 2, 1),
                                         x = c(2.8, -1.3, 7.1, 0.1, -5.1, 3.8),
                                         dimnames = list(NULL, c("a", "b", "c")))))

# dataset with a dataset column
(y <- dataset(value = rnorm(4), nested = x))
```

### Keys

Datasets can have multi-component keys that uniquely identify each row.
You can index a dataset just like a `data.frame`, or you can use key values
to extract particular rows.

```{r}
# set multi-component keys
keys(x) <- keyset(major = c("x", "x", "y", "y"),
                  minor = c(1, 2, 1, 3))

# show the data keys and values
print(x)

# index with keys
x[dataset(major = c("y", "x"),
          minor = c(  3,   1)), ]
```


Citation
--------

Cite *frame* with the following BibTeX entry:

    @Manual{,
        title = {frame: Data with Context},
        author = {Patrick O. Perry},
        year = {2018},
        note = {R package version 0.0.0},
    }


Contributing
------------

The project maintainer welcomes contributions in the form of feature requests,
bug reports, comments, unit tests, vignettes, or other code.  If you'd like to
contribute, either

 + fork the repository and submit a pull request;

 + [file an issue][issues];

 + or contact the maintainer via e-mail.

This project is released with a [Contributor Code of Conduct][conduct],
and if you choose to contribute, you must adhere to its terms.


[apache]: https://www.apache.org/licenses/LICENSE-2.0.html "Apache License, Version 2.0"
[apache-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg "Apache License, Version 2.0"
[appveyor]: https://ci.appveyor.com/project/patperry/r-frame/branch/master "Continuous Integration (Windows)"
[appveyor-badge]: https://ci.appveyor.com/api/projects/status/github/patperry/r-frame?branch=master&svg=true "Continuous Inegration (Windows)"
[building]: #development-version "Building from Source"
[codecov]: https://codecov.io/github/patperry/r-frame?branch=master "Code Coverage"
[codecov-badge]: https://codecov.io/github/patperry/r-frame/coverage.svg?branch=master "Code Coverage"
[conduct]: https://github.com/patperry/r-frame/blob/master/CONDUCT.md "Contributor Code of Conduct"
[cran]: https://cran.r-project.org/package=frame "CRAN Page"
[cran-badge]: http://www.r-pkg.org/badges/version/frame "CRAN Page"
[cranlogs-badge]: http://cranlogs.r-pkg.org/badges/frame "CRAN Downloads"
[issues]: https://github.com/patperry/r-frame/issues "Issues"
[travis]: https://travis-ci.org/patperry/r-frame "Continuous Integration (Linux)"
[travis-badge]: https://api.travis-ci.org/patperry/r-frame.svg?branch=master "Continuous Integration (Linux)"