================================================================================
================================================================================

Title:      Audio Cartography - Prepare Data 
Copyright:  2017 University of Oregon
Author:     M. Brittell
License:    GNU General Public License, version 3 (GPL3)

This work was funded in part by the National Science Foundation (NSF) Doctoral 
Dissertation Research Improvement (DDRI) Grant #1634086 and the University of 
Oregon (UO) Lewis Family Endowment.

================================================================================
================================================================================

Three scripts automate the generation of sample data sets and rendering of that 
data in each of four forms.  

Eighteen data sets were generated and rendered in each of four forms to support 
exploration of the use of audio in cartography. The rendered maps are provided 
in the accompanying "audioCartography-maps".  The presentation software is 
provided in the accompanying "audioCartography-present".

As scripts were reviewed prior to sharing, an error was noted in the script 
that renders the audio maps: alignment between reference level phons and equal 
loudness contour (see Render below).

--------------------------------------------------------------------------------
README (This file)
--------------------------------------------------------------------------------
File: audioCartography-prepare-README.txt

An overview of the contents of this part of the collection.

--------------------------------------------------------------------------------
LICENSE
--------------------------------------------------------------------------------
File: audioCartography-prepare-COPYING.txt

A copy of the GNU General Public License, version 3 (GPL3) under which these 
scripts are released.

--------------------------------------------------------------------------------
Make Maps
--------------------------------------------------------------------------------
File: audioCartography-prepare-makeMaps.sh

Bash script to automate the generation and rendering of multiple instances 
of audio maps.  The number of instances to generate must be provided as an 
argument when the script is called.

Usage:
	audioCartography-prepare-makeMaps.sh <N: number of maps to create>
	
Dependencies:
	audioCartography-prepare-generate.R (see below)
	
	audioCartography-prepare-render.py (see below)
	
	Bourne Again Shell (Bash) 3.2.57
		Copyright © 2007 Free Software Foundation 
		GNU General Public License 3 or later
		https://www.gnu.org/software/bash/

    Python 2.7.11
    	Copyright © 2001-2018 Python Software Foundation
        Python Software Foundation ("PSF") license
		https://www.python.org
		
    R 3.3.1
    	Copyright © 2016 R Core Team
		GNU General Public License 2 or 3
		https://www.R-project.org/
		
Inputs:
	N   Number of maps to generate

Outputs:
	<N*5 data representations>    see audioCartography-prepare-generate.R
	<N*3 rendered audio maps>     see audioCartography-prepare-render.py

--------------------------------------------------------------------------------
Generate
--------------------------------------------------------------------------------
File: audioCartography-prepare-generate.R

R script that generates a spatial point pattern, rasterizes the result in an 
8x8 grid by assigning a data value equal to the number of points in each cell,
and classes the data values into three ordinal levels (quantile breaks).  The
result is stored in five formats, two data formats (tabular and matrix), a 
choropleth visualization, and two descriptive summaries (stats and possible 
locations of response options).

The possible locations of response options are determined and saved to 
support preparation of a stimulus set that provides experimental control.  
The listed locations meet the following criteria:
- four continuous grid cells (2x2) share the same data value, 
- one option has data value "high" and the other has data value "low",
- the two response options are offset both horizontally and vertically,
- the black option was to the west (left) of the red option.

Usage: 
	Rscript audioCartography-prepare-generateTrials.R \
		-o <output directory> \
		-i <map identifier>
	
Requires:
	classInt 0.1-23
		Copyright © 2015 Roger Bivand
		GNU General Public License 2 or later
		https://CRAN.R-project.org/package=classInt

	docopt 0.4.5
		Copyright © 2016 Edwin de Jonge
		MIT License
		https://CRAN.R-project.org/package=docopt
		
	maptools 0.8-39
		Copyright © 2016 Bivand and Lewin-Koh
		GNU General Public License 2 or later
		https://CRAN.R-project.org/package=maptools
		
    R 3.3.1
		Copyright © 2016 R Core Team 
		GNU General Public License 2 or 3
        https://www.R-project.org/

	RColorBrewer 1.1-2
		Copyright © 2014 Erich Neuwirth
		Apache License 2.0
		https://CRAN.R-project.org/package=RColorBrewer 

	rgeos 0.3-21
		Copyright © 2016 Bivand and Rundel
		GNU General Public License 2 or later
		https://CRAN.R-project.org/package=rgeos

	spatstat 1.47-0
		Copyright © 2016 Baddeley, Rubak, and Turner
		GNU General Public License 2 or later
		https://CRAN.R-project.org/package=spatstat
		
	sp 1.2-3
		Copyright © 2016 Pebesma and Bivand
		GNU General Public License 2 or later
		https://CRAN.R-project.org/package=sp
	
Inputs:
	-o <output directory>		location where results should be saved
	-i <N: map identifier>		unique identifier used to label the data set

Outputs:	
    concurrent-N.csv            tabular data representation
    graphic-N.pdf               visual representation
    sequential-N.txt            matrix (nested arrays) data representation
    stats-N.csv                 table of data characteristics
    candidateResponses-N.csv    feasible response option locations

--------------------------------------------------------------------------------
Render
--------------------------------------------------------------------------------
File: audioCartography-prepare-render.py

Python script that renders simple spatial data sets (matrix or tabular format)
in an audio stream for display in the fMRI scanner, and aligned  with the 
quiet interval of a sparse sampling sequence.  Each call to the script produces 
a single wave file (.wav) as output, which represents the spatial data provided 
as input.

Rendering uses frequency-based attenuation using value estimated from a 
graphic of ISO 226:2003 equal loudness contours (Lindosland, 2005).  
Attenuation in dB is converted to factor using physics equation (Sengpiel 
Audio, 2014).


CORRECTION: in the maps rendered for the study, the equal loudness contours 
were read along the 40 phon curve and compared to a reference 20 dB at 20 phon.  
The misalignment was identified after data collection was complete.  Three 
adjustments to reflect equal loudness contour at 20 phon are provided in the 
comments (numbered N=1,2,3; annotation "Correction N of 3").

Usage:
	python audioCartography-prepare-renderTrials.py \
		-t <map type> \
		-o <output directory>/<map name>.wav \
		-d <data directory>/<data name>.txt
	
	map type:   "sequential" | "sequential2" | "concurrent"
	data type:  "sequential" | "concurrent"
		
Requires:
	argparse 1.1 - Python Standard Library (see Python)

	csv 1.0 - Python Standard Library (see Python)

	math - Python Standard Library (see Python)

	numpy 1.12.0
		Copyright © 2005 NumPy Developers
		Modified BSD  
		http://www.numpy.org/
		
	Pyo 0.7.9
		Copyright © 2009-2015 Olivier Belanger
        GNU General Public License v3 or later
		http://ajaxsoundstudio.com/software/pyo/.

    Python 2.7.11	
    	Copyright © 2001-2018 Python Software Foundation
        Python Software Foundation ("PSF") license
		https://www.python.org

Inputs:
	-t <map type>          "sequential" | "sequential2" | "concurrent"
                           The "sequential2" value renders the "augmented-
                           sequential" map type

	-o <output directory>/<map name>.wav
                           Absolute or relative path to the output including
                           the name of the file (with extension).

    -d <data directory>/<data name>.txt
                           Absolute or relative path to the data file to be 
                           rendered in audio.  The data file format is expected
                           to be either matrix or tabular 
                           (see audioCartography-prepare-generateTrials.R)

Outputs:
    <map name>.wav

================================================================================
================================================================================

REFERENCES

Baddeley, A., E. Rubak, and R. Turner. (2015) Spatial Point Patterns: 
	Methodology and Applications with R. London: Chapman and Hall/CRC Press, 
	2015. URL http://www.crcpress.com/Spatial-Point-Patterns-Methodology-and-
	Applications-with-R/Baddeley-Rubak-Turner/9781482210200/

Bivand, R.S., E. Pebesma, V. Gomez-Rubio. (2013) Applied spatial data analysis 
	with R, Second edition. Springer, NY. http://www.asdar-book.org/

Lindosland at English Wikipedia. (2005, public domain) ISO equal-loudness 
	contours with frequency in Hz. 
	https://en.wikipedia.org/wiki/Image:Lindos1.svg

Pebesma, E.J., R.S. Bivand. (2005) Classes and methods for spatial data in R. 
	R News 5 (2), https://cran.r-project.org/doc/Rnews/Rnews_2005-2.pdf

R Core Team. (2016) R: A language and environment for statistical computing. R 
    Foundation for Statistical Computing, Vienna, Austria. Available: 
    https://www.R-project.org/.

Sengpiel Audio. (2014) Sound Engineering Calculator: Conversion Factor, Ratio, 
	or Gain to a Level Value (Gain Decibels dB) or vice versa.  Managed in 
	trust by Alexander Sengpiel. Available: 
	http://www.sengpielaudio.com/calculator-FactorRatioLevelDecibel.htm

================================================================================
================================================================================
