Auto-doc ymls

.gitignore

@@ -27,6 +27,8 @@
 # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
 __pypackages__/
 
+__pycache__/
+
 # Celery stuff
 celerybeat-schedule
 celerybeat.pid

MANIFEST.in

@@ -1,2 +1,3 @@
 include src/strauss/presets/*/*.yml
-include src/strauss/presets/*/*/*.yml
+include src/strauss/presets/*/*/*.yml
+include src/strauss/data/*.csv

README.md

@@ -9,14 +9,20 @@
 
 ## Getting Started
 
-Access the [full documentation here](https://strauss.readthedocs.io/) *(under construction!)* and read more about the associated [Audio Universe project here](https://www.audiouniverse.org/).
+Access the [full documentation here](https://strauss.readthedocs.io/) and read more about the associated [Audio Universe project here](https://www.audiouniverse.org/).
 
-*STRAUSS* is  [PyPI hosted package](https://pypi.org/project/strauss/) and can be installed directly via `pip`:
+*STRAUSS* is  [PyPI hosted package](https://pypi.org/project/strauss/) and `pip` can be used for the default installation:
 
-`pip install strauss`
+`pip install 'strauss[default]'`
 
 For a standard install (without text-to speech support).
 
+For development purposes, you can instead use:
+
+`pip install -e .`
+
+where the `-e` option allows a local install, such that you can modify and run the source code on the fly without needing to reinstall each time. 
+
 If you would like access to all the resources and explore the code directly, make a copy of the *STRAUSS* repository via SSH,
 
 `git clone [email protected]:james-trayford/strauss.git strauss`
@@ -31,12 +37,6 @@ and install *STRAUSS* from your local repository using `pip`
 
 `pip install .`
 
-For development purposes, you can instead use:
-
-`pip install -e .`
-
-where the `-e` option allows a local install, such that you can modify and run the source code on the fly without needing to reinstall each time. 
-
 We recommend using a conda environment to avoid package conflicts. Type
 
 `conda env create -f environment.yml`
@@ -51,7 +51,7 @@ and activate the environment with
 
 *STRAUSS* can also be installed with text-to-speech (TTS) support, allowing audio captioning of sonifications and future accessibility features, via the [TTS module](https://github.com/coqui-ai/TTS). Due to the specific module requirements of this module, install can sometimes lead to incompatibilities with other modules and be slower, so is packaged with *STRAUSS* as an optional extra. If you'd like to use these features, its easy to directly from PyPI:
 
-`pip install strauss[TTS]`
+`pip install 'strauss[TTS]'`
 
 or if you're working from a local copy of the repository, as above, use
 

docs/conf.py

@@ -13,7 +13,7 @@
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
-
+sys.path.insert(0, os.path.abspath('../../src/strauss/presets'))
 
 # -- Project information -----------------------------------------------------
 
@@ -35,8 +35,12 @@
               'sphinx.ext.ifconfig', 'sphinx.ext.viewcode',
               'sphinx.ext.inheritance_diagram',
               'sphinx.ext.autosummary','sphinx.ext.coverage',
-              'sphinx.ext.napoleon']
+              'sphinx.ext.napoleon', "myst_parser",
+              "sphinx_exec_code"]#, 'sphinxcontrib.jquery']
 
+html_js_files = [
+    'js/custom.js'
+]
 
 print(extensions)
 
@@ -55,12 +59,16 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'nature'
+# html_theme_path = [sphinx_pdj_theme.get_html_theme_path()]
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# enable markdown
-#extensions.append('myst_parser')
+myst_footnote_transition = False
+
+# html_theme_options = {
+#     'page_width': '1200px'
+# }

docs/detailed.rst

@@ -1,32 +1,71 @@
 .. _detailed:
 
 Detailed Documentation
-^^^^^^^^^^^^^^^^^^^^^^
+######################
 
 .. automodule:: strauss
     :imported-members:
 
+User-Facing Modules
+*******************
+
+These are the user-facing modules of the ``strauss`` code, that are used to define a ``Sonification``.
+
+
 Sources
-*******
+=======
    .. automodule:: strauss.sources 
       :members:
-
+      :show-inheritance:
 Score
-*****
+=====
    .. automodule:: strauss.score
       :members:
-
+      :show-inheritance:	 
 Generator
-*********
+=========
    .. automodule:: strauss.generator
       :members:
+      :show-inheritance:
 
 Channels
-********
+========
    .. automodule:: strauss.channels
       :members:
-	 
+      :show-inheritance:
 Sonification
-************
+============
    .. automodule:: strauss.sonification
       :members:
+      :show-inheritance:
+
+Ancillary Modules
+*****************
+
+These are modules intended for internal use by the ``strauss`` module
+
+Utilities
+=========
+   .. automodule:: strauss.utilities
+      :members:
+      :show-inheritance:
+Stream
+======
+   .. automodule:: strauss.stream
+      :members:
+      :show-inheritance:
+Notes
+=====
+   .. automodule:: strauss.notes
+      :members:
+      :show-inheritance:
+Filters
+=======
+   .. automodule:: strauss.filters
+      :members:
+      :show-inheritance:
+Text-to-Speech
+==============
+   .. automodule:: strauss.tts_caption
+      :members:
+      :show-inheritance:

docs/elements.rst

@@ -23,7 +23,7 @@ Source Class
 
 The :code:`Source` classes in Strauss are so named because they act as `sources of sound` in the sonification. Sources are used to represent the input data, by mapping this data to properties of sound (volume, position, frequency, etc). The choice of how to set up the sources depends on the data being sonified, and what the user wants to convey. For this, Strauss defines two generic classes that inherit the parent :code:`Source` class; :code:`Events` and :code:`Objects`, described below.
 
-**Full documentation of the mappable parameters are coming soon!** See :obj:`./examples` for example mappings in jupyter notebooks.
+**Full documentation of the mappable parameters is coming soon!** See :obj:`./examples` for example mappings in Jupyter Notebooks and Python scripts.
 
 `Events`
 ''''''''
@@ -46,3 +46,46 @@ In this case, sound is produced continuously by the source, with the evolving pr
    Some examples of :code:`Objects` in scientific data could be; `A galaxy evolving, planets orbiting, a plant growing, a glacier flowing, a climate changing etc...`   
 
 .. _score:
+
+Score Class
+***********
+
+With the audio :code:`Sources` defined, the :code:`Score` class allows us to place ‘musical’ constraints on the sound they produce to represent the underlying data. The duration of the output sonification is also specified via the Score with the timeline of the sonification scaled to fit this duration.
+
+.. _generator:
+
+Generator Class
+***************
+
+The :code:`Generator` class takes instruction from the two prior classes and generates audio for each individual source. This can be achieved using either the :code:`Sampler` or :code:`Synthesiser` child classes (along with the :code:`Spectraliser` special case), detailed below.
+
+`Sampler`
+'''''''''
+
+This class generates audio by triggering **pre-recorded audio samples**.
+
+A directory of audio files is used to specify which sample to use for each note of the sampler. These samples are loaded into the sampler and are interpolated to allow arbitrary pitch shifting. Samples can also be looped in a number of ways to allow notes to sustain perpetually. 
+
+`Synthesiser`
+'''''''''''''
+
+This class instead **generates audio additively using mathematical functions** via an arbitrary number of oscillators. The strauss synthesiser supports a number of oscillator forms.
+
+`Spectraliser`
+''''''''''''''
+
+A special case of the :code:`Synthesiser`, this generator synthesises sound from an input spectrum, via an inverse Fast Fourier Transform (IFFT), with randomised phases. The user can specify the audible frequency range that the ‘spectralised’ audio is mapped over.
+
+.. _channels:
+
+Channels Class
+**************
+
+Once sound has been produced for each :code: `source`, the final step is to mix the audio down into some multi-channel audio format. The :code:`Channels` class essentially represents a bank of virtual microphones, with 3D antennae patterns, that each correspond to a channel in the output file.
+
+.. _sonification:
+
+Sonification Class
+******************
+
+The top-level :code:`Sonification` class loads in all the above classes and produces the final sonification. Once :code:`Sources`, :code:`Score`, :code:`Generator` and :code:`Channels` classes are defined, the :code:`Sonification` class is invoked. The :code:`render()` method can then be run to produce the sonification. 

docs/examples.rst

@@ -4,11 +4,48 @@
 Examples
 ^^^^^^^^
 
-Here, we explain some of the example sonfications included in the :code:`examples/` directory of the Strauss repo. These are all in *Python Notebook* (:code:`.ipynb`) format.
+Here, we explain some of the example sonfications included in the :code:`examples/` directory of the Strauss repo. These are all in both *Python Notebook* (:code:`.ipynb`) and *Python script* (:code:`.py`) format so you can choose which format you prefer to use.
+
+Audio Caption (:code:`AudioCaption.ipynb`)
+******************************************
+The *Audio Caption* example demonstrates how to add audio captions to a sonification, using a text-to-speech (TTS) module. The TTS module is not included in the standard Strauss installation, but it can be installed by using pip install strauss[TTS]. This example uses the Strauss :code:`Sampler` to play a short sequence of glockenspiel notes, then generates an audio caption using a standard TTS voice. The notebook allows the user to try different voices and languages from TTS.
+
+
+Day Sequence (:code:`DaySequence.ipynb`)
+****************************************
+The *Day Sequence* sonification generates the sunrise to sunset sonification used in the `"Audio Universe: Tour of the Solar System" <https://www.audiouniverse.org/education/shows/tour-of-the-solar-system>`_, an immersive planetarium show designed with sonifications so it can be enjoyed and understood irrespective of level of vision. Samples are downloaded from a Google drive to a local directory, and are played using the Strauss :code:`Sampler`. This spatialisation can be mapped to any audio setup, and a :code:`5.1` system was used for the planetarium, but for the example we use :code:`stereo`.
+
+
+Earth System (:code:`EarthSystem.ipynb`)
+****************************************
+The *Earth System* sonification represents the ratio of ocean to land along lines of longitude as the Earth spins through three rotation cycles. We use the Strauss :code:`Synthesiser` to generate chords. A low pass filter is employed to generate a brighter sound to represent a high water fraction and a duller sound for high land fraction. 
+
+A video of this sequence is available starting at 2:17 in `this video <https://www.youtube.com/watch?v=h1muFAEMmOs>`_.
+
+Light Curve Soundfonts (:code:`LightCurveSoundfonts.ipynb`)
+************************************************************
+The *Light Curve Soundfonts* example demonstrates how to use imported soundfont files to use virtual musical instruments in a sonification. Soundfont files are widely available online. We download flute and guitar sounds from `Soundfonts 4 U <https://sites.google.com/site/soundfonts4u/>`_. We load the sounds into the Strauss :code:`Sampler`, and select a preset. The soundfonts are used to sonify a light curve for the variable star 55 Cancri, creating the audio equivalent of a scatter plot. The note length and volume envelope can be adjusted to improve the articulation of individual data points. To demonstrate an alternative approach, we use an :code: `Object` source type, where we evolve a sound over time to represent the data. This is analogous to a line graph, representing a continuous data series. We use a held chord, changing the cutoff frequency of the low-pass filter to create a "brighter" timbre when the star is brighter and a "duller" sound when the star is darker.
+
+
+Planetary Orbits (:code:`PlanetaryOrbits.ipynb`)
+************************************************
+The *Planetary Orbits* example generates sonifications used in the "Audio Universe: Tour of the Solar System" planetarium show. Each planet in the Solar System is assigned a unique note, with the smallest planets having the highest notes and the largest planets having the lowest notes. The sonification length for each is set according to the planet's orbital period, and the volume is varied by orbital azimuth. The audio system is set as 'stereo' by default but for the planetarium '5.1' is used. This creates the effect of the planets moving in orbits at relative speeds to represent the real relative motions.
+
+A video of this sequence with the audio is available `here <https://www.youtube.com/watch?v=WI-WPvXeAgk>`_.
+
+Sonifying Data 1D (:code:`SonifyingData1D.ipynb`)
+*************************************************
+The *Sonifying Data 1D* example demonstrates some generic techniques for sonifying one-dimensional data series. We construct some mock data with features and noise. For all examples we use the Strauss :code:`Synthesiser` to create a 30 second, mono sonification. We demonstrate a variety of ways to map y as a function of x, using the change in some expressive property of sound (e.g. pitch_shift, volume and filter-cutoff) as a function of time.
+
+
+Spectral Data (:code:`SpectralData.ipynb`)
+******************************************
+The *Spectral Data* sonification demonstrates use of the Strauss :code:`Spectraliser` to represent data. We use a direct spectralisation approach where the sound is generated by treating the 1D data as a sound spectrum. This uses a direct inverse Fourier transform, which is relatively intuitive for spectral data, especially where the spectral features are similar to those that can be identified in sound. We use Planetary Nebulae data, objects dominated by strong emission lines, to demonstrate this. We plot the spectra vs wavelength and spectra vs frequency, and use the Strauss :code:`Synthesiser` to create a 30 second, mono sonification. We set the ranges for the mapped parameters and render the sonification. A second example uses an "Object" type sonification with an evolving Spectrum to sonify an image. We represent the image by evolving from left to right, with higher features in the y-axis having a higher pitch.
+
 
 Stars Appearing (:code:`StarsAppearing.ipynb`)
 **********************************************
 
-The *Stars Appearing* sonification demonstrates the generation of a sonification that was used directly in `a planetarium show for visually impaired children <https://www.audiouniverse.org/tour-of-the-solar-system>`_. This is intended to represent the appearance of stars in the night sky to an observer. Over time, the sky darkens and our eyes adjust, allowing us to see more and more stars. To represent this, the brightest stars appear first, with dimmer stars appearing later. Data on the colours of the stars is used to set the note used for each stars sound, with bluer stars higher notes and redder stars lower notes. We use the Strauss :code:`Sampler` to play a glockenspiel sound for each star as it appears. The actual positions of stars in the sky is used to spatialise the audio, with westerly stars positioned in the right speaker and easterly stars in the left. This spatialisation can be mapped to any audio setup, and a :code:`5.1` system was used fo the planetarium, but for the example we use :code:`stereo`
+The *Stars Appearing* sonification demonstrates the generation of a sonification that was used directly in the "Audio Universe: Tour of the Solar System" planetarium show. This is intended to represent the appearance of stars in the night sky to an observer. Over time, the sky darkens and our eyes adjust, allowing us to see more and more stars. To represent this, the brightest stars appear first, with dimmer stars appearing later. Data on the colours of the stars is used to set the note used for each stars sound, with bluer stars having higher notes and redder stars having lower notes. We use the Strauss :code:`Sampler` to play a glockenspiel sound for each star as it appears. The actual positions of stars in the sky is used to spatialise the audio, with westerly stars positioned in the right speaker and easterly stars in the left. This spatialisation can be mapped to any audio setup, and a :code:`5.1` system was used for the planetarium, but for the example we use :code:`stereo`.
 
 A video of this sequence with the audio is available `here <https://www.youtube.com/watch?v=5HS3tRl2Ens>`_.

docs/index.rst

@@ -1,4 +1,5 @@
-.. strauss documentation master file, created by
+.. strauss
+   documentation master file, created by
    sphinx-quickstart on Tue Oct 26 14:56:02 2021.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
@@ -8,7 +9,7 @@ Welcome to the STRAUSS documentation!
 
 Strauss is a python toolkit for data *"sonification"* - the representation of data using sound - with both scientific and outreach applications.
 
-The code aims to make rich and evocative sonification straightforward, with a number of presets and examples enabling a quick start. At the same time, it is intended to be flexible enough to allow high level of control over the sonification and various expressive elements of sound and harmony if required. You can read about the associated `Audio Universe project here <https://www.audiouniverse.org/>`_ for outreach and examples using Strauss.
+The code aims to make rich and evocative sonification straightforward, with a number of presets and examples enabling a quick start. At the same time, it is intended to be flexible enough to allow high level of control over the sonification and various expressive elements of sound and harmony if required. The project is described in more detail in the paper `Introducing STRAUSS: a flexible sonification Python package <https://arxiv.org/abs/2311.16847/>`_, presented at the 28th Proceedings of the `International Community of Auditory Displays (2023) <https://repository.gatech.edu/entities/publication/6f73e8a9-ae9a-447f-a174-64ca28a2f3bb/full/>`_. You can read about the associated `Audio Universe project here <https://www.audiouniverse.org/>`_ for examples of using Strauss for a variety of applications.
 
 .. note::
    Strauss and its documentation are currently in development, with more details and features coming soon. Look out for / follow the repo  our first numbered release, and accompanying article!
@@ -19,10 +20,11 @@ The code aims to make rich and evocative sonification straightforward, with a nu
    motivation
    start
    elements
+   params
    detailed
    examples
    todo
-
+   
 Indices and tables
 ==================
 

docs/js/custom.js

@@ -0,0 +1,3 @@
+$(document).ready(function () {
+    $('a.external').attr('target', '_blank');
+});