shape_boxplot: Create a boxplot layer

View source: R/shape-boxplot.R

shape_boxplotR Documentation

Create a boxplot layer

Description

Gives a sense of the distribution of values by sampling at increasingly narrow percentiles around the median.

Usage

  shape_boxplot(length = 5, tempo = 240, pause = 0.1, ...,
    data = NULL, mapping = NULL)

Arguments

length

The overall length, in seconds, of each segment of the boxplot.

tempo

The tempo, in beats per minute; i.e. the rapidity with which to represent values from the dataset.

pause

The pause between each segment of the boxplot, in seconds.

...

settings to pass to sonlayer (see Details)

data

The data.frame to be sonified for this layer. If blank, the data from the parent sonify object is used.

mapping

A sonaes object.

Details

The audio boxplot is implemented by a simple frequency-modulation synthesis (through csound), representing a univariate view of the data by rapidly playing pitches in the 5th to 95th percentile, then the interquartile range (25th to 75th), then the median, all sampled from the dataset. (It is essentially shape_histogram evaluated separately on each of these subsets of the data.)

Only pitch is intended to be used for mapping but the remainder of the same parameters available in shape_scatter are available for setting to suit the analyst's ear:

time

The starting time of the note (in seconds).

pitch

The pitch of the note, in the Csound oct notation notation for pitches, where 8 is middle C and 1 represents an octave, to the corresponding frequency in Hertz. By default this is scaled to the nearest musical (chromatic) pitch. (See scale_pitch_continuous.)

dur

The duration of the note (relative to the total time if relative = TRUE, in seconds otherwise).

amp

The volume of the note, as a proportion between 0 and 1, where 1 is the maximum volume. Note that a multiple notes that happen at the same time could add up to more than one, causing distortion and clipping.

attkp

The proportion of the note's length devoted to the initial (linear) attack.

decayp

The proportion of the note's length devoted to the (linear) decay.

indx

The index of modulation. This affects the distortion of the tone; indx = 0 is a sine wave, whereas higher indices of modulation give increasingly complex tones.

mod

The modulating frequency, given as a multiple of the primary frequency (i.e. given by pitch).

To set a sound parameter to a value, you simply include it as an extra argument in shape_scatter; to map a parameter, you set the mapping for the layer or the sonify object using sonaes (see examples in shape_scatter).

Value

A sonlayer object that can be added onto a sonify object.

References

S. Ferguson, W. Martens and D. Cabrera, “Statistical Sonification for Exploratory Data Analysis”, in The Sonification Handbook, ed. Hermann, Hunt, Neuhoff. Available: http://sonification.de/handbook/

Examples

x1 <- sonify(iris, sonaes(pitch = Sepal.Length)) + sonfacet(Species) +
   shape_boxplot(length = 1, tempo = 1800)
## Not run: x1 # facet by Species
x2 <- sonify(iris, sonaes(pitch = Sepal.Length)) +
  shape_boxplot(length = 2, tempo = 1800) # plays each segment longer
## Not run: x2
x3 <- sonify(iris, sonaes(pitch = Sepal.Length)) +
  shape_boxplot(length = 1, tempo = 1200) #  same length as original but fewer pitches
## Not run: x3

statisfactions/playitbyr documentation built on Jan. 27, 2024, 1:33 p.m.