Skip to content

Commit

Permalink
fix documentation and add notebook gallery
Browse files Browse the repository at this point in the history
  • Loading branch information
@ManonMarchand
ManonMarchand committed Nov 6, 2023
1 parent 8846158 commit ab525ca
Show file tree
Hide file tree
Showing 7 changed files with 589 additions and 209 deletions.
26 changes: 11 additions & 15 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
repos:
# General pre-commits
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
rev: v4.5.0
hooks:
- id: detect-private-key
description: "Check accidental private keys in code"
Expand All @@ -10,32 +10,28 @@ repos:
- id: trailing-whitespace
description: "Remove trailing whitespaces"
- repo: https://github.com/pre-commit/pygrep-hooks
rev: 'v1.9.0'
rev: 'v1.10.0'
hooks:
- id: python-no-eval
- id: rst-backticks
# For python files
- repo: https://github.com/psf/black
# Code style
rev: 22.12.0
rev: 23.10.1
hooks:
- id: black
- repo: https://github.com/charliermarsh/ruff-pre-commit
# Fast linter to replace flake8
rev: 'v0.0.212'
hooks:
- id: ruff
fail_fast: true
# Same tools but for Jupyter notebooks
# Same tool but for Jupyter notebooks
- repo: https://github.com/nbQA-dev/nbQA
rev: 1.6.0
rev: 1.7.0
hooks:
- id: nbqa-black
name: nbqa-black
description: "Run 'black' on a Jupyter Notebook"
language: python
require_serial: true
- id: nbqa-ruff
name: nbqa-ruff
description: "Run ruff on a Jupyter notebook"
fail_fast: true
- repo: https://github.com/charliermarsh/ruff-pre-commit
# Fast linter to replace flake8
rev: 'v0.1.4'
hooks:
- id: ruff
fail_fast: true
68 changes: 48 additions & 20 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,33 +15,39 @@
import os
import sys

# Get configuration information from toml
import tomllib
import datetime

with open("../Cargo.toml", "rb") as config:
cargotoml = tomllib.load(config)

sys.path.insert(0, os.path.abspath(".."))

# -- Project information -----------------------------------------------------

project = "cdshealpix"
copyright = "2019, François-Xavier Pineau, Matthieu Baumann"
author = "François-Xavier Pineau, Matthieu Baumann"
project = cargotoml["package"]["name"]
author = " ".join(cargotoml["package"]["authors"])
copyright = f"{datetime.datetime.now().year}, {author}"


# The short X.Y version
version = ""
version = cargotoml["package"]["version"].rsplit(".", 1)[0]
# The full version, including alpha/beta/rc tags
release = ""
release = cargotoml["package"]["version"]


# -- General configuration ---------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# By default, highlight as Python 3.
highlight_language = "python3"

# 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.doctest",
"sphinx.ext.intersphinx",
# to allow usage of a folder not in docs
"sphinxcontrib.collections",
"sphinx.ext.githubpages",
"sphinx.ext.autosummary",
# Extension for plotting image in the doc
Expand All @@ -51,12 +57,17 @@
"numpydoc",
"sphinxcontrib.bibtex",
"sphinx.ext.mathjax",
"jupyter_sphinx",
# for notebooks
"nbsphinx",
# to add copypaste of notebook cells
"sphinx_copybutton",
"sphinx_gallery.load_style",
]
default_role = "py:obj"
numpydoc_class_members_toctree = False
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
bibtex_bibfiles = ["references.bib"]

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
Expand Down Expand Up @@ -116,6 +127,21 @@
#
# html_sidebars = {}

# -- Add the notebooks to Sphinx root folder with collections ----------------

collections = {
"notebooks": {
"driver": "copy_folder",
"source": "../notebooks/",
"target": "notebooks",
"ignore": [".fits", ".ipynb_checkpoints/*"],
}
}

# -- Configuration for nbsphinx ----------------------------------------------

nbsphinx_allow_errors = True


# -- Options for HTMLHelp output ---------------------------------------------

Expand Down Expand Up @@ -143,12 +169,13 @@
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
title = "cdshealpix Documentation"
latex_documents = [
(
master_doc,
"cdshealpix.tex",
"cdshealpix Documentation",
"François-Xavier Pineau, Matthieu Baumann",
title,
author,
"manual",
),
]
Expand All @@ -158,7 +185,7 @@

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [(master_doc, "cdshealpix", "cdshealpix Documentation", [author], 1)]
man_pages = [(master_doc, "cdshealpix", title, author, 1)]


# -- Options for Texinfo output ----------------------------------------------
Expand All @@ -169,12 +196,12 @@
texinfo_documents = [
(
master_doc,
"cdshealpix",
"cdshealpix Documentation",
project,
title,
author,
"cdshealpix",
"One line description of project.",
"Miscellaneous",
project,
cargotoml["package"]["description"],
cargotoml["package"]["categories"],
),
]

Expand Down Expand Up @@ -206,6 +233,7 @@
"python": ("https://docs.python.org/", None),
"astropy": ("http://docs.astropy.org/en/latest/", None),
"numpy": ("http://docs.scipy.org/doc/numpy/", None),
"matplotlib": ("https://matplotlib.org/", None),
}


Expand Down
161 changes: 5 additions & 156 deletions docs/examples/examples.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,160 +19,9 @@ Polygon search
.. plot:: examples/polygon_search.py
:include-source:

Coordinate conversion
---------------------
Notebook examples
-----------------


In this example, we will load an archival all-sky Galactic reddening map, E(B-V),
based on the derived reddening maps of Schlegel, Finkbeiner and Davis (1998) :cite:`Schlegel_1998`.
It has been translated into an HEALPix map in galactic coordinates by the Legacy Archive
for Microwave Background Data Analysis `LAMBDA <http://lambda.gsfc.nasa.gov/>`_.
We'll rotate it into equatorial coordinates for demonstration purpose.

Algorithm
^^^^^^^^^

It follows the following reasonning:

- get the coordinates of the centers of the HEALPix map in galactic coordinates,
- converts those to equatorial coordinates with the astropy library,
- find the bilinear interpolation for the neighbors of each of these new coordinates using cdshealpix methods,
- apply it to form a HEALPix map in the new coordinate system.

Disclaimer
^^^^^^^^^^

This example was designed to illustrate the use of this library.
This transformation is not the most precise you could get and should be used
for visualizations or to have a quick view at maps in different coordinate systems.
For scientific use, please have a look at the method rotate_alm in
`healpy <https://github.com/healpy/healpy>`_ or at the sht module of the
`ducc <https://gitlab.mpcdf.mpg.de/mtr/ducc>`_ library that both implement the rotation in the spherical harmonics space.


.. jupyter-execute::

import cdshealpix

from mocpy import MOC, WCS
import astropy.units as u

from astropy.io import fits
from astropy.coordinates import SkyCoord, Angle

import matplotlib.pyplot as plt
import numpy as np

Fetching the HEALPix map from NASA archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. jupyter-execute::

ext_map = fits.open(
"https://lambda.gsfc.nasa.gov/data/foregrounds/SFD/" + "lambda_sfd_ebv.fits"
) # dowloading the map from the nasa archive
hdr = ext_map[0].header # extracts the header
data_header = ext_map[1].header
data = ext_map[1].data # extracts the data
ext_map.close()

hdr

Let's also have a look at the data header

.. jupyter-execute::

data_header

After learning that the magnitudes are stored in ``'TEMPERATURE'``, we can extract all useful information.

.. jupyter-execute::

extinction_values = data["TEMPERATURE"]
nside = hdr["NSIDE"]
norder = hdr["RESOLUTN"]

Coordinate conversion
^^^^^^^^^^^^^^^^^^^^^
We first create an HEALPix grid at order 9 (like the original) in nested ordering

.. jupyter-execute::

healpix_index = np.arange(12 * 4**norder, dtype=np.uint64)
print(
f"We can check that the NPIX value corresponds to the one in the header here: {len(healpix_index)}"
)

Then, we get the coordinates of the centers of these healpix cells

.. jupyter-execute::

center_coordinates_in_equatorial = cdshealpix.healpix_to_skycoord(
healpix_index, depth=norder
) # this function works for nested maps, see cdshealpix documentation
center_coordinates_in_equatorial

Conversion into galactic coordinates with astropy method

.. jupyter-execute::

center_coordinates_in_galactic = center_coordinates_in_equatorial.galactic
center_coordinates_in_galactic

Calculate the bilinear interpolation that must be applied to each
HEALPix cell to obtain the magnitude values in the other coordinate system.

.. jupyter-execute::

healpix, weights = cdshealpix.bilinear_interpolation(
center_coordinates_in_galactic.l, center_coordinates_in_galactic.b, depth=norder
)
# then apply the interpolation
ext_map_equatorial_nested = (extinction_values[healpix.data] * weights.data).sum(axis=1)

Convert the two HEALPix into MOCs for visualisation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

We produce MOCs by excluding the high extinction regions. This allows to have a clear view of the position
of the galactic disc.

.. jupyter-execute::

# For the HEALPix in equatorial coordinate system
low_extinction_index_equatorial = np.where((ext_map_equatorial_nested < 0.5))[0]
moc_low_extinction_equatorial = MOC.from_healpix_cells(
ipix = low_extinction_index_equatorial,
depth = np.full((len(low_extinction_index_equatorial)),norder),
max_depth = norder
)

# For the HEALPix in galactic coordinate system
low_extinction_index_galactic = np.where((extinction_values < 0.5))[0]
moc_low_extinction_galactic = MOC.from_healpix_cells(
ipix = low_extinction_index_galactic,
depth = np.full((len(low_extinction_index_galactic)),norder),
max_depth = norder
)

# Plot the MOCs using matplotlib
fig = plt.figure(figsize=(20, 10))
# Define a astropy WCS from the mocpy.WCS class
with WCS(fig,
fov=120 * u.deg,
center=SkyCoord(0, 0, unit='deg', frame='icrs'),
coordsys="icrs",
rotation=Angle(0, u.degree),
projection="SIN") as wcs:

ax1 = fig.add_subplot(121, projection=wcs, aspect='equal', adjustable='datalim')
ax2 = fig.add_subplot(122, projection=wcs, aspect='equal', adjustable='datalim')
moc_low_extinction_galactic.fill(ax=ax1, wcs=wcs, alpha=0.5, fill=True, color="green")
moc_low_extinction_equatorial.fill(ax=ax2, wcs=wcs, alpha=0.5, fill=True, color="green")


ax1.set(xlabel = 'l', ylabel= 'b', title='galactic')
ax2.set(xlabel='ra', ylabel='dec', title='ICRS')

ax1.grid(color="black", linestyle="dotted")
ax2.grid(color="black", linestyle="dotted")
plt.show()
.. nbgallery::
../_collections/notebooks/coordinate_conversion.ipynb
../_collections/notebooks/external_neighbours.ipynb
Loading

0 comments on commit ab525ca

Please sign in to comment.