diff --git a/README.md b/README.md index 1d6a5c9..5409f5a 100644 --- a/README.md +++ b/README.md @@ -6,4 +6,30 @@ [![Tests](https://github.com/heracles-ec/heracles/actions/workflows/tests.yml/badge.svg)](https://github.com/heracles-ec/heracles/actions/workflows/tests.yml) [![Coverage](https://coveralls.io/repos/github/heracles-ec/heracles/badge.svg?branch=main)](https://coveralls.io/github/heracles-ec/heracles?branch=main) -The _Heracles_ code was developed in the _Euclid_ Science Ground Segment. +This is _Heracles_, a code for harmonic-space statistics on the sphere. +_Heracles_ can take catalogues of positions a function values on the sphere and +turn them into wonderful things like angular power spectra and mixing matrices. + +To get started, read the [documentation](https://heracles.readthedocs.io). + +🛰️ **Made in the Euclid Science Ground Segment** + +## Installation (latest) + +To install the latest released version of the package: + + pip install heracles + +You should do this in a dedicated environment (conda, venv, etc.) + +## Installation (git main) + +To install the latest unreleased version from the git main branch: + + pip install git+https://github.com/heracles-ec/heracles.git + +## Installation (develop) + +Clone the repository, cd into the local copy, then install in editable mode: + + pip install -e . diff --git a/docs/api/catalog.rst b/docs/api/catalog.rst new file mode 100644 index 0000000..58ad432 --- /dev/null +++ b/docs/api/catalog.rst @@ -0,0 +1,31 @@ + +Catalogues +========== + +.. currentmodule:: heracles + + +The catalogue protocol +---------------------- + +.. autoclass:: Catalog + +.. autoclass:: CatalogBase + +.. autoclass:: CatalogPage + + +Catalogue implementations +------------------------- + +.. autoclass:: FitsCatalog + +.. autoclass:: ArrayCatalog + + +Catalogue filters +----------------- + +.. autoclass:: FootprintFilter + +.. autoclass:: InvalidValueFilter diff --git a/docs/api/examples.rst b/docs/api/examples.rst new file mode 100644 index 0000000..0987924 --- /dev/null +++ b/docs/api/examples.rst @@ -0,0 +1,14 @@ +Python examples +=============== + +The best way to get started with the Python interface for *Heracles* is to look +at the example notebooks below. If you want to follow along and run the +examples yourself, the source files are found on in the repository__. + +__ https://github.com/heracles-ec/heracles/blob/main/examples + + +.. toctree:: + :maxdepth: 1 + + ../examples/example.ipynb diff --git a/docs/api/fields.rst b/docs/api/fields.rst new file mode 100644 index 0000000..50e1380 --- /dev/null +++ b/docs/api/fields.rst @@ -0,0 +1,33 @@ + +Fields +====== + +.. currentmodule:: heracles + + +The field protocol +------------------ + +.. autoclass:: Field + + +Mathematical fields +------------------- + +.. autoclass:: ComplexField + +.. autoclass:: ScalarField + +.. autoclass:: Spin2Field + + +Concrete fields +--------------- + +.. autoclass:: Positions + +.. autoclass:: Shears + +.. autoclass:: Visibility + +.. autoclass:: Weights diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..bc006e7 --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,34 @@ + +Using *Heracles* from Python +============================ + +*Heracles* is a fully-featured library for harmonic-space statistics on the +sphere. The Python interface can be used, e.g., in exploratory work using +Jupyter notebooks, or to create automated data processing pipelines for a large +collaboration like *Euclid*. + + +Importing *Heracles* +-------------------- + +To use *Heracles* from Python, it is usually enough to import its main module:: + + import heracles + +The ``heracles`` module contains most user-facing functionality. However, some +of *Heracles*' features require additional external dependencies; these +features are therefore encapsulated in their own separate modules:: + + import heracles.healpy # requires healpy + import heracles.ducc # requires ducc0 + import heracles.notebooks # requires IPython, ipywidgets + import heracles.rich # requires rich + + +Python documentation +-------------------- + +The best way to get started with the Python interface for *Heracles* is to look +at the provided :doc:`/api/examples`. + +The full list of user functionality is documented in the :doc:`/api/reference`. diff --git a/docs/api/reference.rst b/docs/api/reference.rst new file mode 100644 index 0000000..1520256 --- /dev/null +++ b/docs/api/reference.rst @@ -0,0 +1,19 @@ + +Python API reference +==================== + +This is the API reference for using *Heracles* as a Python library. +The documentation is broadly organized into the stages of a data processing +pipeline. + +.. warning:: + + The API documentation is a work in progress. + + +.. toctree:: + :maxdepth: 1 + + catalog + fields + twopoint diff --git a/docs/api/twopoint.rst b/docs/api/twopoint.rst new file mode 100644 index 0000000..b87eebc --- /dev/null +++ b/docs/api/twopoint.rst @@ -0,0 +1,29 @@ + +Two-point statistics +==================== + +.. currentmodule:: heracles + + +Angular power spectra +--------------------- + +.. autofunction:: angular_power_spectra + +.. autofunction:: binned_cls + +.. autofunction:: debias_cls + + +Mixing matrices +--------------- + +.. autofunction:: mixing_matrices + +.. autofunction:: binned_mms + + +Auxiliary functions +------------------- + +.. autofunction:: bin2pt diff --git a/docs/cli/index.rst b/docs/cli/index.rst new file mode 100644 index 0000000..371baa8 --- /dev/null +++ b/docs/cli/index.rst @@ -0,0 +1,6 @@ + +Using the *Heracles* CLI +======================== + +The *Heracles* CLI is functional but currently still unsupported. It will be +fully supported as part of the next *Heracles* release. diff --git a/docs/conf.py b/docs/conf.py index 6b73bcf..df13cf1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -16,7 +16,7 @@ from importlib import metadata -project = "heracles" +project = "Heracles" copyright = "2023-2024 Euclid Science Ground Segment" author = "Euclid Science Ground Segment" version = metadata.version(project) @@ -28,10 +28,11 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - "numpydoc", + "sphinx.ext.napoleon", "sphinx.ext.intersphinx", "sphinxcontrib.katex", "matplotlib.sphinxext.plot_directive", + "nbsphinx", ] intersphinx_mapping = { @@ -55,3 +56,9 @@ html_static_path = ["_static"] html_logo = "_static/logo.png" + + +# -- Options for autodoc ----------------------------------------------------- + +# This value controls how to represent typehints. +autodoc_typehints = "description" diff --git a/docs/examples b/docs/examples new file mode 120000 index 0000000..a6573af --- /dev/null +++ b/docs/examples @@ -0,0 +1 @@ +../examples \ No newline at end of file diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 0000000..6eb6f8b --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,61 @@ +Getting started +=============== + +These are the first steps to get up and running with *Heracles*. First, +install the *Heracles* package for Python using one of the methods described +below. Then, see the documentation on :doc:`/api/index` or :doc:`/cli/index`. + + +Installing a release +-------------------- + +This is the usual way of installing *Heracles*, and should be your first port +of call. + +The *Heracles* package requires Python 3.9+ and a number of dependencies. It +can be installed using `pip` in the usual manner: + +.. code-block:: console + + $ pip install heracles + +This will also install any missing dependencies. + +.. note:: + + As usual, it is recommended to install *Heracles* into a dedicated + environment (conda, venv, etc.). + +For alternative ways to install the package, see `Installing from the +repository`_ and `Developer installation`_. + + +Installing from the repository +------------------------------ + +To install the latest work-in-progress version, install directly from the main +branch of the git repository: + +.. code-block:: console + + $ pip install git+https://github.com/heracles-ec/heracles.git + +This will install *Heracles* with a local version string that encodes the last +release and any subsequent commits. + + +Developer installation +---------------------- + +If you want to install *Heracles* for local development, clone the repository +and install the package in editable mode: + +.. code-block:: console + + $ # clone the repository + $ cd heracles + $ pip install -e . + +The result is similar to `Installing from the repository`_, but uses the local +copy of the repository as the package source. This means changes to your local +files are applied without needing to reinstall the package. diff --git a/docs/index.rst b/docs/index.rst index b915c55..0786002 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,17 +1,43 @@ -****************************************************** *Heracles* --- Harmonic-space statistics on the sphere -****************************************************** +====================================================== .. image:: _static/logo.png :width: 50% -================= +This is *Heracles*, a code for harmonic-space statistics on the sphere. +*Heracles* can take catalogues of positions a function values on the sphere and +turn them into wonderful things like angular power spectra and mixing matrices. + +*Heracles* is both a Python library, to be used in notebooks or data processing +pipelines, and a tool for running measurements from the command line using a +configuration file. To jump right in, see :doc:`/getting-started`, +:doc:`api/index`, and :doc:`/cli/index`. + +🛰️ **Made in the Euclid Science Ground Segment** + + Table of Contents -================= +----------------- + +.. toctree:: + :caption: Heracles + :maxdepth: 2 + + getting-started + publications + releases + +.. toctree:: + :caption: Python interface + :maxdepth: 2 + + api/index + api/examples + api/reference + .. toctree:: + :caption: Command Line Interface :maxdepth: 2 - manual/index - user/index - reference/index + cli/index diff --git a/docs/manual/examples.rst b/docs/manual/examples.rst deleted file mode 100644 index 2eb30fd..0000000 --- a/docs/manual/examples.rst +++ /dev/null @@ -1,6 +0,0 @@ -Examples -======== - -The best way to get started with *Heracles* is to follow the GitHub example__. - -__ https://github.com/heracles-ec/heracles/blob/main/examples/example.ipynb diff --git a/docs/manual/index.rst b/docs/manual/index.rst deleted file mode 100644 index 0fa60b4..0000000 --- a/docs/manual/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -=============== -Software manual -=============== - -.. toctree:: - :maxdepth: 2 - - installation - examples - releases diff --git a/docs/manual/installation.rst b/docs/manual/installation.rst deleted file mode 100644 index 7557af2..0000000 --- a/docs/manual/installation.rst +++ /dev/null @@ -1,18 +0,0 @@ -Installation -============ - -Requirements ------------- - -*Heracles* is auto tested on Python versions 3.8 - 3.12. For now there is no official release so we recommend developer installation only. - - -Developer installation ----------------------- - -If you want to install *Heracles* for local development, clone the repository and -install the package in editable mode:: - - $ pip install -e . - -This will automatically add Heracles modules to your python path so that you can import into you Python codes. diff --git a/docs/manual/releases.rst b/docs/manual/releases.rst deleted file mode 100644 index b3aedb0..0000000 --- a/docs/manual/releases.rst +++ /dev/null @@ -1,6 +0,0 @@ -Releases -======== - -You may check for releases here: - -https://github.com/heracles-ec/heracles/releases/ diff --git a/docs/publications.rst b/docs/publications.rst new file mode 100644 index 0000000..aa784f4 --- /dev/null +++ b/docs/publications.rst @@ -0,0 +1,12 @@ +Publications +============ + +The *Heracles* code is based on the following publications. When using +*Heracles* in scientific work, please remember to give credit and support the +development of the code by citing the relevant papers. + +* | *Euclid preparation. Angular power spectra from discrete data sets.* + | Euclid Collaboration: Tessore et al. (2024). + | arXiv__. + +__ https://arxiv.org/abs/2409.00000 diff --git a/docs/reference/index.rst b/docs/reference/index.rst deleted file mode 100644 index e2498e6..0000000 --- a/docs/reference/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -================== -Function reference -================== - -.. toctree:: - :maxdepth: 1 - - twopoint diff --git a/docs/reference/twopoint.rst b/docs/reference/twopoint.rst deleted file mode 100644 index 2ce3be6..0000000 --- a/docs/reference/twopoint.rst +++ /dev/null @@ -1,5 +0,0 @@ -============================== -Example twopoint documentation -============================== - -Documentation to be written 'by hand' without use of automodule diff --git a/docs/releases.rst b/docs/releases.rst new file mode 100644 index 0000000..b1d55e8 --- /dev/null +++ b/docs/releases.rst @@ -0,0 +1,8 @@ +Releases +======== + +The official list of *Heracles* releases can be found on GitHub__. The list of +released Python packages is available on PyPI__. + +__ https://github.com/heracles-ec/heracles/releases +__ https://pypi.org/project/heracles diff --git a/docs/user/how-heracles-works.rst b/docs/user/how-heracles-works.rst deleted file mode 100644 index 4986773..0000000 --- a/docs/user/how-heracles-works.rst +++ /dev/null @@ -1,4 +0,0 @@ - -How *Heracles* works -==================== -Todo diff --git a/docs/user/index.rst b/docs/user/index.rst deleted file mode 100644 index cc3e545..0000000 --- a/docs/user/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -========== -User guide -========== - -.. toctree:: - :maxdepth: 2 - - how-heracles-works - publications diff --git a/docs/user/publications.rst b/docs/user/publications.rst deleted file mode 100644 index 64d998c..0000000 --- a/docs/user/publications.rst +++ /dev/null @@ -1,4 +0,0 @@ -Publications -============ - -Publications are coming - watch this space! diff --git a/examples/example.ipynb b/examples/example.ipynb index 669ab77..993d7af 100644 --- a/examples/example.ipynb +++ b/examples/example.ipynb @@ -18,10 +18,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "
\n", - "

Note: This notebook is only meant to give you an idea of how Heracles works.

\n", - "

It does not show everything that Heracles can do.

\n", - "

This is a toy, treat it is such!

\n", + "
\n", + "\n", + "**Important note**\n", + "\n", + "This notebook is only meant to give you an idea of **how *Heracles* works**.\n", + "\n", + "It does **not** show everything that *Heracles* can do.\n", + "\n", + "**This is a toy, treat it is such!**\n", + "\n", "
" ] }, diff --git a/heracles/__init__.py b/heracles/__init__.py index db894a1..5452cb6 100644 --- a/heracles/__init__.py +++ b/heracles/__init__.py @@ -27,6 +27,7 @@ # catalog "ArrayCatalog", "Catalog", + "CatalogBase", "CatalogPage", "FitsCatalog", "FootprintFilter", @@ -80,6 +81,7 @@ from .catalog import ( ArrayCatalog, Catalog, + CatalogBase, CatalogPage, FitsCatalog, FootprintFilter, diff --git a/pyproject.toml b/pyproject.toml index aade418..5e57a81 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,7 +44,9 @@ all = [ ] docs = [ "furo", + "ipython", "matplotlib", + "nbsphinx", "numpydoc", "sphinx", "sphinxcontrib-katex",