.. -*- mode: rst -*-
.. |LicenseMIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg
.. _LicenseMIT: https://opensource.org/licenses/MIT
.. |LicenseCC| image:: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg
.. _LicenseCC: https://creativecommons.org/licenses/by/4.0/
.. |Pipeline| image:: https://gitlab.com/aidaspace/aidapy/badges/master/pipeline.svg
.. _Pipeline: https://gitlab.com/aidaspace/aidapy/commits/master
.. |CoverageReport| image:: https://codecov.io/gl/aidaspace/aidapy/branch/master/graph/badge.svg
.. _CoverageReport: https://codecov.io/gl/aidaspace/aidapy
.. |PylintScore| image:: https://aidaspace.gitlab.io/aidapy/pylint.svg
.. _PylintScore: https://gitlab.com/aidaspace/aidapy/commits/master
.. |Maintenance| image:: https://img.shields.io/badge/Maintained%3F-yes-green.svg
.. _Maintenance: https://gitlab.com/aidaspace/aidapy/commits/master
.. |DocSphinx| image:: https://img.shields.io/static/v1.svg?label=sphinx&message=documentation&color=blue
.. _DocSphinx: https://gitlab.com/aidaspace/aidapy/commits/master
.. |PyPi| image:: https://img.shields.io/badge/install_with-pypi-brightgreen.svg
.. _PyPi: https://pypi.org/project/aidapy/
AIDApy
=======
|LicenseMit|_ |LicenseCC|_ |Pipeline|_ |PyPi|_ |CoverageReport|_ |PylintScore|_ |DocSphinx|_ |Maintenance|_
The Python package ``aidapy`` centralizes and simplifies access to:
- Spacecraft data from heliospheric missions
- Space physics simulations
- Advanced statistical tools
- Machine Learning, Deep Learning algorithms, and applications
The ``aidapy`` package is part of the project AIDA (Artificial Intelligence Data Analysis) in Heliophysics funded from
the European Unions Horizon 2020 research and innovation programme under grant agreement No 776262.
It is distributed under the open-source MIT license.
Full documentation can be found `here <https://aidapy.readthedocs.io>`_
.. end-marker-intro-do-not-remove
.. start-marker-install-do-not-remove
Installation
------------
The package aidapy has been tested only for Linux.
Using PyPi
^^^^^^^^^^^^^^^
``aidapy`` is available for pip.
.. code-block:: bash
pip install aidapy
From sources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The sources are located on **GitLab**:
https://gitlab.com/aidaspace/aidapy
1) Clone the GitLab repo:
Open a terminal and write the below command to clone in your PC the
AIDApy repo:
.. code-block:: bash
git clone https://gitlab.com/aidaspace/aidapy.git
cd aidapy
2) Create a virtual env
AIDApy needs a significant number of dependencies. The easiest
way to get everything installed is to use a virtual environment.
- Anaconda
You can create a virtual environment and install all the dependencies using conda_
with the following commands:
.. code-block:: bash
pip install conda
conda create -n aidapy
source activate aidapy
.. _conda: http://conda.io/
- Virtual Env
Virtualenv_ can also be used:
.. code-block:: bash
pip install virtualenv
virtualenv AIDApy
source AIDApy/bin/activate
.. _virtualenv: https://virtualenv.pypa.io/en/latest/#
3) Install the version you want via the commands:
For the "basic" version:
.. code-block:: bash
python setup.py install
For the version with the ML use cases:
.. code-block:: bash
pip install aidapy[ml]
4) Test the installation in your PC by running. (**Install both versions before running the tests**)
.. code-block:: bash
python setup.py test
5) (Optional) Generate the docs: install the extra dependencies of doc and run
the `setup.py` file:
.. code-block:: bash
pip install aidapy[doc]
python setup.py build_sphinx
Once installed, the doc can be generated with:
.. code-block:: bash
cd doc
make html
Dependencies
^^^^^^^^^^^^^
The required dependencies are:
- `Python <https://python.org>`_ >= 3.6
- `scikit-learn <https://scikit-learn.org>`_ >= 0.21
- `numpy <https://www.numpy.org>`_ >= 1.18
- `scipy <https://scipy.org>`_ >= 1.4.1
- `matplotlib <https://matplotlib.org>`_ >= 3.2.1
- `pandas <https://pandas.pydata.org/>`_ >= 1.0.3
- `heliopy <https://github.com/heliopython/heliopy>`_ >= 0.12
- `sunpy <https://docs.sunpy.org/en/stable/>`_ >= 1.1.2
- `astropy <https://www.astropy.org/>`_ >=4.0.1
- `xarray <https://xarray.pydata.org/en/stable/>`_ >=0.15
- `bottleneck <https://pypi.org/project/Bottleneck/>`_ >= 1.3.2
- `heliopy-multid <https://pypi.org/project/heliopy-multid/>`_ >= 0.0.2
Optional dependencies are:
- `pytorch <https://pytorch.org/>`_ >= 1.4
- `skorch <https://github.com/skorch-dev/skorch>`_ >= 0.8.0
Testing dependencies are:
- `pytest <https://docs.pytest.org/en/latest/>`_ >= 2.8
Extra testing dependencies:
- `coverage <https://coverage.readthedocs.io>`_ >= 4.4
- `pylint <https://www.pylint.org>`_ >= 1.6.0
.. end-marker-install-do-not-remove
Usage
--------
AIDApy's high level interface has been created in order to combine
simplicity with workability. In the example below, the end user
downloads data from the MMS space mission for a specific time range and
afterwards extracts the *mean* of these. Finally the timeseries are
ploted in the screen.
.. code:: python
from datetime import datetime
#AIDApy Modules
from aidapy import load_data
###############################################################################
# Define data parameters
###############################################################################
# Time Interval
start_time = datetime(2018, 4, 8, 0, 0, 0)
end_time = datetime(2018, 4, 8, 0, 1, 0)
# Dictionary of data settings: mission, product, probe, coordinates
# Currently available products: 'dc_mag', 'i_dens', and 'all'
settings = {'prod': ['dc_mag'], 'probes': ['1', '2'], 'coords': 'gse'}
###############################################################################
# Download and load desired data as aidapy timeseries
###############################################################################
xr_mms = load_data(mission='mms', start_time=start_time, end_time=end_time, **settings)
###############################################################################
# Extract a Statistical Measurement of the data
###############################################################################
xr_mms['dc_mag1'].statistics.mean()
###############################################################################
# Plot the loaded aidapy timeseries
###############################################################################
xr_mms['dc_mag1'].graphical.peek()
Contributing
------------
Pull requests are welcome. For major changes, please open an issue first
to discuss what you would like to change.
All the code must follow the instructions of STYLEGUIDE.rst. Please make sure to update tests as
appropriate.
Licenses
--------
This software (AIDApy) and the database of the AIDA project (AIDAdb) are
distributed under the `MIT <https://www.gnu.org/licenses/gpl-3.0>`__
license.
The data collections included in the AIDAdb are distributed under the
Creative Commons `CC BT
4.0 <https://creativecommons.org/licenses/by/4.0/>`__ license.
.. |license-mit| image:: https://img.shields.io/badge/License-MIT-yellow.svg
:target: https://opensource.org/licenses/MIT
.. |license-cc| image:: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg
:target: https://creativecommons.org/licenses/by/4.0/
.. |pipeline-status| image:: https://gitlab.com/aidaspace/aidapy/badges/master/pipeline.svg
:target: https://gitlab.com/aidaspace/aidapy/commits/master
.. |coverage-report| image:: https://codecov.io/gl/aidaspace/aidapy/branch/master/graph/badge.svg
:target: https://codecov.io/gl/aidaspace/aidapy
.. |pylint-score| image:: https://aidaspace.gitlab.io/aidapy/pylint.svg
:target: https://gitlab.com/aidaspace/aidapy/commits/master
.. |maintenance-yes| image:: https://img.shields.io/badge/Maintained%3F-yes-green.svg
:target: https://gitlab.com/aidaspace/aidapy/commits/master
.. |doc-sphinx| image:: https://img.shields.io/static/v1.svg?label=sphinx&message=documentation&color=blue
:target: https://gitlab.com/aidaspace/aidapy/commits/master
.. |pypi| image:: https://img.shields.io/badge/install_with-pypi-brightgreen.svg
:target: https://pypi.org/project/aidapy/