diff --git a/docs/source/contribute.rst b/docs/source/_static/.gitkeep similarity index 100% rename from docs/source/contribute.rst rename to docs/source/_static/.gitkeep diff --git a/docs/source/conf.py b/docs/source/conf.py index 83a41508e46100285fad462685a64a1495b363d0..0796a3d87db7189b66e80ad0b7435229890c3684 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,3 +1,6 @@ +#import sphinx_rtd_theme + + # Configuration file for the Sphinx documentation builder. # # This file only contains a selection of the most common options. For a full @@ -14,7 +17,6 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) -master_doc = 'index' # needed for read the docs # -- Project information ----------------------------------------------------- @@ -24,6 +26,7 @@ author = 'Michael Blaß' # The full version, including alpha/beta/rc tags release = '0.1.3' +version = '0.1.3' # -- General configuration --------------------------------------------------- @@ -31,22 +34,10 @@ release = '0.1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinxcontrib.apidoc', 'sphinx.ext.napoleon'] - -# apidoc config -apidoc_module_dir = '../../apollon/' -apidoc_output_dir = 'reference' -apidoc_separate_modules = True -apidoc_module_first = True -apidoc_full = True - -# napoleaon config -napoleon_numpy_docstring = False -napoleon_google_docstring = True -napoleon_use_param = True -napoleon_use_rtype = True -napoleon_use_keyword = True - +extensions = [ + #'sphinxcontrib.apidoc', + 'sphinx.ext.napoleon', + 'sphinx_rtd_theme'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -68,3 +59,25 @@ html_theme = 'sphinx_rtd_theme' # 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'] + + +# -- Options for apidoc ----------------------------------------------------- +# +apidoc_module_dir = '../../src/apollon' +apidoc_output_dir = 'reference' +apidoc_separate_modules = True +apidoc_module_first = True +apidoc_full = True + + +# -- Options for Napoleon --------------------------------------------------- +# +napoleon_google_docstring = True +napoleon_numpy_docstring = False +napoleon_include_init_with_doc = True +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = False +napoleon_use_ivar = True +napoleon_use_param = True +napoleon_use_keyword = True +napoleon_use_rtype = True diff --git a/docs/source/download.rst b/docs/source/download.rst new file mode 100644 index 0000000000000000000000000000000000000000..c10742c71f88bde73c21a1c956ffcfd7e9b2bbc8 --- /dev/null +++ b/docs/source/download.rst @@ -0,0 +1,11 @@ +Download +*************************************** + +You can either download the source code from the `apollon GitHub repository`_ +or clone it directly with + +.. code-block:: Bash + + git clone https://github.com/teagum/apollon.git + +.. _apollon GitHub repository: https://github.com/teagum/apollon.git diff --git a/docs/source/framework.rst b/docs/source/framework.rst new file mode 100644 index 0000000000000000000000000000000000000000..0acad7e9e498899aadf0c3c8fdca945aef4e43d7 --- /dev/null +++ b/docs/source/framework.rst @@ -0,0 +1,16 @@ +Framework +*************************************** + +Audio Feature Extraction +======================================= +Extract some of the most common low-level audio feauters. + + +Hidden Markov Model +======================================= +Estimate Poisson-distributed Hidden Markov Models. + + +Self-Organizing Map +======================================= +Train some Self-organizing maps. diff --git a/docs/source/index.rst b/docs/source/index.rst index ad9c48ddec229fc99c3d02a495332f4a9d6ed38c..be6332868d4f4ebf98977143f7357a9f9dd35cd0 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,7 +8,7 @@ Welcome to the documentation of the apollon feature extraction framework! *apollon* is a feature extraction and modelling frame work for music data analysis. It handles low-level audio feature extraction, their aggreagation using Hidden Markov models, and comparison by means of the Self-Organizing Map. -See the :doc:`starters` chapter for gentle introduction to the mentioned +See the :doc:`framework` chapter for gentle introduction to the mentioned concepts. Contents @@ -17,10 +17,10 @@ Contents .. toctree:: :maxdepth: 2 - installation - starters - clt - contribute + download + install + framework + reference/modules * :ref:`genindex` * :ref:`modindex` diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 0000000000000000000000000000000000000000..fce46e414212a5c73a899e0871918a54141f0b55 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,33 @@ +Installation +*************************************** +apollon can be installed on GNU/Linux, macOS, and Windows. Installation process +is similar on each of these plaforms. Note, however, that apollon contains +Python C extension modules, which have to be compile locally for GNU/Linux and +Windows users. If work on any of those platforms, please make shure that there +is a C compiler set up on your machine; otherwise the installation will fail. +In the case of macOS, a precompiled wheel is provided for the latest version +only. + + +Install using pip +======================================= +The Python packager manager can automatically install download and install +apollon from pip. Simply run the following command from your terminal: + +.. code-block:: Bash + + python3 -m pip install apollon + + +Install from source +======================================= +You can also install and compile apollon directly from its sources in three +steps: + +* Download the apollon source code +* Open a terminal and navigate to the apollon root directory +* Install and compile with the following command + +.. code-block:: Bash + + python3 -m pip install . diff --git a/docs/source/installation.rst b/docs/source/installation.rst deleted file mode 100644 index bdb722a4457b0649c7022a7f5d8628bb96ae3105..0000000000000000000000000000000000000000 --- a/docs/source/installation.rst +++ /dev/null @@ -1,16 +0,0 @@ -Before you order -================ - -1. Download ------------ -Download the repository from the gitlab server using -``git clone git@gitlab.rrz.uni-hamburg.de:bla7667/apollon.git`` - -2. Installation ----------------- -To install apollon, navigate to its repository's source directory and install -using pip: -`` -cd path/to/apollon -pip install . -`` diff --git a/docs/source/modules.rst b/docs/source/modules.rst deleted file mode 100644 index 3d0e131cafec9374bd500220453055f6fa6cea55..0000000000000000000000000000000000000000 --- a/docs/source/modules.rst +++ /dev/null @@ -1,6 +0,0 @@ -apollon -======= - -.. toctree:: - :maxdepth: 4 - diff --git a/docs/source/reference/apollon.analyses.rst b/docs/source/reference/apollon.analyses.rst deleted file mode 100644 index a925627d2cf1dc48d1e23ed536c70ce0016e7613..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.analyses.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.analyses module -======================= - -.. automodule:: apollon.analyses - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.aplot.rst b/docs/source/reference/apollon.aplot.rst deleted file mode 100644 index caf67e66c9de81b92ab5a7b58eba0fb1f92d0980..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.aplot.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.aplot module -==================== - -.. automodule:: apollon.aplot - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.audio.rst b/docs/source/reference/apollon.audio.rst deleted file mode 100644 index 64efcb2b3a10d870384b5290479f22573bf7c528..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.audio.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.audio module -==================== - -.. automodule:: apollon.audio - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.commands.apollon_export.rst b/docs/source/reference/apollon.commands.apollon_export.rst deleted file mode 100644 index 26c7857ac0adc6421a2a0055125731d2d2a03fae..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.commands.apollon_export.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.commands.apollon\_export module -======================================= - -.. automodule:: apollon.commands.apollon_export - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.commands.apollon_features.rst b/docs/source/reference/apollon.commands.apollon_features.rst deleted file mode 100644 index 35168847949b740d6f1781406cb372600634cd1b..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.commands.apollon_features.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.commands.apollon\_features module -========================================= - -.. automodule:: apollon.commands.apollon_features - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.commands.apollon_hmm.rst b/docs/source/reference/apollon.commands.apollon_hmm.rst deleted file mode 100644 index fd3bc55bd5dc968222c8474c83739dcf7ee0d026..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.commands.apollon_hmm.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.commands.apollon\_hmm module -==================================== - -.. automodule:: apollon.commands.apollon_hmm - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.commands.apollon_onsets.rst b/docs/source/reference/apollon.commands.apollon_onsets.rst deleted file mode 100644 index c18836a56eae02f9cd13d856da71e2b9dfe3abc7..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.commands.apollon_onsets.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.commands.apollon\_onsets module -======================================= - -.. automodule:: apollon.commands.apollon_onsets - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.commands.rst b/docs/source/reference/apollon.commands.rst deleted file mode 100644 index ae032a3ded23f66ff05bfcc77e1d88ced7049504..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.commands.rst +++ /dev/null @@ -1,18 +0,0 @@ -apollon.commands package -======================== - -.. automodule:: apollon.commands - :members: - :undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - apollon.commands.apollon_export - apollon.commands.apollon_features - apollon.commands.apollon_hmm - apollon.commands.apollon_onsets - diff --git a/docs/source/reference/apollon.datasets.rst b/docs/source/reference/apollon.datasets.rst deleted file mode 100644 index fcca8082ac27fa2ba8f8a85e390e2ce71f9b03b1..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.datasets.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.datasets module -======================= - -.. automodule:: apollon.datasets - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.fractal.rst b/docs/source/reference/apollon.fractal.rst deleted file mode 100644 index 8a5ae9ed4baeeecc8afe92af011f37fbf5021c28..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.fractal.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.fractal module -====================== - -.. automodule:: apollon.fractal - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.hmm.graph.grapher.rst b/docs/source/reference/apollon.hmm.graph.grapher.rst deleted file mode 100644 index e8fa67791a674b9be024aa6e8ec452b40b366016..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.hmm.graph.grapher.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.hmm.graph.grapher module -================================ - -.. automodule:: apollon.hmm.graph.grapher - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.hmm.graph.rst b/docs/source/reference/apollon.hmm.graph.rst deleted file mode 100644 index de6bccda87995bbab0c58a907329e5d8fab35ba8..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.hmm.graph.rst +++ /dev/null @@ -1,15 +0,0 @@ -apollon.hmm.graph package -========================= - -.. automodule:: apollon.hmm.graph - :members: - :undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - apollon.hmm.graph.grapher - diff --git a/docs/source/reference/apollon.hmm.hmm_utilities.rst b/docs/source/reference/apollon.hmm.hmm_utilities.rst deleted file mode 100644 index eb8c41c4246d57e4ced66c7a069b90b605dddcbe..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.hmm.hmm_utilities.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.hmm.hmm\_utilities module -================================= - -.. automodule:: apollon.hmm.hmm_utilities - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.hmm.poisson.poisson_core.rst b/docs/source/reference/apollon.hmm.poisson.poisson_core.rst deleted file mode 100644 index ec4d0df4018688d8e737c020bb11f495209e664f..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.hmm.poisson.poisson_core.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.hmm.poisson.poisson\_core module -======================================== - -.. automodule:: apollon.hmm.poisson.poisson_core - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.hmm.poisson.poisson_hmm.rst b/docs/source/reference/apollon.hmm.poisson.poisson_hmm.rst deleted file mode 100644 index 71942c4914051678eba2cf557e5e1bdd1b533bcf..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.hmm.poisson.poisson_hmm.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.hmm.poisson.poisson\_hmm module -======================================= - -.. automodule:: apollon.hmm.poisson.poisson_hmm - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.hmm.poisson.rst b/docs/source/reference/apollon.hmm.poisson.rst deleted file mode 100644 index 35231b2491b271a3fb99f5f1ceed3e047b0172f8..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.hmm.poisson.rst +++ /dev/null @@ -1,16 +0,0 @@ -apollon.hmm.poisson package -=========================== - -.. automodule:: apollon.hmm.poisson - :members: - :undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - apollon.hmm.poisson.poisson_core - apollon.hmm.poisson.poisson_hmm - diff --git a/docs/source/reference/apollon.hmm.rst b/docs/source/reference/apollon.hmm.rst deleted file mode 100644 index 963eaab8eb14494a6f47468856d9dcfe0f413e63..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.hmm.rst +++ /dev/null @@ -1,23 +0,0 @@ -apollon.hmm package -=================== - -.. automodule:: apollon.hmm - :members: - :undoc-members: - :show-inheritance: - -Subpackages ------------ - -.. toctree:: - - apollon.hmm.graph - apollon.hmm.poisson - -Submodules ----------- - -.. toctree:: - - apollon.hmm.hmm_utilities - diff --git a/docs/source/reference/apollon.io.rst b/docs/source/reference/apollon.io.rst deleted file mode 100644 index b888376390ef920ecb3d1a10e12699199f380417..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.io.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.io module -================= - -.. automodule:: apollon.io - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.onsets.rst b/docs/source/reference/apollon.onsets.rst deleted file mode 100644 index 7aa82bb90e7fda362cbbcc567191456fb5b54d82..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.onsets.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.onsets module -===================== - -.. automodule:: apollon.onsets - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.rst b/docs/source/reference/apollon.rst deleted file mode 100644 index 22613bb8a73716ec5ec1033227db1e42005e808c..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.rst +++ /dev/null @@ -1,34 +0,0 @@ -apollon package -=============== - -.. automodule:: apollon - :members: - :undoc-members: - :show-inheritance: - -Subpackages ------------ - -.. toctree:: - - apollon.commands - apollon.hmm - apollon.signal - apollon.som - -Submodules ----------- - -.. toctree:: - - apollon.analyses - apollon.aplot - apollon.audio - apollon.datasets - apollon.fractal - apollon.io - apollon.onsets - apollon.segment - apollon.tools - apollon.types - diff --git a/docs/source/reference/apollon.segment.rst b/docs/source/reference/apollon.segment.rst deleted file mode 100644 index 938324d4d44bfe566e3da5dc89d866178655ed83..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.segment.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.segment module -====================== - -.. automodule:: apollon.segment - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.signal.critical_bands.rst b/docs/source/reference/apollon.signal.critical_bands.rst deleted file mode 100644 index af36c5ae335c8743238e588fc7933fa3b1f8fde0..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.signal.critical_bands.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.signal.critical\_bands module -===================================== - -.. automodule:: apollon.signal.critical_bands - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.signal.features.rst b/docs/source/reference/apollon.signal.features.rst deleted file mode 100644 index 354c9c30bbb197fdb384bf97ec4ce56a058ba554..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.signal.features.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.signal.features module -============================== - -.. automodule:: apollon.signal.features - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.signal.filter.rst b/docs/source/reference/apollon.signal.filter.rst deleted file mode 100644 index fbaaee915cbb56bd3c3a200e0a6869c917a477dd..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.signal.filter.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.signal.filter module -============================ - -.. automodule:: apollon.signal.filter - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.signal.rst b/docs/source/reference/apollon.signal.rst deleted file mode 100644 index 32fcbab0acd1bf603c42c1edf1b4a038d486514a..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.signal.rst +++ /dev/null @@ -1,19 +0,0 @@ -apollon.signal package -====================== - -.. automodule:: apollon.signal - :members: - :undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - apollon.signal.critical_bands - apollon.signal.features - apollon.signal.filter - apollon.signal.spectral - apollon.signal.tools - diff --git a/docs/source/reference/apollon.signal.spectral.rst b/docs/source/reference/apollon.signal.spectral.rst deleted file mode 100644 index f398387c2c4f467053b3df29f9cff157781cd182..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.signal.spectral.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.signal.spectral module -============================== - -.. automodule:: apollon.signal.spectral - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.signal.tools.rst b/docs/source/reference/apollon.signal.tools.rst deleted file mode 100644 index b2fc3fb813bdbd3e78657cda9bca09ff4fc46816..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.signal.tools.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.signal.tools module -=========================== - -.. automodule:: apollon.signal.tools - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.som.defaults.rst b/docs/source/reference/apollon.som.defaults.rst deleted file mode 100644 index 2fe2ffcab44035b0caef2d8d77d0c00886a748ad..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.som.defaults.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.som.defaults module -=========================== - -.. automodule:: apollon.som.defaults - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.som.rst b/docs/source/reference/apollon.som.rst deleted file mode 100644 index ec8deb1a5178d0699cf56ee66ff09b9e4907dbbf..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.som.rst +++ /dev/null @@ -1,18 +0,0 @@ -apollon.som package -=================== - -.. automodule:: apollon.som - :members: - :undoc-members: - :show-inheritance: - -Submodules ----------- - -.. toctree:: - - apollon.som.defaults - apollon.som.som - apollon.som.topologies - apollon.som.utilities - diff --git a/docs/source/reference/apollon.som.som.rst b/docs/source/reference/apollon.som.som.rst deleted file mode 100644 index cae42e9208112dde5c2b69d726a11f29fa2c1b36..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.som.som.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.som.som module -====================== - -.. automodule:: apollon.som.som - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.som.topologies.rst b/docs/source/reference/apollon.som.topologies.rst deleted file mode 100644 index 800f123376fe4dd367a4a42e4bb003715631ff60..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.som.topologies.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.som.topologies module -============================= - -.. automodule:: apollon.som.topologies - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.som.utilities.rst b/docs/source/reference/apollon.som.utilities.rst deleted file mode 100644 index 16f42c75cfb45d5b0ca011703b1d1e838bd4f0dc..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.som.utilities.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.som.utilities module -============================ - -.. automodule:: apollon.som.utilities - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.tools.rst b/docs/source/reference/apollon.tools.rst deleted file mode 100644 index ac6d46ab5c0e40d396f3a4d342ed680c467a5276..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.tools.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.tools module -==================== - -.. automodule:: apollon.tools - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/apollon.types.rst b/docs/source/reference/apollon.types.rst deleted file mode 100644 index 19c2581e82361fb7c976e08e13214d0ae0965fc0..0000000000000000000000000000000000000000 --- a/docs/source/reference/apollon.types.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon.types module -==================== - -.. automodule:: apollon.types - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/source/reference/modules.rst b/docs/source/reference/modules.rst deleted file mode 100644 index 52f8518a5f1f5ea33c6deb067f688dab9161fae3..0000000000000000000000000000000000000000 --- a/docs/source/reference/modules.rst +++ /dev/null @@ -1,7 +0,0 @@ -apollon -======= - -.. toctree:: - :maxdepth: 4 - - apollon diff --git a/docs/source/starters.rst b/docs/source/starters.rst deleted file mode 100644 index e6b01928d957ae5c8ccf0b2d6b376a520cb9bc1e..0000000000000000000000000000000000000000 --- a/docs/source/starters.rst +++ /dev/null @@ -1,14 +0,0 @@ -Starters -======== - -1. Audio Feature Extraction ----------------------------- -Extract some of the most common low-level audio feauters. - -2. Hidden Markov Model ------------------------ -Estimate Poisson-distributed Hidden Markov Models. - -3. Self-Organizing Map ------------------------ -Train some Self-organizing maps. diff --git a/setup.cfg b/setup.cfg index b21e4deeb335aa0f3af6ddf74341376d4a5aa581..205080e369831ccd6ad60cddfd177343ab915428 100644 --- a/setup.cfg +++ b/setup.cfg @@ -40,6 +40,7 @@ install_requires = matplotlib >= "2" pandas >= "0.20" soundfile >= "0.10.2" + chainsaddiction @ git+https://gitlab.rrz.uni-hamburg.de/bal7668/chainsaddiction.git [options.packages.find] where = src diff --git a/src/apollon/aplot.py b/src/apollon/aplot.py index e91664914c4128fe6afd42c02e55b8ffc3f2813e..baed8592c9bd0cdc9bc38d1434d3794d43366965 100644 --- a/src/apollon/aplot.py +++ b/src/apollon/aplot.py @@ -124,7 +124,7 @@ def _new_axis_3d(fig: MplFig = None, **kwargs) -> tuple: def signal(values: _Array, fps: int = None, **kwargs) -> tuple: """Plot time series with constant sampling interval. - Params: + Args: values: Values of the time series. fps: Sampling frequency in samples. time_scale: Seconds or samples. @@ -235,7 +235,7 @@ def marginal_distr(train_data: _Array, state_means: _Array, stat_dist: _Array, b def onsets(sig, ons, **kwargs) -> tuple: """Indicate onsets on a time series. - Parmas: + Args: sig: Input to onset detection. ons: Onset detector instance. diff --git a/src/apollon/audio.py b/src/apollon/audio.py index 03a4537122186166916d25e5c9125dbe180781ba..2e1bb969584b3de66c0e1cb63b8681e6600cc0eb 100644 --- a/src/apollon/audio.py +++ b/src/apollon/audio.py @@ -25,6 +25,7 @@ class AudioFile: """Representation of an audio file.""" def __init__(self, path: PathType) -> None: """Load an audio file. + Args: path: Path to file. """ @@ -140,7 +141,7 @@ class AudioFile: def fti16(inp: Array) -> Array: """Cast audio loaded as float to int16. - Params: + Args: inp: Input array of dtype float64. Returns: diff --git a/src/apollon/segment.py b/src/apollon/segment.py index 705ad14338a2b58a4f8761d667c9b4338ab89ed4..c536ac7b6e60bd319c9245e9310b6e034b5e6580 100644 --- a/src/apollon/segment.py +++ b/src/apollon/segment.py @@ -197,7 +197,7 @@ class Segmentation: data: Input array. Returns: - ``Segments` object. + ``Segments`` object. """ self._validate_data_shape(data) self._validate_nps(data.shape[0]) diff --git a/src/apollon/signal/features.py b/src/apollon/signal/features.py index eb4022a3c058ea043bd8ce4066578d7e6920194e..fe3f79637905f2aebfa79b14ddc192b7cb3602ae 100644 --- a/src/apollon/signal/features.py +++ b/src/apollon/signal/features.py @@ -1,25 +1,14 @@ -"""apollon/signal/features.py -- Feature extraction routines -Licensed under the terms of the BSD-3-Clause license. -Copyright (C) 2019 Michael Blaß -mblass@posteo.net - -Functions: - cdim Fractal correlation dimension. - correlogram Windowed auto-correlation. - energy Total signal energy. - rms Root mean square. - spectral_centroid - spectral_spread - spectral_flux - spl - splc - loudness - sharpness - roughness +""" +Audio feature extraction routines. + +| Licensed under the terms of the BSD-3-Clause license. +| Copyright (C) 2019 Michael Blaß +| mblass[at]posteo[dot]net """ import numpy as _np from scipy.signal import hilbert as _hilbert +from typing import Optional import _features from . import tools as _sigtools @@ -34,7 +23,16 @@ from .. import _defaults def cdim(inp: _Array, delay: int, m_dim: int, n_bins: int = 1000, scaling_size: int = 10, mode: str = 'bader') -> _Array: # pylint: disable = too-many-arguments - """Compute an estimate of the correlation dimension of the input data. + r"""Compute an estimate of the correlation dimension ``inp``. + + This function implements the Grassberger-Procaccia algorithm + [Grassberger1983]_ to compute the correlation sum + + .. math:: + \hat C(r) = \frac{2} {N(n-1)} \sum_{i<j} + \Theta (r - | \boldsymbol{x}_i - \boldsymbol{x}_j) + + from a time delay embedding of ``inp``. If ``mode`` is set to 'bader', the input array must have at least 2400 elements. Otherwise, the result is undefined. @@ -45,13 +43,14 @@ def cdim(inp: _Array, delay: int, m_dim: int, n_bins: int = 1000, m_dim: Number of embedding dimensions. n_bins: Number of bins. mode: Use either 'bader' for the original algorithm - or 'blass' for the refined version. Returns: Array of correlation dimension estimates. Raises: ValueError + + .. [Grassberger1983] P. Grassberger, and I. Procaccia, "Measuring the strangeness of strange attractors," *Physica 9d*, pp. 189-208. """ if inp.ndim != 2: raise ValueError(f'Input array must be two-dimensional.') @@ -75,19 +74,34 @@ def cdim(inp: _Array, delay: int, m_dim: int, n_bins: int = 1000, def correlogram(inp: _Array, wlen: int, n_delay: int, total: bool = False) -> _Array: - """Windowed autocorrelation of ``inp``. + r"""Windowed autocorrelation of ``inp``. + + This function estimates autocorrelation functions between ``wlen``-sized + windows of the input, separated by ``n_delay`` samples [Granqvist2003]_ . + The autocorrelation :math:`r_{m, n}` is given by + + .. math:: + r_{m, n} = \frac{ \sum_{k=m}^{m+w-1} (x_k- \overline x_m)(x_{k+m}- + \overline x_{m+n})} + {\sqrt{\sum_{k=m}^{m+w-1}(x_k - \overline x_m)^2 + \sum_{k=m}^{m+w-1}(x_{k+n} - \overline x_{m+n})^2}} \,, - This function computes the autocorrelation of a ``wlen``-sized - window of the input. + where :math:`x_m` is + + .. math:: + x_m=\frac{\sum_{i=m}^{m+w-1} x_i}{w} \,. Args: inp: One-dimensional input signal. wlen: Length of the autocorrelation window. n_delay: Number of delay. + total: Sum the correlogram along its first axis. Returns: Two-dimensional array in which each column is an auto-correlation function. + + .. [Granqvist2003] S. Granqvist, B. Hammarberg, "The correlogram: a visual display of periodicity," *JASA,* 114, pp. 2934. """ if not isinstance(inp, _np.ndarray): raise TypeError(f'Argument ``inp`` is of type {type(inp)}. It has ' @@ -119,7 +133,7 @@ def energy(sig: _Array) -> _Array: def frms(bins: _Array, n_sig: int, window: str = None) -> _Array: - """Root meann square of signal energy estimate in the specrtal domain. + """Root meann square of signal energy estimate in the spectral domain. Args: bins: DFT bins. @@ -152,52 +166,55 @@ def rms(sig: _Array) -> _Array: return _np.sqrt(_np.mean(_np.square(_np.abs(sig)), axis=0, keepdims=True)) -def spectral_centroid(frqs: _Array, bins: _Array) -> _Array: - """Estimate the spectral centroid frequency. +def spectral_centroid(frqs: _Array, amps: _Array) -> _Array: + r"""Estimate the spectral centroid frequency. - Spectral centroid is always computed along the second axis of ``bins``. + Spectral centroid is always computed along the second axis of ``amps``. Args: - frqs: Nx1 array of DFT frequencies. - power: NxM array of DFT bin values. + frqs: Nx1 array of DFT frequencies. + amps: NxM array of absolute values of DFT bins. Returns: 1xM array of spectral centroids. - """ - return tools.fsum(frqs*_power_distr(bins), axis=0, keepdims=True) + Note: + The spectral centroid frequency :math:`f_C` is computed as + the expectation of a spectral distribution: -def spectral_flux(inp: _Array, delta: float = 1.0, total: bool = True - ) -> _Array: - """Estimate the spectral flux + .. math:: + f_C = \sum_{i=0}^{N} f_i p(i) \,, - Args: - inp: Input data. Each row is assumend FFT bins. - delta: Sample spacing. - - Returns: - Array of Spectral flux. + where :math:`f_i` is the center frequency, and :math:`p(i)` the + relative amplitude of the :math:`i` th DFT bin. """ - inp = _np.atleast_2d(inp).astype('float64') - out = _np.maximum(_np.gradient(inp, delta, axis=-1), 0) - if total: - return out.sum(axis=0, keepdims=True) - return out + return tools.fsum(frqs*_power_distr(amps), axis=0, keepdims=True) -def spectral_spread(frqs: _Array, bins: _Array, centroids: _Array=None) -> _Array: +def spectral_spread(frqs: _Array, bins: _Array, + centroids: Optional[_Array] = None) -> _Array: """Estimate spectral spread. - Spectral spread is always computed along the second axis of ``bins``. + Spectral Spread is always computed along the second axis of ``bins``. This function computes the square roote of spectral spread. Args: - frqs: Nx1 array of DFT frequencies. - power: NxM array of DFT bin values. + frqs: Nx1 array of DFT frequencies. + bins: NxM array of DFT bin values. centroids: Array Spectral Centroid values. Returns: Square root of spectral spread. + + Note: + Spectral Spread :math:`f_s` is computed as + + .. math:: + f_S = \sum_{i=0}^N (f_i - f_C)^2 p(i) \,, + + where :math:`f_i` is the center frequency, and :math:`p(i)` the + relative amplitude of the :math:`i` th DFT bin. :math:`f_C` is the + spectral centroid frequency. """ if centroids is None: centroids = spectral_centroid(frqs, bins) @@ -206,6 +223,87 @@ def spectral_spread(frqs: _Array, bins: _Array, centroids: _Array=None) -> _Arra keepdims=True)) +def spectral_skewness(frqs: _Array, bins: _Array, + centroid: Optional[_Array] = None, + spreads: Optional[_Array] = None) -> _Array: + r"""Estimate the spectral skewness. + + Args: + frqs: Frequency array. + bins: Absolute values of DFT bins. + centroids: Precomputed spectral centroids. + spreads: Precomputed spectral spreads. + + Returns: + Array of spectral skewness values. + + Note: + The spectral skewness :math:`S_S` is calculated by + + .. math:: + S_{K} = \sum_{i=0}^N \frac{(f_i-f_C)^3}{\sigma^3} p(i) \,, + + where :math:`f_i` is the center frequency, and :math:`p(i)` the + relative amplitude of the :math:`i` th DFT bin. :math:`f_C` is the + spectral centroid frequency, and :math:`\sigma = \sqrt{f_S}.` + """ + pass + +def spectral_kurtosis(frqs: _Array, bins: _Array, + centroid: Optional[_Array] = None, + spreads: Optional[_Array] = None) -> _Array: + r"""Estimate spectral kurtosis. + + Args: + frqs: Frequency array. + bins: Absolute values of DFT bins. + centroids: Precomputed spectral centroids. + spreads: Precomputed spectral spreads. + + Returns: + Array of spectral skewness values. + + Note: + Spectral kurtosis is calculated by + + .. math:: + S_{K} = \sum_{i=0}^N \frac{(f_i-f_c)^4}{\sigma^4} p(i) \,, + + where :math:`f_i` is the center frequency, and :math:`p(i)` the + relative amplitude of the :math:`i` th DFT bin. :math:`f_C` is the + spectral centroid frequency, and :math:`\sigma = \sqrt{f_S}.` + """ + pass + + +def spectral_flux(inp: _Array, delta: float = 1.0, + total: bool = True) -> _Array: + r"""Estimate the spectral flux + + Args: + inp: Input data. Each row is assumend DFT bins. + delta: Sample spacing. + total: Accumulate over first axis. + + Returns: + Array of Spectral flux. + + Note: + Spextral flux is computed by + + .. math:: + SF(i) = \sum_{j=0}^k H(|X_{i,j}| - |X_{i-1,j}|) \,, + + where :math:`X_{i,j}` is the :math:`j` th frequency bin of the :math:`i` + th spectrum :math:`X` of a spectrogram :math:`\boldsymbol X`. + """ + inp = _np.atleast_2d(inp).astype('float64') + out = _np.maximum(_np.gradient(inp, delta, axis=-1), 0) + if total: + return out.sum(axis=0, keepdims=True) + return out + + def fspl(amps: _Array, total: bool = False, ref: float = None) -> _Array: """Computes sound pressure level from spectrum. diff --git a/src/apollon/signal/tools.py b/src/apollon/signal/tools.py index 38418d908871ec1e9643b60efabde95751d82eb8..218c9f7863491308c2b9466359b0cd973e1fae6d 100644 --- a/src/apollon/signal/tools.py +++ b/src/apollon/signal/tools.py @@ -215,9 +215,9 @@ def sinusoid(frqs: Union[Sequence, Array, int, float], Args: frqs: Component frequencies. - amps: Amplitude of each component in ``frqs``. If ``amps`` is an + amps: Amplitude of each component in ``frqs``. If ``amps`` is an integer, each component of ``frqs`` is scaled according to - ``amps``. If ``amps` iis an iterable each frequency is scaled + ``amps``. If ``amps`` iis an iterable each frequency is scaled by the respective amplitude. fps: Sample rate. length: Length of signal in seconds. diff --git a/src/apollon/som/utilities.py b/src/apollon/som/utilities.py index df97a0c2b94adaa0a8cf1dd95f60015fbc5957ec..cdd71878b1a31454d8f47192f3c4a1171a3b41dd 100644 --- a/src/apollon/som/utilities.py +++ b/src/apollon/som/utilities.py @@ -190,7 +190,7 @@ def sample_stm(dims: SomDims, data: Optional[Array] = None, **kwargs) -> Array: Notes: Each row of the output array is to be considered a flattened stochastic matrix, such that each ``N = sqrt(data.shape[1])`` values - are a discrete probability distribution forming the ``N``th row of + are a discrete probability distribution forming the ``N`` th row of the matrix. """ n_rows, n_cols, n_feats = dims diff --git a/src/apollon/tools.py b/src/apollon/tools.py index f7cf50569b946f20d5c050bd63f4a1409b946e07..34b2963603877a00500332b2357797e2456181e8 100644 --- a/src/apollon/tools.py +++ b/src/apollon/tools.py @@ -1,26 +1,12 @@ -"""apollon/tools.py -- Common tool library. +""" +Common tool library. Licensed under the terms of the BSD-3-Clause license. + Copyright (C) 2019 Michael Blaß -mblass@posteo.net - -Functions: - assert_array Raise if array does not match given params. - L1_Norm Compute L1_Norm. - normalize Return _normalized version of input. - in2out Create a save from an input path. - offdiag Access to off-diagonal elements of square array. - rowdiag kth array diagonal sorted by array's rows. - scale Scale array between bounds. - smooth_stat Return smoothed input. - standardize Scale to zero mean and unit standard deviation. - time_stamp Return time stamp. - within Test wether val is in window. - within_any Test wether val is in any of windows. - array2d_fsum Sum array entry with machine precision. """ from datetime import datetime, timezone import math as _math -from typing import Any, Tuple +from typing import Any, Tuple, Callable import numpy as np @@ -58,11 +44,11 @@ def assert_array(arr: Array, ndim: int, size: int, # pylint: disable=R0913 """Raise an error if shape of `arr` does not match given arguments. Args: - arr (np.ndarray) Array to test. - ndim (int) Expected number of dimensions. - size (int) Expected total number of elements. - lower_bound (float) Lower bound for array elements. - upper_bound (float) Upper bound for array elements. + arr: Array to test. + ndim: Expected number of dimensions. + size: Expected total number of elements. + lower_bound: Lower bound for array elements. + upper_bound: Upper bound for array elements. Raises: ValueError @@ -123,17 +109,17 @@ def L1_Norm(arr: Array) -> float: return np.abs(arr).sum(axis=0) -def normalize(arr, mode='array'): +def normalize(arr: Array, mode: str = 'array'): """Normalize an arbitrary array_like. - Params: - arr (numerical array-like) Input signal. - axis (str) Normalization mode: + Args: + arr: Input signal. + mode: Normalization mode: 'array' -> (default) Normalize whole array. 'rows' -> Normalize each row separately. 'cols' -> Normalize each col separately. Return: - (array) Normalized input. + Normalized input. """ arr = np.atleast_1d(arr) @@ -151,70 +137,80 @@ def normalize(arr, mode='array'): # TODO: This normalizes in [0, 1]; for audio we need [-1, 1] -def _normalize(arr): +def _normalize(arr: Array) -> Array: """Normalize array.""" arr_min = arr.min() arr_max = arr.max() return (arr - arr_min) / (arr_max - arr_min) -def assert_and_pass(assert_func, arg): - """Call `assert_func` with `arg` and return `arg`. Additionally allow arg to be None.""" +def assert_and_pass(func: Callable, arg: Any): + """Call ``func``` with ``arg`` and return ``arg``. Additionally allow arg + to be ``None``. + + Args: + func: Test function. + arg: Function argument. + + Returns: + Result of ``func(arg)``. + """ if arg is not None: - assert_func(arg) + func(arg) return arg -def rowdiag(v, k=0): - """Get or set k'th diagonal of square matrix. +def rowdiag(arr: Array, k: int = 0) -> Array: + """Get or set ``k`` th diagonal of square matrix. - Get the k'th diagonal of a square matrix sorted by rows - or construct a sqare matrix with the elements of v as the - main diagonal of the second and third dimension. + Get the ``k`` th diagonal of a square matrix sorted by rows or construct a + sqare matrix with the elements of v as the main diagonal of the second and + third dimension. - Params: - v (array) Square matrix. - k (int) Number diagonal. + Args: + arr: Square array. + k: Number of diagonal. - Return: - (1d-array) Values of diagonal. + Returns: + Flattened diagonal. """ - return np.diag(v, k)[:, None] + return np.diag(arr, k)[:, None] -def scale(x, new_min=0, new_max=1, axis=-1): - """Scale `x` between `new_min` and `new_max`. +def scale(arr: Array, new_min: int = 0, new_max: int = 1, axis: int = -1 + ) -> Array: + """Scale ``arr`` between ``new_min`` and ``new_max``. - Parmas: - x (np.array) Array to be scaled. - new_min (real numerical) Lower bound. - new_max (real numerical) Upper bound. + Args: + arr: Array to be scaled. + new_min: Lower bound. + new_max: Upper bound. Return: - (np.ndarray) One-dimensional array of transformed values. + One-dimensional array of transformed values. """ - xmax = x.max(axis=axis, keepdims=True) - xmin = x.min(axis=axis, keepdims=True) + xmax = arr.max(axis=axis, keepdims=True) + xmin = arr.min(axis=axis, keepdims=True) - a = (x-xmin) / (xmax - xmin) - y = a * (new_max - new_min) + new_min + fact = (arr-xmin) / (xmax - xmin) + out = fact * (new_max - new_min) + new_min - return y + return out -def smooth_stat(sig): +def smooth_stat(arr: Array) -> Array: """Smooth the signal based on its mean and standard deviation. - Params: - sig (array-like) Input signal. + Args: + arr: Input signal. - Return: - (ndarray) smoothed input signal. + Returns: + smoothed input signal. """ out = [] - sig_mean = sig.mean() - sig_std = sig.std() - for i in sig: + sig_mean = arr.mean() + sig_std = arr.std() + for i in arr: if i < sig_mean - sig_std or i > sig_mean + sig_std: out.append(i) else: @@ -223,16 +219,17 @@ def smooth_stat(sig): return np.array(out) -def standardize(x: np.ndarray) -> np.ndarray: - """Retrun z-transformed values of x. +def standardize(arr: Array) -> Array: + """Retrun z-transformed values of ``arr``. - Params: - x (array) Input values + Args: + arr: Input array. - Return: - (array) z-transformed values + Returns: + z-transformed values """ - return (x - x.mean(axis=0)) / x.std(axis=0) + return (arr - arr.mean(axis=0)) / arr.std(axis=0) + def time_stamp(fmt: str = None) -> str: """Report call time as UTC time stamp. @@ -251,24 +248,31 @@ def time_stamp(fmt: str = None) -> str: return tsp.isoformat() return tsp.strftime(fmt) + def within(val: float, bounds: Tuple[float, float]) -> bool: """Return True if x is in window. Args: - val (float) Value to test. + val: Value to test. - Retrns: - (bool) True if ``val`` is within ``bounds``. + Returns: + ``True``, if ``val`` is within ``bounds``. """ return bounds[0] <= val <= bounds[1] def within_any(val: float, windows: Array) -> bool: - """Return True if x is in any of the given windows""" + """Return True if x is in any of the given windows. + + Args: + val: Value to test. + windows: Array of bounds. + + Returns: + """ a = windows[:, 0] <= val b = val <= windows[:, 1] c = np.logical_and(a, b) - return np.any(c) @@ -302,4 +306,3 @@ def fsum(arr: Array, axis: int = None, keepdims: bool = False, else: raise ValueError(f'``Axis is {axis} but must be 0, 1, or ``None``.') return out -