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 <[email protected]>
+# @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|[email protected]:|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,64 @@
+
+---
+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: 0000-0003-4568-7005
+  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
+The `hips` package allows users to fetch and draw HiPS data. It supports Python 3.6 or later and runs on most operating systems including Linux, Windows, and macOS. The HiPS (Hierarchical Progressive Surveys) scheme [@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.
+
+The presented package 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}).
+
+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 to fix the tile distortion issue, which 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 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

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()