Working on documentation

NAMESPACE

@@ -216,6 +216,7 @@ S3method(y_lab,smooth_spectrum)
 S3method(y_lab,sparse_spectrum)
 S3method(y_unit,smooth_spectrum)
 S3method(y_unit,sparse_spectrum)
+export("%>%")
 export("amp<-")
 export("freq<-")
 export("metadata<-")

R/imports.R

@@ -1,6 +1,3 @@
-#' @importFrom magrittr "%>%"
-NULL
-
 #' @importFrom graphics "plot"
 NULL
 

R/pc-chord-type.R

@@ -56,7 +56,7 @@ pc_chord_type.pc_set_type <- function(x) {
 }
 
 #' @export
-#' @rdname pc_set_norm_order
+#' @rdname pc_chord_type
 pc_chord_type.pc_set_norm_order <- function(x) {
   pc_chord_type(pc_set_type(x))
 }

R/represent.R

@@ -1,9 +1,21 @@
-.representations <- c("fr_chord", "sparse_fr_spectrum",
-                      "pi_chord", "pi_chord_type",
-                      "sparse_pi_spectrum",
-                      "pc_chord", "pc_chord_type",
-                      "pc_set", "pc_set_type", "pc_set_norm_order",
-                      "milne_pc_spectrum", "wave")
+.representations <- c(
+  "fr_chord",
+  "milne_pc_spectrum",
+  "pc_chord",
+  "pc_chord_type",
+  "pc_set",
+  "pc_set_norm_order",
+  "pc_set_type",
+  "pi_chord",
+  "pi_chord_type",
+  "smooth_pc_spectrum",
+  "smooth_pi_spectrum",
+  "sparse_fr_spectrum",
+  "sparse_fr_spectrum",
+  "sparse_pc_spectrum",
+  "sparse_pi_spectrum",
+  "wave"
+)
 
 #' Representations
 #'

R/utils-pipe.R

@@ -0,0 +1,11 @@
+#' Pipe operator
+#'
+#' See \code{magrittr::\link[magrittr]{\%>\%}} for details.
+#'
+#' @name %>%
+#' @rdname pipe
+#' @keywords internal
+#' @export
+#' @importFrom magrittr %>%
+#' @usage lhs \%>\% rhs
+NULL

README.Rmd

@@ -9,26 +9,91 @@ knitr::opts_chunk$set(
   collapse = TRUE,
   comment = "#>",
   fig.path = "man/figures/README-",
-  out.width = "100%"
+  out.width = "70%",
+  fig.width = 6, 
+  fig.height = 3,
+  dpi = 300
 )
 ```
-# hrep - Harmony Representations
+# Representing harmony with the hrep package
 
 [![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
 [![Travis build status](https://travis-ci.org/pmcharrison/hrep.svg?branch=master)](https://travis-ci.org/pmcharrison/hrep)
 [![AppVeyor build status](https://ci.appveyor.com/api/projects/status/github/pmcharrison/hrep?branch=master&svg=true)](https://ci.appveyor.com/project/pmcharrison/hrep)
 [![Coverage status](https://coveralls.io/repos/github/pmcharrison/hrep/badge.svg)](https://coveralls.io/r/pmcharrison/hrep?branch=master)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2545770.svg)](https://doi.org/10.5281/zenodo.2545770)
 
-`hrep` is an R package that provides methods for 
-representing and manipulating chord sequences.
-It is currently still under active development,
-but we plan an official release in 2019.
+*hrep* is an R package for representing and manipulating 
+chords and chord sequences.
 
-We recommend you explore the [online documentation](https://pmcharrison.github.io/hrep).
+## Resources
 
-## Development notes
+- [Function-level documentation](https://pmcharrison.github.io/hrep/reference/index.html)
+- [Changelog](https://pmcharrison.github.io/hrep/news/index.html)
+- [File an issue](https://github.com/pmcharrison/hrep/issues)
 
-- The integer representation of a given representation
-must begin at 1 and count upwards with no missing values.
-0 can optionally be used to code missing chords (but this is not implemented here).
+## Installation
+
+The *hrep* package may be installed from GitHub as follows:
+
+``` r
+if (!requireNamespace("devtools")) install.packages("devtools")
+devtools::install_github("pmcharrison/hrep")
+```
+
+## Example usage
+
+Chords may be defined as sequences of integers, with each integer
+corresponding to a pitch or a pitch class.
+The following chord defines a C major triad in first inversion:
+
+```{r}
+library(hrep)
+x <- pi_chord(c(52, 60, 67))
+print(x)
+```
+
+From this symbolic representation, it is possible to derive various 
+acoustic and sensory representations, such as:
+
+a) A wave:
+
+```{r}
+plot(wave(x))
+```
+
+b) A sparse pitch spectrum:
+
+```{r}
+plot(sparse_pi_spectrum(x))
+```
+
+c) A sparse pitch-class spectrum:
+
+```{r}
+plot(sparse_pc_spectrum(x))
+```
+
+d) A smooth pitch-class spectrum:
+
+```{r}
+plot(smooth_pc_spectrum(x))
+```
+
+Chords can be translated to various symbolic representations,
+which can be encoded to integer formats.
+For example, here we convert the chord to the pitch-class chord representation,
+and then encode it to an integer.
+
+```{r}
+pc_chord((x))
+as.integer(encode(pc_chord(x)))
+```
+
+Similarly, the following code expresses the chord as a pitch-class set,
+and then encodes the pitch-class set as an integer.
+
+```{r}
+pc_set(x)
+as.integer(encode(pc_set(x)))
+```

README.md

@@ -1,7 +1,7 @@
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
-# hrep - Harmony Representations
+# Representing harmony with the hrep package
 
 [![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
 [![Travis build
@@ -12,15 +12,98 @@ status](https://ci.appveyor.com/api/projects/status/github/pmcharrison/hrep?bran
 status](https://coveralls.io/repos/github/pmcharrison/hrep/badge.svg)](https://coveralls.io/r/pmcharrison/hrep?branch=master)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2545770.svg)](https://doi.org/10.5281/zenodo.2545770)
 
-`hrep` is an R package that provides methods for representing and
-manipulating chord sequences. It is currently still under active
-development, but we plan an official release in 2019.
+*hrep* is an R package for representing and manipulating chords and
+chord sequences.
 
-We recommend you explore the [online
-documentation](https://pmcharrison.github.io/hrep).
+## Resources
 
-## Development notes
+  - [Function-level
+    documentation](https://pmcharrison.github.io/hrep/reference/index.html)
+  - [Changelog](https://pmcharrison.github.io/hrep/news/index.html)
+  - [File an issue](https://github.com/pmcharrison/hrep/issues)
 
-  - The integer representation of a given representation must begin at 1
-    and count upwards with no missing values. 0 can optionally be used
-    to code missing chords (but this is not implemented here).
+## Installation
+
+The *hrep* package may be installed from GitHub as follows:
+
+``` r
+if (!requireNamespace("devtools")) install.packages("devtools")
+devtools::install_github("pmcharrison/hrep")
+```
+
+## Example usage
+
+Chords may be defined as sequences of integers, with each integer
+corresponding to a pitch or a pitch class. The following chord defines a
+C major triad in first inversion:
+
+``` r
+library(hrep)
+x <- pi_chord(c(52, 60, 67))
+print(x)
+#> Pitch chord: 52 60 67
+```
+
+From this symbolic representation, it is possible to derive various
+acoustic and sensory representations, such as:
+
+1)  A wave:
+
+<!-- end list -->
+
+``` r
+plot(wave(x))
+```
+
+<img src="man/figures/README-unnamed-chunk-2-1.png" width="70%" />
+
+2)  A sparse pitch spectrum:
+
+<!-- end list -->
+
+``` r
+plot(sparse_pi_spectrum(x))
+```
+
+<img src="man/figures/README-unnamed-chunk-3-1.png" width="70%" />
+
+3)  A sparse pitch-class spectrum:
+
+<!-- end list -->
+
+``` r
+plot(sparse_pc_spectrum(x))
+```
+
+<img src="man/figures/README-unnamed-chunk-4-1.png" width="70%" />
+
+4)  A smooth pitch-class spectrum:
+
+<!-- end list -->
+
+``` r
+plot(smooth_pc_spectrum(x))
+```
+
+<img src="man/figures/README-unnamed-chunk-5-1.png" width="70%" />
+
+Chords can be translated to various symbolic representations, which can
+be encoded to integer formats. For example, here we convert the chord to
+the pitch-class chord representation, and then encode it to an integer.
+
+``` r
+pc_chord((x))
+#> Pitch-class chord: [4] 0 7
+as.integer(encode(pc_chord(x)))
+#> [1] 8210
+```
+
+Similarly, the following code expresses the chord as a pitch-class set,
+and then encodes the pitch-class set as an integer.
+
+``` r
+pc_set(x)
+#> Pitch-class set: 0 4 7
+as.integer(encode(pc_set(x)))
+#> [1] 145
+```

inst/_pkgdown.yml

@@ -3,7 +3,7 @@ template:
     bootswatch: cerulean
 reference:
 - title: Types
-  desc: These provide different ways of representing chords.
+  desc: Types provide different ways of representing chords.
   contents:
   - '`type`'
   - '`represent`'
@@ -14,10 +14,14 @@ reference:
   - '`pc_chord`'
   - '`pc_chord_type`'
   - '`pc_set`'
-  - '`pc_set_norm_form`'
+  - '`pc_set_norm_order`'
+  - '`pc_set_type`'
   - '`pi_chord`'
   - '`pi_chord_type`'
+  - '`smooth_pc_spectrum`'
+  - '`smooth_pi_spectrum`'
   - '`sparse_fr_spectrum`'
+  - '`sparse_pc_spectrum`'
   - '`sparse_pi_spectrum`'
   - '`.wave`'
   - '`wave`'
@@ -69,6 +73,7 @@ reference:
 - title: Manipulating chords
   desc: Manipulating properties of chords.
   contents:
+  - '`combine_sparse_spectra`'
   - '`edit_bass_pc`'
   - '`tp`'
 - title: Miscellaneous utilities
@@ -98,6 +103,11 @@ reference:
   - '`is.coded_vec`'
   - '`is.equal_tempered`'
   - '`is.milne_pc_spectrum`'
+  - '`is.smooth_pc_spectrum`'
+  - '`is.smooth_pi_spectrum`'
+  - '`is.sparse_fr_spectrum`'
+  - '`is.sparse_pc_spectrum`'
+  - '`is.sparse_pi_spectrum`'
   - '`is.pc_chord`'
   - '`is.pc_set`'
   - '`is.pi_chord`'