.. _mathematics:

######################################
A mathematics module for the scripting
######################################

:Last update: 
    2/06/14


.. Description                                                              {{{1
.. _description:

***********
Description 
***********

The module `mathematics.py` provides useful functions and a class to do basic
mathematics with Python/Jython lists and tuples. 


.. Useful functions                                                              {{{1
.. _useful-functions:

****************
Useful functions
****************

* Convert FWHM to :math:`\sigma`::

  >>> sigma = fwhmToSigma(fwhm)
  
* Convert :math:`\sigma` to FWHM::

  >>> fwhm = sigmatoFwhm(sigma)
  
* Create an evenly spaced numbers over a specified interval

The general syntax is::

    >>> numbers = linspace(start, stop, num=num, endpoint=endpoint, retstep=retstep)

* Generate the values between 1 and 10 (the default number of values is 50)::

    >>> print linspace(1, 10)
    [1.0, 1.183673469387755, 1.3673469387755102,..., 10]

* Generate the 10 values between 1 and 10::
  
    >>> print linspace(1, 10, num=10)
    [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]

* Generate the 10 values between 1 and 10 but don't include the end point::

    >>> print linspace(1, 10, num=10, endpoint=False)
    [1.0, 1.9, 2.8, 3.7, 4.6, 5.5, 6.4, 7.3, 8.2, 9.1]

* Generate the values between 1 and 10 and return the step::

    >>> print linspace(1, 10, retstep=True)
    ([1.0, 1.183673469387755, 1.3673469387755102,..., 10], 0.1836734693877551)


.. The Array class                                                          {{{1
.. _the-array-class:

***************
The Array class
***************

 As CASSIS uses Jython as a scripting language (Python implemented in Java),
 libraries like `numpy` are not available in Jython. The class `Array` in
 `mathematics.py` aims to provide some useful equivalent functionalities for
 1-dimension arrays such as:

* operations on the array
* selection of indexes
* basic statistical functions
* plotting

The class `Array` roughly emulates `numpy.array` for 1-dimensional arrays::

    >>> from mathematics import Array


.. Creation of an array                                              {{{1
.. _creation-of-an-array:

Creation of an array
********************

You can create an empty Array instance by specifying a number of values::

    >>> emptyArray = Array(100)

or create it from an iterable::

    >>> a = Array([1, 2, 3, 4])


.. Operations on the array                                              {{{1
.. _operations-on-the-array:

Operations on the array
***********************

Operations on the array can be performed with scalars or other arrays.

Mathematical operators
----------------------

Basic mathematical operators are available: 

* addition
* subtraction
* multiplication
* division
* power
* modulo

Example::

    >>> print a + 42
    [43 44 45 56]

    # Another array
    >>> b = Array([-20, 17, 3, 67])

    >>> print a+b
    [-19 19 6 71]

    >>> print a**2
    [1 4 9 16]

    >>> print a % 2
    [1 0 1 0]


Logical operators
-----------------

The available logical operators are: 

* `>`
* `>=`
* `<`
* `<=`
* `==`
* `!=` (different)

Example::

    >>> print a > 2
    [0 0 1 1]

    >>> print a > b
    [1 0 0 0]


Accessing the values in the array
*********************************

You can access any value in the array like you would do for a Python `list`.

* You can select a single index::

    >>> print a[0] 
    1

* Or a range of indexes::

    >>> print a[0:2]
    [1 2]

* You can set a new index::

    >>> a[0] = 10
    >>> print a
    [10 2 3 4]

* Or a range of indexes::
    >>> a[0:2] = 10
    >>> print a
    [10 10 3 4]
    >>> a[0:2] = 100, 200
    >>> print a
    [100 200 3 4]


`Array` also allows a more advanced way of accessing the values by specifying 
a condition on the array.

* Select all the positive values in b::

    >>> print b[b > 0]
    [17 3 67]

* Select all the even values in a::

    >>> print a[b % 2 == 0]
    [2 4]

.. note:: Compound conditions are supported yet.


Basic statistical functions
***************************

The `Array` instance provides its own statistical functions:

* mean
* median
* std
* min
* max
* sum
* cumsum (the cumulative sum)

Examples::

    >>> print a.sum()
    10
    
    >>> print a.mean()
    2.5
    
    >>> print a.cumsum()
    [1 3 6 10]
    

.. Plotting                                                              {{{1
.. _plotting:

Plotting
********

You can plot the values stored in the `Array` instance with the `plot` method::

    >>> # y is an Array whose values are the intensity of a spectrum
    >>> y.plot(title="CO line")

plots the following graph

.. image:: _static/images/spectrum.png

(the indexes of the array are represented on the x axis.)

.. note:: You can use all the available optional keywords that you would use
    with the :ref:`Plot class <plot>`.