sonipy Documentation

A Scatterplot Sonification Package

A package to turn scatter plots into perceptually uniform sound files for use in science and to make science more accessible.

This project was developed by Locke Patton and Prof. Emily Levesque. Click here for a twitter thread explaining the motivation behind this project.

What does sonipy do?

Here is an example sonification.

Our method of sonification takes in scatterplot data and produces audio clips that depict each datapoint as a short sound blip with a y value corresponding to pitch and an x value corresponding to arrival time.

sonipy setup

Each data point has a corresponding short tone called a ``blip``, with a y value corresponding to its pitch and a x value corresponding to its arrival time. Higher y value data points have higher corresponding blip pitches.

Installation

sonipy is pip-installable from command line, as follows:

pip install sonipy

Alternately, you can clone the repository and install it yourself, also in command line:

git clone https://github.com/lockepatton/sonipy.git
cd sonipy
python setup.py install

If you would just like to play around with our sonifying tool online, without any installation, you can play with the tutorial with binder here.

Example Easy Setup

For two arrays of the same length, called x and y, you can sonify them using the following:

from sonipy.sonify import SonifyTool

Tone = SonifyTool(x, y)
Tone.play()
Tone.save()

Extended Setup

If you would like more fine control of the sonification inputs, you can adjust the underlying arguments as follows. For details about the parameters involved, see the Parameter Inputs section below.

from sonipy.sonify import SonifyTool

C4 = 261.6 # Hz
frequency_args = {
  'frequency_min' : C4,
  'frequency_max' : C4*4
  # 'cents_per_value' : -680,
  # 'value_min' : 0,
  # 'value_max' : 1,
}

duration_args = {
  'time_total' : 2000, # ms
  # 'time_min' : 100, # ms
  # 'time_max' : 800, # ms
}

duration_scale = 1. / 2000. # x value / time (ms)

Tone = SonifyTool(x, y,
                  frequency_args = frequency_args,
                  duration_args = duration_args,
                  # duration_scale = duration_scale,
                  bliplength=0.5)

Tone.play()
Tone.SaveTone()

Parameter Inputs

Frequency Scale Parameters:

All frequency parameters are entered inside the frequency_args parameter. The following inputs are all accepted.

1. a minimum frequency and it’s corresponding minimum y value

2. a maximum frequency and it’s corresponding maximum y value

3. a change in pitch (measured in

cents) over change in y value parameter

Time Scale Parameters:

By default, the sound files are 2 seconds. Time parameters are entered by simply by defining a duration_scale (in seconds per x value). Or alternately by passing a duration_args dictionary with some total time, smallest delta time between points or max delta time between points.

1. a total time of the soundfile

2. a change in time (measured in seconds) over change in x value

parameter

Demos

Several Jupyter notebook demos that demonstrate some use cases and examples of sonipy are found here, with an interactive version found here.

TransientZoo Motivation

This code was developed as part of TransientZoo, a citizen science program that will allow participants, including blind and visually impaired individuals, to classify supernova lightcurves using sound. In astronomy, lightcurves depict variations in brightness of a specific astrophysical object as a function of time. For more, see this summary twitter thread and poster from the 235th American Astronomical Meeting.

Special Thanks

Thank you to Prof. Allen Downey for permission to host his thinkDSP code in this repository for easier distribution. This work wouldn’t be possible without it. For more details about his book Think DSP: Digital Signal Processing in Python, see his textbook repository at https://github.com/AllenDowney/ThinkDSP.

Reach Out

Have an issue with your operating system? Let us know by opening an issue! Have a suggestion for how to make this code more accessible? Send Locke an email at locke.patton@cfa.harvard.edu.

Attribution

If you find the package useful in your research, please cite our JOSS paper.

Reference/API

sonipy Package

SonifyTool(x, y[, frequency_args, …])	This is a built-in-one sonification tool for creating a MultiTone.
cent_per_value(f_min, f_max, v_min, v_max)	This function takes in a frequency max and min, and y value max and min and returns a y scale parameter in units of cents/y value.
from_max_ms(x, dtime_max)	Calculates a time scale in units of x value / time (ms), by matching the largest time step in the x array to the input dtime_max.
from_min_ms(x, dtime_min)	Calculates a time scale in units of x value / time (ms), by matching the smallest time step in the x array to the input dtime_min.
from_total_ms(x, time_total)	Calculates a time scale in units of x value / time (ms), by matching the total length of x array to the input time_total.
getScale(x[, time_total, dtime_min, dtime_max])	Function that takes in a total time between blips, minimum difference between successive blips or maximum difference between successive blips and returns a time scale in units of x value / ms.
get_f_max(f_min, cents_per_value, v_min, v_max)	This function takes in a y value max and min, a minimum frequency and a y scale parameter in units of cents/y value, and returns the maximum frequency that fits to such a scale.
get_f_min(f_max, cents_per_value, v_min, v_max)	This function takes in a y value max and min, a maximum frequency and a y scale parameter in units of cents/y value, and returns the minimum frequency that fits to such a scale.

DurationsScale(scale)	This class builds the x component of the sonification - the durations scale.
FrequencyScale(value_min, value_max[, …])	This class builds a frequency scale and populates the namespace of frequency objects based on the given inputs from the following combos:
MultiTone(starttimes, values[, bliplength, …])	Class for building a MultiTone, and saving it as audio files.

Indices and tables

• Index

• Module Index

• Search Page