Add JOSS article for hips package

docs/joss_paper/Makefile

@@ -0,0 +1,52 @@
+# =============================================================================
+# @file    Makefile
+# @brief   Makefile for generating previews of the paper
+# @author  Michael Hucka <mhucka@caltech.edu>
+# @license Please see the file named LICENSE in the project directory
+# @website https://github.com/casics/dassie
+# =============================================================================
+
+# Change the following values to match your configuration.
+# .............................................................................
+
+input	:= paper.md
+output	:= paper.pdf
+bib	:= paper.bib
+
+# Main code -- no more customization variables after this point
+# .............................................................................
+
+title	:= $(shell grep title: $(input) | sed 's/title: *//' | tr -d "'")
+authors := $(shell sed -n '/authors:/,/affiliations:/p' $(input) | grep name: | sed 's/- name: *//' | paste -d, -s - | sed 's/,/, /g')
+repo	:= $(shell git config --get remote.origin.url | sed 's|git@github.com:|https://github.com/|' | sed 's/\.git//')
+#repo    := https://github.com/hipspy/hips
+
+$(output): $(input) $(bib) Makefile
+	pandoc \
+	-V paper_title="$(title)" \
+	-V citation_author="$(authors)" \
+	-V repository="$(repo)" \
+	-V archive_doi="http://dx.doi.org/00.00000/zenodo.0000000" \
+	-V formatted_doi="00.00000/joss.00000" \
+	-V paper_url="http://joss.theoj.org/papers/" \
+	-V review_issue_url="http://joss.theoj.org/papers/" \
+	-V issue="0" \
+	-V volume="00" \
+	-V year="2018" \
+	-V submitted="00 January 0000" \
+	-V published="00 January 0000" \
+	-V page="00" \
+	-V graphics="true" \
+	-V joss_logo_path="whedon/resources/joss-logo.png" \
+	-V logo_path="whedon/resources/joss-logo.png" \
+	-V footnote_paper_title="..." \
+	-V geometry:margin=1in \
+        -V journal_name="JOSS" \
+	-o $(output) \
+	--pdf-engine=xelatex \
+	--filter pandoc-citeproc $(input) \
+	--from markdown+autolink_bare_uris \
+	--template "whedon/resources/latex.template"
+
+autorefresh:;
+	((ls $(input) $(bib) | entr make $(output)) &)

docs/joss_paper/paper.bib

@@ -0,0 +1,107 @@
+@ARTICLE{hips,
+   author = {{Fernique}, P. and {Allen}, M.~G. and {Boch}, T. and {Oberto}, A. and 
+	{Pineau}, F.-X. and {Durand}, D. and {Bot}, C. and {Cambr{\'e}sy}, L. and 
+	{Derriere}, S. and {Genova}, F. and {Bonnarel}, F.},
+    title = "{Hierarchical progressive surveys. Multi-resolution HEALPix data structures for astronomical images, catalogues, and 3-dimensional data cubes}",
+  journal = {\aap},
+archivePrefix = "arXiv",
+   eprint = {1505.02291},
+ primaryClass = "astro-ph.IM",
+ keywords = {surveys, atlases, astronomical databases: miscellaneous, catalogs, virtual observatory tools, methods: statistical},
+     year = 2015,
+    month = jun,
+   volume = 578,
+      eid = {A114},
+    pages = {A114},
+      doi = {10.1051/0004-6361/201526075},
+   adsurl = {http://cdsads.u-strasbg.fr/abs/2015A%26A...578A.114F},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@ARTICLE{healpix,
+   author = {{G{\'o}rski}, K.~M. and {Hivon}, E. and {Banday}, A.~J. and 
+	{Wandelt}, B.~D. and {Hansen}, F.~K. and {Reinecke}, M. and 
+	{Bartelmann}, M.},
+    title = "{HEALPix: A Framework for High-Resolution Discretization and Fast Analysis of Data Distributed on the Sphere}",
+  journal = {\apj},
+   eprint = {astro-ph/0409513},
+ keywords = {Cosmology: Cosmic Microwave Background, Cosmology: Observations, Methods: Statistical},
+     year = 2005,
+    month = apr,
+   volume = 622,
+    pages = {759-771},
+      doi = {10.1086/427976},
+   adsurl = {http://adsabs.harvard.edu/abs/2005ApJ...622..759G},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@ARTICLE{2018arXiv180102634T,
+   author = {{The Astropy Collaboration} and {Price-Whelan}, A.~M. and {Sip{\H o}cz}, B.~M. and 
+	{G{\"u}nther}, H.~M. and {Lim}, P.~L. and {Crawford}, S.~M. and 
+	{Conseil}, S. and {Shupe}, D.~L. and {Craig}, M.~W. and {Dencheva}, N. and 
+	{Ginsburg}, A. and {VanderPlas}, J.~T. and {Bradley}, L.~D. and 
+	{P{\'e}rez-Su{\'a}rez}, D. and {de Val-Borro}, M. and {Aldcroft}, T.~L. and 
+	{Cruz}, K.~L. and {Robitaille}, T.~P. and {Tollerud}, E.~J. and 
+	{Ardelean}, C. and {Babej}, T. and {Bachetti}, M. and {Bakanov}, A.~V. and 
+	{Bamford}, S.~P. and {Barentsen}, G. and {Barmby}, P. and {Baumbach}, A. and 
+	{Berry}, K.~L. and {Biscani}, F. and {Boquien}, M. and {Bostroem}, K.~A. and 
+	{Bouma}, L.~G. and {Brammer}, G.~B. and {Bray}, E.~M. and {Breytenbach}, H. and 
+	{Buddelmeijer}, H. and {Burke}, D.~J. and {Calderone}, G. and 
+	{Cano Rodr{\'{\i}}guez}, J.~L. and {Cara}, M. and {Cardoso}, J.~V.~M. and 
+	{Cheedella}, S. and {Copin}, Y. and {Crichton}, D. and {D{\'A}vella}, D. and 
+	{Deil}, C. and {Depagne}, {\'E}. and {Dietrich}, J.~P. and {Donath}, A. and 
+	{Droettboom}, M. and {Earl}, N. and {Erben}, T. and {Fabbro}, S. and 
+	{Ferreira}, L.~A. and {Finethy}, T. and {Fox}, R.~T. and {Garrison}, L.~H. and 
+	{Gibbons}, S.~L.~J. and {Goldstein}, D.~A. and {Gommers}, R. and 
+	{Greco}, J.~P. and {Greenfield}, P. and {Groener}, A.~M. and 
+	{Grollier}, F. and {Hagen}, A. and {Hirst}, P. and {Homeier}, D. and 
+	{Horton}, A.~J. and {Hosseinzadeh}, G. and {Hu}, L. and {Hunkeler}, J.~S. and 
+	{Ivezi{\'c}}, {\v Z}. and {Jain}, A. and {Jenness}, T. and {Kanarek}, G. and 
+	{Kendrew}, S. and {Kern}, N.~S. and {Kerzendorf}, W.~E. and 
+	{Khvalko}, A. and {King}, J. and {Kirkby}, D. and {Kulkarni}, A.~M. and 
+	{Kumar}, A. and {Lee}, A. and {Lenz}, D. and {Littlefair}, S.~P. and 
+	{Ma}, Z. and {Macleod}, D.~M. and {Mastropietro}, M. and {McCully}, C. and 
+	{Montagnac}, S. and {Morris}, B.~M. and {Mueller}, M. and {Mumford}, S.~J. and 
+	{Muna}, D. and {Murphy}, N.~A. and {Nelson}, S. and {Nguyen}, G.~H. and 
+	{Ninan}, J.~P. and {N{\"o}the}, M. and {Ogaz}, S. and {Oh}, S. and 
+	{Parejko}, J.~K. and {Parley}, N. and {Pascual}, S. and {Patil}, R. and 
+	{Patil}, A.~A. and {Plunkett}, A.~L. and {Prochaska}, J.~X. and 
+	{Rastogi}, T. and {Reddy Janga}, V. and {Sabater}, J. and {Sakurikar}, P. and 
+	{Seifert}, M. and {Sherbert}, L.~E. and {Sherwood-Taylor}, H. and 
+	{Shih}, A.~Y. and {Sick}, J. and {Silbiger}, M.~T. and {Singanamalla}, S. and 
+	{Singer}, L.~P. and {Sladen}, P.~H. and {Sooley}, K.~A. and 
+	{Sornarajah}, S. and {Streicher}, O. and {Teuben}, P. and {Thomas}, S.~W. and 
+	{Tremblay}, G.~R. and {Turner}, J.~E.~H. and {Terr{\'o}n}, V. and 
+	{van Kerkwijk}, M.~H. and {de la Vega}, A. and {Watkins}, L.~L. and 
+	{Weaver}, B.~A. and {Whitmore}, J.~B. and {Woillez}, J. and 
+	{Zabalza}, V.},
+    title = "{The Astropy Project: Building an inclusive, open-science project and status of the v2.0 core package}",
+  journal = {ArXiv e-prints},
+archivePrefix = "arXiv",
+   eprint = {1801.02634},
+ primaryClass = "astro-ph.IM",
+ keywords = {Astrophysics - Instrumentation and Methods for Astrophysics},
+     year = 2018,
+    month = jan,
+   adsurl = {http://adsabs.harvard.edu/abs/2018arXiv180102634T},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@article{scikit-image,
+ title = {scikit-image: image processing in {P}ython},
+ author = {van der Walt, {S}t\'efan and {S}ch\"onberger, {J}ohannes {L}. and
+           {Nunez-Iglesias}, {J}uan and {B}oulogne, {F}ran\c{c}ois and {W}arner,
+           {J}oshua {D}. and {Y}ager, {N}eil and {G}ouillart, {E}mmanuelle and
+           {Y}u, {T}ony and the scikit-image contributors},
+ year = {2014},
+ month = {6},
+ keywords = {Image processing, Reproducible research, Education,
+             Visualization, Open source, Python, Scientific programming},
+ volume = {2},
+ pages = {e453},
+ journal = {PeerJ},
+ issn = {2167-8359},
+ url = {http://dx.doi.org/10.7717/peerj.453},
+ doi = {10.7717/peerj.453}
+}
+

docs/joss_paper/paper.md

@@ -0,0 +1,66 @@
+
+---
+title: 'A Python astronomy package for HiPS: Hierarchical Progressive Surveys'
+tags:
+- python
+- astronomy
+- science
+- image-viewer
+- image-processing
+
+authors:
+- name: Adeel Ahmad
+  orcid: 0000-0001-5035-4497
+  affiliation: 1
+
+- name: Christoph Deil
+  orcid: 0000-0002-4198-4005
+  affiliation: 2
+
+- name: Thomas Boch
+  orcid: 0000-0001-5818-2781
+  affiliation: 3
+
+- name: Brigitta M Sipőcz
+  orcid: 0000-0002-3713-6337
+  affiliation: 4
+
+- name: Axel Donath
+  orcid:
+  affiliation: 2
+
+affiliations:
+- name: National University of Computer and Emerging Sciences, Islamabad, Pakistan
+  index: 1
+- name: Max Planck Institute for Nuclear Physics, Heidelberg, Germany
+  index: 2
+- name: Université de Strasbourg, CNRS, Observatoire astronomique de Strasbourg
+  index: 3
+- name: Institute of Astronomy, University of Cambridge, Madingley Road, Cambridge, CB3 0HA, UK
+  index: 4
+
+date: 5 July 2018
+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.
+
+## 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 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].
+
+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}).
+
+## 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.
+
+![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.
+
+# References

docs/joss_paper/plot_jpg.py

@@ -0,0 +1,16 @@
+"""Basic example how to plot a sky image with the hips package"""
+from astropy.coordinates import SkyCoord
+from hips import WCSGeometry, HipsPainter
+
+# Compute the sky image
+geometry = WCSGeometry.create(
+    skydir=SkyCoord(0, 0, unit='deg', frame='galactic'),
+    width=2000, height=1000, fov="3 deg",
+    coordsys='galactic', projection='AIT',
+)
+hips_survey = 'IPAC/P/GLIMPSE360'
+
+fetch_opts = dict(fetch_package='urllib', timeout=30, n_parallel=10)
+painter = HipsPainter(geometry, hips_survey, 'jpg', fetch_opts=fetch_opts)
+painter.run()
+painter.plot_mpl_hips_tile_number_grid()

hips/draw/paint.py

@@ -221,6 +221,30 @@ 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.