Commit 2ba81264 authored by Ronan Hamon's avatar Ronan Hamon

Add release 1.0

parents
Pipeline #452 passed with stage
in 36 seconds
[run]
branch = True
source = madarrays
include = */madarrays/*
omit =
*/setup.py
*/__init__.py
*/test_*
[report]
exclude_lines =
pragma: no cover
if self.debug:
if settings.DEBUG
raise AssertionError
raise NotImplementedError
if 0:
if __name__ == .__main__.:
if obj is None: return
if verbose > 0:
if self.verbose > 0:
if verbose > 1:
if self.verbose > 1:
pass
def __str__(self):
*.py[co]
# Packages
*.egg
*.egg-info
dist
build
eggs
parts
bin
var
sdist
develop-eggs
.installed.cfg
# Installer logs
pip-log.txt
# Mac OS X files
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
# Sphinx stuff
docs/generated/
docs/build/
# jupyter notebook
.ipynb_checkpoints
# coverage
htmlcov
.coverage
# ide
.idea
.spyderproject
# run the test suite
tests_old_ubuntu:
image: registry.gitlab.lis-lab.fr:5005/skmad-suite/madarrays/ubuntu:16.04
tags:
- docker
script:
- pip3 install . --no-deps
- pytest
tests_new_ubuntu:
image: registry.gitlab.lis-lab.fr:5005/skmad-suite/madarrays/ubuntu:rolling
tags:
- docker
script:
- pip3 install . --no-deps
- pytest-3
# generate the documentation
pages:
image: registry.gitlab.lis-lab.fr:5005/skmad-suite/madarrays/ubuntu:rolling
tags:
- docker
only:
- master
script:
- pip3 install . --no-deps
- python3 setup.py build_sphinx
- cp -r build/sphinx/html public
artifacts:
paths:
- public
This diff is collapsed.
include *.txt
include *.rst
include VERSION
recursive-include doc *.rst *.py
include madarrays/tests/*.py
prune doc/build
MadArrays
=========
MadArrays is a Python package that regroups various data structures adapted to
handle audio signals with missing data.
Install
-------
Install the current release with ``pip``::
pip install madarrays
For additional details, see doc/install.rst.
Usage
-----
See the `documentation <http://skmad-suite.pages.lis-lab.fr/madarrays/>`_.
Bugs
----
Please report any bugs that you find through the `MadArrays GitLab project
<https://gitlab.lis-lab.fr/skmad-suite/madarrays/issues>`_.
You can also fork the repository and create a merge request.
Source code
-----------
The source code of MadArrays is available via its `GitLab project
<https://gitlab.lis-lab.fr/skmad-suite/madarrays>`_.
You can clone the git repository of the project using the command::
git clone git@gitlab.lis-lab.fr:skmad-suite/madarrays.git
Copyright © 2017-2018
---------------------
* `Laboratoire d'Informatique et Systèmes <http://www.lis-lab.fr/>`_
* `Université d'Aix-Marseille <http://www.univ-amu.fr/>`_
* `Centre National de la Recherche Scientifique <http://www.cnrs.fr/>`_
* `Université de Toulon <http://www.univ-tln.fr/>`_
Contributors
------------
* `Ronan Hamon <mailto:ronan.hamon@lis-lab.fr>`_
* `Valentin Emiya <mailto:valentin.emiya@lis-lab.fr>`_
License
-------
Released under the GNU General Public License version 3 or later
(see `LICENSE.txt`).
madarrays:1.0
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = python -m sphinx
PAPER =
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest epub
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " pickle to make pickle files"
@echo " epub to make an epub"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " gitwash to update the gitwash documentation"
clean:
-rm -rf build/*
-rm -rf ghpages_build
-rm -rf auto_examples modules
-rm -rf reference/generated reference/algorithms/generated reference/classes/generated reference/readwrite/generated
dist: html
test -d build/latex || make latex
make -C build/latex all-pdf
-rm -rf build/dist
(cd build/html; cp -r . ../../build/dist)
(cd build/dist && tar czf ../dist.tar.gz .)
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
@echo
@echo "Build finished. The HTML pages are in build/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) build/dirhtml
@echo
@echo "Build finished. The HTML pages are in build/dirhtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in build/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in build/qthelp, like this:"
@echo "# qcollectiongenerator build/qthelp/test.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile build/qthelp/test.qhc"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) build/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
@echo
@echo "Build finished; the LaTeX files are in build/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
@echo
@echo "The overview file is in build/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in build/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) build/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in build/doctest/output.txt."
latexpdf: latex
@echo "Running LaTeX files through latexmk..."
$(MAKE) -C build/latex all-pdf
@echo "latexmk finished; the PDF files are in build/latex."
docs: clean html latexpdf
cp build/latex/networkx_reference.pdf build/html/_downloads/.
gitwash-update:
python ../tools/gitwash_dumper.py developer networkx \
--project-url=http://networkx.github.io \
--project-ml-url=http://groups.google.com/group/networkx-discuss/ \
--gitwash-url git@github.com:matthew-brett/gitwash.git
Sphinx is used to generate the API and reference documentation for all
packages from the [`skmad-suite`](https://gitlab.lis-lab.fr/skmad-suite/).
## Instructions to build the documentation
In addition to installing ``madarrays`` and its dependencies, install the
Python packages needed to build the documentation by entering
```
pip install -r ../requirements/doc.txt
```
in the ``doc/`` directory.
To build the HTML documentation, run:
```
make html
```
in the ``doc/`` directory. This will generate a ``build/html`` subdirectory
containing the built documentation.
To build the PDF documentation, run:
```
make latexpdf
```
You will need to have Latex installed for this.
{
"cells": [
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"%pylab inline"
]
},
{
"cell_type": "markdown",
"metadata": {
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"source": [
"# Tutorial on how to use `MadArray` objects\n",
"\n",
"A `MadArray` is a numpy array with missing elements. It is generated using three types of parameter:\n",
"\n",
"* **data** as an array of entries, either *int*, *float* or *complex*;\n",
"* a **mask** indicating the missing entries;\n",
"* **options** to define the behaviour of the object.\n",
"\n",
"A basic initialisation requires only a data matrix. Without mask, all elements are considered as non-missing"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"from madarrays import MadArray\n",
"\n",
"# initialisation without mask\n",
"data = np.random.rand(4, 6)\n",
"\n",
"A = MadArray(data)\n",
"print(A)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Masking\n",
"\n",
"The masking of data differs according to the type of entries:\n",
"\n",
"* if the entries are *int* or *float*, the masking is done exclusively by giving aa boolean array of the same size of the data as argument `mask`, each entry indicating if the corresponding entry in the data array is missing or not\n",
"* if the entries are *complex*, the masking can be done as previously, or by giving boolean arrays of the same size of the data as arguments `mask_amplitude` and `mask_phase`, each entry indicating respectively if the magnitude and the phase of the corresponding entry is missing or not."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"# initialization with a mask\n",
"mask = np.random.random(data.shape) < 0.5\n",
"\n",
"Am = MadArray(data, mask)\n",
"print(mask)\n",
"print(Am)"
]
},
{
"cell_type": "markdown",
"metadata": {
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"source": [
"A *MadArray* can also be defined from another *MadArray*, for example to copy the object:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"Am2 = MadArray(Am)\n",
"print('{} - {}'.format(str(Am), repr(Am)))\n",
"print('{} - {}'.format(str(Am2), repr(Am2)))"
]
},
{
"cell_type": "markdown",
"metadata": {
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"source": [
"A different mask can also be used:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"mask2 = np.random.random(data.shape) < 0.9\n",
"Am3 = MadArray(Am, mask2)\n",
"print('{} - {}'.format(str(Am), repr(Am)))\n",
"print('{} - {}'.format(str(Am3), repr(Am3)))"
]
},
{
"cell_type": "markdown",
"metadata": {
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"source": [
"## Properties\n",
"\n",
"A *MadArray* has attributes that give information about the masking."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"# mask of non-missing elements\n",
"print(Am.known_mask)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"# mask of missing elements\n",
"print(Am.unknown_mask)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"print('Is masked: {}'.format(Am.is_masked))\n",
"print('Ratio missing data: {}'.format(Am.ratio_missing_data))"
]
},
{
"cell_type": "markdown",
"metadata": {
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"source": [
"## Indexing\n",
"\n",
"There are two different and incompatible ways to index *MadArray*. By default (`masked_indexing=False`), it is similar to the indexing of *nd-array*: both the data matrix and the mask are indexed, and a *MadArray* with the shape defined by the indices is returned:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"print(A[0:3, 1:3])\n",
"print(Am[0:3, 1:3])"
]
},
{
"cell_type": "markdown",
"metadata": {
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"source": [
"With the other way (`masked_indexing=True`), a MadArray with the shape unchanged is returned, where non-indexed entries are considered as masked."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"Am4 = MadArray(data, mask, masked_indexing=True)\n",
"print(Am4[0:3, 1:3])"
]
},
{
"cell_type": "markdown",
"metadata": {
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"source": [
"This latter approach is adapted to be handled with *scikit-learn* procedures."
]
},
{
"cell_type": "markdown",
"metadata": {
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"source": [
"## Numerical operations\n",
"Numpy functions apply on *MadArray*, but **without** taking into account the mask \n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"autoscroll": "json-false",
"ein.tags": [
"worksheet-0"
],
"slideshow": {
"slide_type": "-"
}
},
"outputs": [],
"source": [
"print(np.mean(A))\n",
"print(np.mean(Am))"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.6.2"
},
"name": "data_structures.ipynb"
},
"nbformat": 4,
"nbformat_minor": 1
}
This diff is collapsed.
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import sys
import os
from datetime import date
import madarrays
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('../madarrays/'))
# -- General configuration ------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
'sphinx_paramlinks',
'numpydoc',
'nbsphinx',
'IPython.sphinxext.ipython_console_highlighting',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'madarrays'
author = 'V. Emiya and R. Hamon'
copyright = '2017-{}, {}'.format(date.today().year, author)
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = madarrays.__version__
# The full version, including alpha/beta/rc tags.
release = madarrays.__version__.replace('_', '')
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# Else, today_fmt is used as the format for a strftime call.