Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add JOSS article for hips package #125

Open
wants to merge 13 commits into
base: master
Choose a base branch
from
Open
Prev Previous commit
Next Next commit
Merge paper headings within Summary
This commit also removes the plot_mpl_hips_tile_number_grid
function. The image plot is also rescaled and its bordres
are trimmed.
adl1995 committed Jul 17, 2018
commit 2bdfd143c26f9be32bcd8d8d10c7063508f2e923
14 changes: 6 additions & 8 deletions docs/joss_paper/paper.md
Original file line number Diff line number Diff line change
@@ -46,21 +46,19 @@ bibliography: paper.bib
# Summary
HiPS (Hierarchical Progressive Surveys) [@hips] is built upon the HEALPix framework [@healpix] and provides a way to store large astronomical survey sky images and catalog datasets on servers (such as HiPS at CDS (\url{http://aladin.u-strasbg.fr/hips}), that allows clients to efficiently fetch only the image tiles or catalog parts for a given region of the sky they are interested in.

Currently, there are clients built using HiPS, such as Aladin Desktop (\url{http://aladin.unistra.fr/AladinDesktop}) and Aladin Lite (\url{http://aladin.unistra.fr/AladinLite}) but they are written in Java and JavaScript, respectively. There is also `ipyaladin` (\url{https://github.com/cds-astro/ipyaladin}), which provides a bridge between Jupyter and Aladin Lite, and enables interactive sky visualization in IPython notebooks.
Currently, there are clients built using HiPS, such as Aladin Desktop (\url{http://aladin.unistra.fr/AladinDesktop}) and Aladin Lite (\url{http://aladin.unistra.fr/AladinLite}), but they are written in Java and JavaScript, respectively. There is also `ipyaladin` (\url{https://github.com/cds-astro/ipyaladin}), which provides a bridge between Jupyter and Aladin Lite, and enables interactive sky visualization in IPython notebooks.

## Scope of the Package
The `hips` Python package supports version 3.6 or later and runs on most operating systems including Linux, Windows, and macOS. It provides flexibility by extending both a high-level and low-level API for novice and advanced users, respectively. It provides the functionality for drawing a sky image from HiPS tiles, transforming HiPS to WCS images, and HEALPix to HiPS---which takes in HEALPix data stored in the "nested" scheme and creates a dictionary object containing HiPS. Additional features include progress bar reporting (`tqdm` \url{https://github.com/tqdm/tqdm}), asynchronous tile fetching (`aiohttp` \url{https://github.com/aio-libs/aiohttp}), image input / output (`pillow` \url{https://python-pillow.org}), and support for multiple image formats including FITS, PNG, and JPG. The FITS format stores image metadata in a human-readable ASCII header and is the standard for astronomical applications. Whereas, PNG and JPG formats contain RGB color images.
The `hips` package supports Python 3.6 or later and runs on most operating systems including Linux, Windows, and macOS. It provides flexibility by extending both a high-level and low-level API for novice and advanced users, respectively. It provides the functionality for drawing a sky image from HiPS tiles, transforming HiPS to WCS images, and HEALPix to HiPS---which takes in HEALPix data stored in the "nested" scheme and creates a dictionary object containing HiPS. Additional features include progress bar reporting (`tqdm` \url{https://github.com/tqdm/tqdm}), asynchronous tile fetching (`aiohttp` \url{https://github.com/aio-libs/aiohttp}), image input / output (`pillow` \url{https://python-pillow.org}), and support for multiple image formats including FITS, PNG, and JPG. The FITS format stores image metadata in a human-readable ASCII header and is the standard for astronomical applications. Whereas, PNG and JPG formats contain RGB color images.

The modules provided by this package mostly build upon Astropy [@2018arXiv180102634T] affiliated packages, namely, `astropy-healpix` (\url{https://github.com/astropy/astropy-healpix}) and `reproject` (\url{https://reproject.readthedocs.io}). The drawing module makes extensive use of projective transformation for which we acknowledge `skimage` [@scikit-image].
The modules provided by this package mostly build upon Astropy [@2018arXiv180102634T] affiliated packages, namely, `astropy-healpix` (\url{https://github.com/astropy/astropy-healpix}) and `reproject` (\url{https://reproject.readthedocs.io}).

For a more comprehensive introduction to the `hips` package, please see the documentation at (\url{http://hips.readthedocs.io}) and the source code at (\url{http://github.com/hipspy/hips}).
We also acknowledge `skimage` [@scikit-image] for their projective transformation module which we apply for projecting HiPS tiles onto the sky image. To achieve this, we first compute the tile corners, which help us in determining the position where the tile is to be placed. The tiles are further split into four children tiles, which is done to fix the tile distortion issue, and results in a more precise image.

## Tile Drawing Algorithm
Projective transformation is applied for projecting HiPS tiles onto the sky image. To achieve this, we first compute the tile corners, which helps us in determining the position where the tile is to be placed. The tiles are further split into four children tiles, which is done to fix the tile distortion issue, and results in a more precise image.
For a more comprehensive introduction to the `hips` package, please see the documentation at (\url{https://hips.readthedocs.io}) and the source code at (\url{https://github.com/hipspy/hips}).

![Astronomical sky image made with the hips Python package using IPAC/P/GLIMPSE360 HiPS survey](plot_jpg.hires.jpg)

# Acknowledgements
This project was initiated as part of Google Summer of Code 2017 program (\url{https://summerofcode.withgoogle.com}) under the Open Astronomy umbrella organization during which period v0.1 and v0.2 were released. The release of v0.3 is expected in summer 2018. The authors would like to thank Google for hosting this program.
This project was initiated as part of Google Summer of Code 2017 program (\url{https://summerofcode.withgoogle.com}) under the Open Astronomy umbrella organization. During this period v0.1 and v0.2 was released. The release of v0.3 is expected in summer 2018. The authors would like to thank Google for hosting this program.

# References
Binary file modified docs/joss_paper/paper.pdf
Binary file not shown.
Binary file modified docs/joss_paper/plot_jpg.hires.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
24 changes: 0 additions & 24 deletions hips/draw/paint.py
Original file line number Diff line number Diff line change
@@ -221,30 +221,6 @@ def plot_mpl_hips_tile_grid(self) -> None:
transform=ax.get_transform('world'), **opts)
ax.imshow(self.image, origin='lower')

def plot_mpl_hips_tile_number_grid(self) -> None:
"""Plot output image and HiPS grid with matplotlib.

This is mainly useful for debugging the drawing algorithm,
not something end-users will call or need to know about.
"""
import matplotlib.pyplot as plt
self.make_tile_list()
i = 0
for tile in self.draw_tiles:
corners = tile.meta.skycoord_corners.transform_to(self.geometry.celestial_frame)
ax = plt.subplot(projection=self.geometry.wcs)
opts = dict(color='red', lw=1, )
ax.plot(corners.data.lon.deg, corners.data.lat.deg,
transform=ax.get_transform('world'), **opts)
# ax.text(corners.data.lon.deg, corners.data.lat.deg,
# '2', bbox=dict(facecolor='red', alpha=0.5),
# transform=ax.get_transform('world'))
ax.text(0.5, 0.5,
'{:d}'.format(i), color='w', ha='center', va='center')
i += 1

ax.imshow(self.image, origin='lower')


def measure_tile_lengths(corners: Tuple[np.ndarray, np.ndarray]) -> Tuple[np.ndarray, np.ndarray]:
"""Compute length of tile edges and diagonals.