Package playitbyr

July 2, 2014
Type Package
Title Representing and exploring data through sound
Version 0.2-1
Date 2012-05-01
Author Ethan Brown
Maintainer Ethan Brown <ethancbrown@gmail.com>
Depends R (>= 2.12.0), csound
Description playitbyr is a exible toolkit for data sonication,with syntax modeled after the gg-
plot2 package. The functions
allow the user to map data onto sonic parameters like pitch,tempo, and rhythm, and out-
put sound and sound les.
URL http://playitbyr.org/
License GPL (>= 2)
SystemRequirements playitbyr creates sound using the csound package,which re-
quires the free and open source software synthesizer
Csound, available at <http://csound.sourceforge.net/>. See
<http://playitbyr.org/csound.html> for more guidance on setting up Csound.
LazyLoad yes
Collate 'aaa.R' 'checkSonify.R' 'getShapeDef.R' 'internaldf.R'
'internalsonify.R' 'linearscale.R' 'octToFreq.R' 'render.R'
'sonaes.R' 'sonify.R' 'sonlayer.R' 'sonscaling.R' 'getSoundParams.R' 'getDefaultMappings.R'
'scorePreprocessor.dotplot.R' 'scorePreprocessor.csound.R'
'render.csound.R' 'sonopts.R' 'expscale.R' 'scorePreprocessor.scatter.R' 'sonsave.R'
'shape-descriptions.R' 'scale-attkp-continuous.R'
'scale-decayp-continuous.R' 'scale-dur-continuous.R' 'scale-identity.R' 'scale-indx-continuous.R'
'scale-mod-continuous.R' 'scale-pan-continuous.R'
'scale-pitch-continuous.R' 'scale-tempo-continuous.R'
'scale-time-continuous.R' 'scale-vol-continuous.R'
1
2 +.sonify
'shape-csound.R' 'shape-dotplot.R' 'shape-scatter.R'
'add-sonify.R' 'print.sonify.R' 'summary.sonify.R' 'sonfacet.R'
'shape-histogram.R' 'scorePreprocessor.histogram.R'
'scorePreprocessor.boxplot.R' 'shape-boxplot.R'
Repository CRAN
Date/Publication 2012-05-03 12:52:01
NeedsCompilation no
R topics documented:
+.sonify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
print.sonify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
scale_attkp_continuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
scale_decayp_exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
scale_dur_continuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
scale_indx_continuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
scale_mod_continuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
scale_pan_continuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
scale_pitch_continuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
scale_tempo_exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
scale_time_continuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
scale_time_identity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
scale_vol_exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
shape_boxplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
shape_csound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
shape_dotplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
shape_histogram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
shape_scatter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
sonaes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
sonfacet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
sonify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
sonopts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
sonsave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
summary.sonify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Index 29
+.sonify Add additional layers or options onto sonify objects
Description
sonify objects can be incrementally added onto to form a complete sonication, much like ggplot
objects.
print.sonify 3
Usage
## S3 method for class sonify
x + y
Arguments
x A sonify object
y An object to be added into the sonify object (see Details).
Details
Adding mappings, layers, facets, and other parameters onto a sonify object is the easiest method
of creating a sonication. The following kinds of objects can be added:
sonaes Mappings of data columns to sound parameters
sonlayer Layers, such as shape_scatter
sonscaling Scalings, such as scale_time_continuous
sonfacet Instructions for faceting the sonication
sonopts Additional options
Value
A sonify object with the relevant y value added into the object.
See Also
sonify for the creation of these objects
print.sonify Print method for sonify objects
Description
Printing a sonify object renders it to sound (analogously to how printing ggplot objects renders
them to screen in the ggplot2 package).
Usage
## S3 method for class sonify
print(x, ...)
4 scale_attkp_continuous
Arguments
x A sonify object
... Additional optional arguments:
render_real_time Render the sonication in real time? If TRUE, the sonica-
tion is rendered in real time (which is faster but may not work as well on
slower computers); if FALSE the sonication is rendered to a le on disk be-
fore playing. The default behavior is given by the option render_real_time.
file The le to render to (if render_real_time = FALSE). The default is a
temporary le.
play If rendering to a le, should the le then be played? Default is TRUE.
playout If playing from a le, what channel should be used for output? This
string is passed to the Csound -o option. Default is "dac", the default audio
out.
Details
In interactive use, you can simply type the name of the sonify object to sonify it. In loops, func-
tions, and source-ing use, however, you need to explicitly call print by using print(x) to print the
object x.
Value
print.sonify is called for its side-effect, which is to actually render the object to a sound. It
invisibly returns the length of the resulting sonication.
Note
By default, a rendering is saved to a le and then immediately played for compatibility with slower
systems. If you have a faster computer and want to play the sonication as you render it, you can
set options("render_real_time" = TRUE). (It is FALSE by default.)
See Also
sonify for the creation of these objects, sonsave for a convenience function that saves a sound le,
sonopts for advanced and low-level rendering options
scale_attkp_continuous
Continuous scales for note attacks
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data (a
column of the data) is to be mapped to sonic parameters (here, "attkp", the sharpness of a notes
initial attack).
scale_decayp_exp 5
Usage
scale_attkp_continuous(soundlimits, limits = NULL,
by = NULL, ...)
scale_attkp_exp(soundlimits, limits = NULL, by = NULL,
...)
Arguments
... Other parameters (currently ignored)
soundlimits The limits of the sound parameter.
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
by The unit to round the sound parameter to.
Details
In shape_scatter, there are 3 phases of a note: the attack (the initial fade-in of the note), sustain
(where the note is held), and the decay (the nal fade-out of the note. attkp is the percentage of
the note devoted to the attack; so a note with attkp = 0.01 would have a very quick start of the
note, whereas a note with attkp = 0.5 would gradually fade in.
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
scale_decayp_exp Continuous note decay scales
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data
(a column of the data) is to be mapped to sonic parameters (here, "decayp", the percentage of the
note devoted to the decay/fade out).
6 scale_dur_continuous
Usage
scale_decayp_exp(soundlimits, limits = NULL, by = NULL,
...)
scale_decayp_continuous(soundlimits, limits = NULL,
by = NULL, ...)
Arguments
... Other parameters (currently ignored)
soundlimits The limits of the sound parameter.
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
by The unit to round the sound parameter to.
Details
In shape_scatter, there are 3 phases of a note: the attack (the initial fade-in of the note), sustain
(where the note is held), and the decay (the nal fade-out of the note. decayp is the percentage of
the note devoted to the decay; so a note with decayp would have a very abrupt ending, whereas a
note with decayp = 0.5 would gradually fade out.
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
scale_dur_continuous Continuous note duration scales
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data (a
column of the data) is to be mapped to sonic parameters (here, "dur", the length of the resulting
note).
Usage
scale_dur_continuous(soundlimits, limits = NULL,
by = NULL, ...)
scale_dur_exp(soundlimits, limits = NULL, by = NULL, ...)
scale_indx_continuous 7
Arguments
... Other parameters (currently ignored)
soundlimits The limits of the sound parameter.
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
by The unit to round the sound parameter to.
Details
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
scale_indx_continuous Continuous modulation index scales
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data
(a column of the data) is to be mapped to sonic parameters (here, "indx", the index of frequency
modulation).
Usage
scale_indx_continuous(soundlimits, limits = NULL,
by = NULL, ...)
scale_indx_exp(soundlimits, limits = NULL, by = NULL,
...)
Arguments
... Other parameters (currently ignored)
soundlimits The limits of the sound parameter.
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
by The unit to round the sound parameter to.
8 scale_mod_continuous
Details
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
scale_mod_continuous Continuous modulation multiplier scales
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data (a
column of the data) is to be mapped to sonic parameters (here, "mod", the modulation frequency as
a multiple of the carrier frequency).
Usage
scale_mod_continuous(soundlimits, limits = NULL,
by = NULL, ...)
scale_mod_exp(soundlimits, limits = NULL, by = NULL, ...)
Arguments
... Other parameters (currently ignored)
soundlimits The limits of the sound parameter.
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
by The unit to round the sound parameter to.
Details
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
scale_pan_continuous 9
scale_pan_continuous Continuous pan scales
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data (a
column of the data) is to be mapped to sonic parameters (here, "pan", the left-right balance of the
note as a number between 0 and 1).
Usage
scale_pan_continuous(soundlimits, limits = NULL,
by = NULL, ...)
scale_pan_exp(soundlimits, limits = NULL, by = NULL, ...)
Arguments
... Other parameters (currently ignored)
soundlimits The limits of the sound parameter.
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
by The unit to round the sound parameter to.
Details
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
10 scale_pitch_continuous
scale_pitch_continuous
Continuous pitch scales
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data
(a column of the data) is to be mapped to sonic parameters (here, "pitch", where middle C is
represented as 8 and each octave as 1).
Usage
scale_pitch_continuous(soundlimits, limits = NULL,
by = NULL, ...)
scale_pitch_exp(soundlimits, limits = NULL, by = NULL,
...)
Arguments
... Other parameters (currently ignored)
soundlimits The limits of the sound parameter.
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
by The unit to round the sound parameter to.
Details
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
scale_tempo_exp 11
scale_tempo_exp Continuous tempo scales
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data (a
column of the data) is to be mapped to sonic parameters (here, "tempo" in beats per minute).
Usage
scale_tempo_exp(soundlimits, limits = NULL, by = NULL,
...)
scale_tempo_continuous(soundlimits, limits = NULL,
by = NULL, ...)
Arguments
... Other parameters (currently ignored)
soundlimits The limits of the sound parameter.
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
by The unit to round the sound parameter to.
Details
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
12 scale_time_continuous
scale_time_continuous Continuous scales for note starting times
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data (a
column of the data) is to be mapped to sonic parameters (here "time", the starting time of the note
in seconds).
Usage
scale_time_continuous(soundlimits, limits = NULL,
by = NULL, ...)
scale_time_exp(soundlimits, limits = NULL, by = NULL,
...)
Arguments
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
soundlimits The limits of the sound parameter.
by The unit to round the sound parameter to.
... Other parameters (currently ignored)
Details
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
scale_time_identity 13
scale_time_identity Use values without scaling
Description
These functions can be added onto a sonify object to indicate that a given parameter is not to be
scaled; the values given in the input data should be take as the given sound values.
Usage
scale_time_identity(...)
scale_pitch_identity(...)
scale_dur_identity(...)
scale_vol_identity(...)
scale_pan_identity(...)
scale_tempo_identity(...)
scale_attkp_identity(...)
scale_decayp_identity(...)
scale_mod_identity(...)
scale_indx_identity(...)
Arguments
... Ignored.
scale_vol_exp Continuous note volume scales
Description
These shortcut functions (with the notation scale_[sound parameter]_[scaling function])
are intended to be added onto a sonify object to specify how [data parameter] from the data
(a column of the data) is to be mapped to sonic parameters (here, "vol", the proportion of the
maximum volume of the note, as a number between 0 and 1).
14 shape_boxplot
Usage
scale_vol_exp(soundlimits, limits = NULL, by = NULL, ...)
scale_vol_continuous(soundlimits, limits = NULL,
by = NULL, ...)
Arguments
... Other parameters (currently ignored)
soundlimits The limits of the sound parameter.
limits The limits of the data to train, a numeric vector of length 2. All data values
outside these limits are returned as NA. If NULL, the default, the function takes
the minimum and maximum of the data
by The unit to round the sound parameter to.
Details
_continuous scales are a linear scaling, whereas _exp is an exponential scale.
Value
A sonscaling object, to be used in sonify or added onto a sonify object.
See Also
shape_scatter, which has more information about this parameter
shape_boxplot 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)
shape_boxplot 15
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 sonied 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 analysts 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 notes length devoted to the initial (linear) attack.
decayp The proportion of the notes 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 Sonication for Exploratory Data Analysis,
in The Sonication Handbook, ed. Hermann, Hunt, Neuhoff. Available: http://sonification.
de/handbook/
16 shape_csound
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
shape_csound Create arbitrary csound layer
Description
Creates a layer that can use an arbitrary csound le as its orchestra (for advanced Csound users).
Usage
shape_csound(...)
Arguments
... Settings or mappings to pass to sonlayer. See Details.
Details
The orchestra le is not actually specied in the layer, its specied in sonopts. The following
parameters are available for setting or mapping:
inst The number of the Csound instrument to be played
start The starting time of the note (in seconds)
dur The duration of the note (in seconds)
p4 thru p20 Additional numbered p-elds, currently available up through p20.
Value
A sonlayer object that can be added onto a sonify object.
shape_dotplot 17
shape_dotplot Create a dotplot layer
Description
Creates a dotplot layer using the sound of a snare drum.
Usage
shape_dotplot(jitter = 0, ..., data = NULL,
mapping = NULL)
Arguments
jitter The maximum size, in seconds, of how much to jitter time by when there are
multiple notes at the same pitch and time (the sonic equivalent of overplotting).
The default, 0, means no jitter occurs.
... data, settings, and mappings to pass to sonlayer (see Details)
data The data.frame to be sonied for this layer. If blank, the data from the parent
sonify object is used.
mapping A sonaes object.
Details
The audio dotplot creates a sense of how the distribution is spread out in time. Users are only
expected to really use the time parameter for mapping, but they may want to ddle with the other
aspects of the sound for aesthetic reasons.
When more than one value appears at a given time, this shape automatically adds noise to "jitter"
the values so they can be heard distinctly.
These parameters are available for setting or mapping:
time The starting time of the snare sound (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).
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.
18 shape_histogram
Author(s)
Originally contributed by Sam Ferguson. Csound instrument created by Hans Mikelson.
References
S. Ferguson, W. Martens and D. Cabrera, Statistical Sonication for Exploratory Data Analysis,
in The Sonication Handbook, ed. Hermann, Hunt, Neuhoff. Available: http://sonification.
de/handbook/
Examples
x <- sonify(iris[1:10,], sonaes(time = Petal.Length)) + shape_dotplot(jitter = 0.3)
## Not run: print(x)
shape_histogram Create a histogram layer
Description
Creates a histogram layer
Usage
shape_histogram(length = 5, tempo = 240, ...,
data = NULL, mapping = NULL)
Arguments
length The overall length, in seconds, of the histogram.
tempo The tempo, in beats per minute; i.e. the rapidity with which to represent values
from the dataset.
... settings to pass to sonlayer (see Details)
data The data.frame to be sonied for this layer. If blank, the data from the parent
sonify object is used.
mapping A sonaes object.
Details
The audio histogram is implemented by a simple frequency-modulation synthesis (through csound),
representing a univariate view of the data by rapidly playing pitches that are samples from the
dataset. Only pitch is intended to be used for mapping.
To compare groups, one can facet by the grouping variable (see sonfacet). All of the examples
below use this technique.
The remainder of the sound parameters (the same as those used by shape_scatter) are available
for setting to tweak aesthetics for the analysts ear:
shape_histogram 19
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 notes length devoted to the initial (linear) attack.
decayp The proportion of the notes 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 Sonication for Exploratory Data Analysis,
in The Sonication Handbook, ed. Hermann, Hunt, Neuhoff. Available: http://sonification.
de/handbook/
Examples
x1 <- sonify(iris, sonaes(pitch = Sepal.Length)) + sonfacet(Species) +
shape_histogram(length = 3, tempo = 1800)
## Not run: x1
x2 <- sonify(iris, sonaes(pitch = Sepal.Length)) + sonfacet(Species) +
shape_histogram(length = 5, tempo = 1800) # plays the same thing for longer
## Not run: x2
x3 <- sonify(iris, sonaes(pitch = Sepal.Length)) + sonfacet(Species) +
shape_histogram(length = 3, tempo = 1200) # same length as original but fewer pitches
## Not run: x3
20 shape_scatter
shape_scatter Create a scatterplot layer
Description
Creates a scatterplot layer; the audio analogue of ggplot2s geom_point.
Usage
shape_scatter(jitter = 0, relative = TRUE, ...,
data = NULL, mapping = NULL)
Arguments
jitter The maximum size, in seconds, of how much to jitter time by when there are
multiple notes at the same pitch and time (the sonic equivalent of overplotting).
The default, 0, means no jitter occurs.
relative Make the duration relative to the overall length of the sonication? The default,
TRUE, means that the sonication will scale durations relative to the length of the
overall sonication (it estimates how long a beat is and then rescales duration
in relation to that). Otherwise, durations remain constant even if the sonication
is much longer or shorter (which may mean that note durations must be ddled
with so they dont overlap).
... settings to pass to sonlayer (see Details)
data The data.frame to be sonied for this layer. If blank, the data from the parent
sonify object is used.
mapping A sonaes object.
Details
The audio scatterplot is implemented by a simple frequency-modulation synthesis (through Csound).
The following parameters are available for setting or mapping:
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 notes length devoted to the initial (linear) attack.
decayp The proportion of the notes 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.
shape_scatter 21
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).
Value
A sonlayer object that can be added onto a sonify object.
Examples
x1 <- sonify(iris, sonaes(time = Petal.Width, pitch = Petal.Length)) +
shape_scatter() # no jitter
## Not run: x1
x2 <- sonify(iris, sonaes(time = Petal.Width, pitch = Petal.Length)) +
shape_scatter(jitter = 0.3) # substantial jitter, fuzzes out overlap
## Not run: x2
## relative = TRUE: rescales duration to fit overall length (usually easier to hear)
d <- cbind(airquality, row = rownames(airquality))
x3 <- sonify(d, sonaes(time = row, pitch = Temp)) + shape_scatter(dur = 3) +
scale_time_continuous(c(0, 10))
## Not run: x3
x4 <- sonify(d, sonaes(time = row, pitch = Temp)) + shape_scatter(dur = 3) +
scale_time_continuous(c(0, 5))
## Not run: x4
## relative = FALSE: duration is in seconds and is not scaled to fit overall length
## (creates lots of overlap)
x5 <- sonify(d, sonaes(time = row, pitch = Temp)) + shape_scatter(relative = FALSE, dur = 3) +
scale_time_continuous(c(0, 10))
## Not run: x5
x6 <- sonify(d, sonaes(time = row, pitch = Temp)) + shape_scatter(relative = FALSE, dur = 3) +
scale_time_continuous(c(0, 5))
## Not run: x6
## Setting the pitch equal to 8 (C), and using iris$Sepal.Width
## to generate the timings of notes##
x7 <- sonify(iris[1:10,], sonaes(time = Sepal.Width)) + shape_scatter(pitch = 9)
## Not run: x7
## Instead, /mapping/ the pitch to 9.
x8 <- sonify(iris[1:10,], sonaes(time = Sepal.Width)) + shape_scatter(pitch = 9)
## Not run: x8
## If a value in the mapping
## is a vector and is not a name of the data column, playitbyr
## creates a new column with that value. This is then scaled,
## producing an unexpected F# (8.5) here when you might expect the same
## sound as above!
22 sonaes
sonaes Create mappings and parameters for sonication objects
Description
Creates a sonaes object, which is a list containing the desired mappings of data columns or con-
stants onto each sound parameter. This is intended be added to a sonify object (or included in its
construction).
Usage
sonaes(...)
Arguments
... Sonic parameter mappings, specic to the shape being rendered. All arguments
must be named, with the argument names sonic parameters and the values ei-
ther numeric values (to set the sonic parameter to that value as a constant) or a
column of the data.frame that is to be sonied (with or without quotes).
Details
Setting sonic parameters to data.frame columns is the heart of making the sonication. The sound
parameters that can be the arguments of sonaes depend on the kinds of layers present; see sonify
for a list of the possible kinds of layers.
Value
A sonaes object, used in or added to a sonify object or sonlayer.
See Also
sonify. Also, see aes from the ggplot2 package, which inspired this function.
Examples
## Maps Petal.Width onto tempo,
## Sepal.Width onto pitch,
## and sets scalings
## (not terribly informative, since the order is
## arbitrary)
x <- sonify(iris, sonaes(tempo=Petal.Width,
pitch=Sepal.Width)) + shape_scatter()
summary(x)
## Not run: x ## Quite long!
## Use a different tempo scaling than default
## to hear more of the data faster
## Not run: x + scale_tempo_continuous(c(300, 1000))
sonfacet 23
## Map Petal.Width onto time instead
y <- x + sonaes(time=Petal.Width)
summary(y)
## Not run: y
## Seems clipped, so increase duration
## Not run: y + sonaes(dur=4)
sonfacet Simple faceting
Description
Allows creation of facets for a sonication, i.e. to separately sonify different groups of a dataset,
one after another. Analogous to ggplot2s facet_wrap.
Usage
sonfacet(facet = NULL, scales = "fixed", pause = 0.5)
Arguments
facet Variable to split by
scales Should scales be xed ("fixed", the default), or free ("free")
pause Length of pause, in seconds, between each facet
Details
When added onto a sonify object, this function splits the data by the variable given in facets and
creates separate sonications for each subset of the data. All factor levels not used in the data will
automatically be dropped.
Note
Unlike facet_wrap, this function does not take a formulainstead it only takes the name of the data
variable to split by.
Examples
df <- data.frame(pits = c(0, 1, 1, 2, 2, 3),
tims = c(0, 1, 0, 1, 0, 1),
facs = c(0, 0, 1, 1, 2, 2))
x <- sonify(df, sonaes(time = tims, pitch = pits)) + shape_scatter(dur = 1) +
scale_time_continuous(c(0, 1)) + scale_pitch_continuous(c(8, 8.25)) +
sonfacet(facs, pause = 1)
## Not run: x
24 sonify
sonify Create sonication objects
Description
Creates a sonify object, the fundamental workhorse of playitbyr; this is a list containing the
data.frame to be sonied, 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 sonied
mapping This species the mappings of the data paramters (i.e. columns of data) to
sound parameters (such as start time, duration, et cetera). Its a sonaes object,
best created by sonaes.
The available sound parameters for mapping depend on what kind of sonica-
tion youre doing. This is specied 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 fa-
cilitate 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
sonify 25
shape_csound A layer that can use an arbitrary csound le 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 facetingthis splits data by the values in one of its columns
and creates separate sonications 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 sonication is to create a sonify object with this function, specify-
ing the data.frame you want sonied 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 sonication.
Value
A sonify object, which contains what is needed to render the object. If the object is completely
specied, 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 sonication.
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.
See Also
summary.sonify
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
26 sonopts
## 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
sonopts Sonication rendering options
Description
Set advanced options for a sonication
Usage
sonopts(...)
Arguments
... Named parameters for setting rendering options. See Details.
Details
Use this function if you want to modify a few settings for a single sonication.
The following options are available, which mirror the input arguments to createPerformance from
the csound package. Note that most of these will be ignored for many shapes, since they set these
options themselves on the back end.
i Usually this is not specied, since this will replace any intended sonication. A list of matrix
objects. Each matrix is not specied in sonopt since these values are usually created and
passed by playitbyr itself. the instructions for a single instrument. Each row of the matrix is
an i statement, which instructs Csound to make an instrument active at a specic time and for
a certain duration, and with certain parameters (p-elds). These p-elds are interpreted in the
order of the columns of the matrix.
f Not used for "built-in.orc". A list of numeric vectors; these create the function tables Csound
uses for oscillators and various other uses.
orcle The path of the orchestra le to be used for the performance. If this equals "built-in.orc",
the default, the orchestra included with this package will be used (see scoreMatrices for
more details of using the built-in instruments.)
scorele The path of the score le, if any, to be used for the performance. The whole purpose of
this function is to feed the score statements to Csound and bypass the need for score les, but
this option is provided in any case.
out String representing where to send output sound; the default, "dac", indicates to send it your
computers sound output. If you want to render a le, enter the path to the (WAV) le you
want.
sonsave 27
realTime Indicates whether the performance is to be rendered in real time. If you are rendering to
a le, you probably want this as FALSE, since it can render a whole lot faster than real-time to
le.
nishPerformance Should the performance be closed after completing the score? If TRUE, the
default, cleans up and closes Csound. If FALSE, returns a pointer to a Csound instance that can
be used to continue the performance or eventually close it.
suppressDisplays Csound by default pops up with annoying graphical widgets. This alloys you to
suppress them (the default).
moreags A character vector of extra command-line ags to pass to Csound upon compilation of
the orchestra. See The Csound Manuals page on the Csound command-line options.
csInstance An instance of Csound that can be used to continue or close the current performance.
Note
By default, a rendering is saved to a le and then immediately played for compatibility with slower
systems. If you have a faster computer and want to play the sonication as you render it, you can
set options("render_real_time" = TRUE). (It is FALSE by default.)
sonsave Save sonications to an audio le
Description
Convenience function to save a sonify object to an audio (.wav) le
Usage
sonsave(what, where, play = FALSE, out = "dac", ...)
Arguments
what A sonify object
where The path to the desired .wav output.
play Play the resulting le after saving?
out If playing, this gives the output channel. Usually users will want to leave this as
"dac", the default (which plays to the default audio out).
... other arguments to be passed onto the rendering.
Value
Returns the lename of the saved le.
28 summary.sonify
summary.sonify Summary method for sonify objects
Description
Summarizes the structure of a sonify object in ways useful for seeing what the output will be.
Usage
## S3 method for class sonify
summary(object, ...)
Arguments
object A sonify object
... Ignored.
Value
summary.sonify prints a brief summary, including info about the dataset to be sonied, and the
specied mappings and scalings of sonic values to data parameters.
Author(s)
Closely based on summary.ggplot by Hadley Wickham
See Also
sonify for the creation of these objects
Examples
summary(sonify(iris, sonaes(time = Sepal.Length, pitch = Sepal.Width)) +
shape_scatter() + shape_dotplot())
Index
+.sonify, 2
aes, 22
createPerformance, 26
facet_wrap, 23
print.sonify, 3
scale_attkp_continuous, 4
scale_attkp_exp
(scale_attkp_continuous), 4
scale_attkp_identity
(scale_time_identity), 13
scale_decayp_continuous
(scale_decayp_exp), 5
scale_decayp_exp, 5
scale_decayp_identity
(scale_time_identity), 13
scale_dur_continuous, 6
scale_dur_exp (scale_dur_continuous), 6
scale_dur_identity
(scale_time_identity), 13
scale_indx_continuous, 7
scale_indx_exp (scale_indx_continuous),
7
scale_indx_identity
(scale_time_identity), 13
scale_mod_continuous, 8
scale_mod_exp (scale_mod_continuous), 8
scale_mod_identity
(scale_time_identity), 13
scale_pan_continuous, 9
scale_pan_exp (scale_pan_continuous), 9
scale_pan_identity
(scale_time_identity), 13
scale_pitch_continuous, 10, 15, 17, 19, 20
scale_pitch_exp
(scale_pitch_continuous), 10
scale_pitch_identity
(scale_time_identity), 13
scale_tempo_continuous
(scale_tempo_exp), 11
scale_tempo_exp, 11
scale_tempo_identity
(scale_time_identity), 13
scale_time_continuous, 3, 12, 24
scale_time_exp (scale_time_continuous),
12
scale_time_identity, 13
scale_vol_continuous (scale_vol_exp), 13
scale_vol_exp, 13
scale_vol_identity
(scale_time_identity), 13
scoreMatrices, 26
shape_boxplot, 14, 24
shape_csound, 16, 25
shape_dotplot, 17, 24
shape_histogram, 15, 18, 24
shape_scatter, 3, 512, 14, 15, 1719, 20, 24
sonaes, 3, 15, 1721, 22, 24
sonfacet, 3, 18, 23, 25
sonify, 24, 1517, 19, 21, 22, 24, 27, 28
sonlayer, 3, 15, 17, 18, 20
sonopts, 3, 4, 16, 25, 26
sonsave, 4, 27
sonscaling, 3, 24
source, 4
summary.sonify, 25, 28
29