R: Create sonification objects

sonify {playitbyr} R Documentation

Create sonification objects

Description

Creates a sonify object, the fundamental workhorse of playitbyr; this is a list containing the data.frame to be sonified, the mappings of data to sound parameters, the scaling of parameters, and additional options.

Usage

  sonify(data = NULL, mapping = sonaes(),
    scales = sonscaling(), sonlayers = NULL,
    opts = sonopts(), sonfacet = NULL)

Arguments

`data`	a `data.frame` with the data to be sonified
`mapping`	This specifies the mappings of the data paramters (i.e. columns of `data`) to sound parameters (such as start time, duration, et cetera). It's a `sonaes` object, best created by `sonaes`. The available sound parameters for mapping depend on what kind of sonification you're doing. This is specified by the `shape_` convenience function, and the available sound parameters are documented on those help pages (see e.g. `shape_scatter`).
`scales`	What range of the sound parameter should the data be scaled to, and how should the scaling be done? Practically, the best way to deal with tweaking scales is to add on the `scale_` convenience function for whichever sound parameter you want to change, like `scale_time_continuous`. If specifying manually (not recommended), this is a `sonscaling` object which gives the scaling function and desired parameter range from the data to each sound.
`sonlayers`	Layers allow you to specify the type of audio display, and multiple layers allow you to display different aspects of the data to play simultaneously. The best way of doing this is to add on the `shape_` function that you want. Current possibilities are: `shape_scatter` A scatterplot of notes with many aspects of the sound available for setting and mapping, generated by FM synthesis `shape_dotplot` Creates a sense of the distribution of a variable, represented by start time, using a snare drum sound `shape_histogram` Gives a sense of the distribution of values (represented by pitch) by sampling the dataset (this can be used along with faceting to facilitate comparisons of groups). `shape_boxplot` Gives a sense of the distribution of values (represented by pitch) by sampling the dataset in increasingly narrow percentiles around the median `shape_csound` A layer that can use an arbitrary csound file as its orchestra (not for beginners!) If specifying manually (not recommended), this is a single `sonlayer` object, or a list of `sonlayer` objects, that gives each layer to be rendered.
`opts`	Advanced rendering options; this is easiest to use by adding on the function `sonopts`
`sonfacet`	playitbyr supports faceting–this splits `data` by the values in one of its columns and creates separate sonifications for each group, played on after another. See `sonfacet` for more information on how to do this. If specifying manually (not recommended), this is a `sonfacet` object that gives what variables to split by.

Details

The easiest way of building up a sonification is to create a sonify object with this function, specifying the data.frame you want sonified as the data parameter and possibly the mappings. Then, you can add on (with +) additional mappings, layers, scalings and facets later. See Arguments section for more explanation of each of these pieces, and the Examples for how you can add the pieces together to form a complete sonification.

Value

A sonify object, which contains what is needed to render the object. If the object is completely specified, it can by rendered simply by calling the print method for the object (i.e. simply typing the name of the object at the R prompt).

Note

When used in a loop, function, or other non-interactive use, a sonify object needs to be printed in order to actually be turned into sound. So, assign the output of this function to an object and then use print(foo) to hear the sonification.

References

The syntax of sonify objects is heavily based on that of ggplot objects in the ggplot2 package. See the ggplot2 web site for more information.

Examples

## A bare-bones sonify object, but one that cannot render
x <- sonify()
summary(x)
## Not run: x # Throws an error message

## Creating a sonification incrementally
## and with the "scale_" convenience functions
x <- sonify(iris)
x <- x + sonaes(time=Petal.Length, pitch=Petal.Width)
x <- x + shape_scatter()
x <- x + scale_pitch_continuous(c(6, 8)) + scale_time_continuous(c(0, 10))
summary(x)
## Not run: x # outputs sound