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
20 changes: 20 additions & 0 deletions docs/joss_paper/paper.bib
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
@ARTICLE{2015A&A...578A.114F,
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}
}

79 changes: 79 additions & 0 deletions docs/joss_paper/paper.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
title: 'A Python astronomy package for HiPS: Hierarchical Progressive Surveys'
tags:
- python
- astronomy
- science
- image-viewer
- image-processing

authors:
- name: Christoph Deil
orcid:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

affiliation: 1

- name: Thomas Boch
orcid:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

affiliation: 2

- name: Adeel Ahmad
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Put your name as first author!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

Please see the updated authors list and let me know if it needs any changes.

orcid: 0000-0001-5035-4497
affiliation: 3

affiliations:
- name: Max Planck Institute for Nuclear Physics, Heidelberg, Germany
index: 1
- name: Centre de Données astronomiques de Strasbourg, Strasbourg, France
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My affiliation is:
Université de Strasbourg, CNRS, Observatoire astronomique de Strasbourg

index: 2
- name: National University of Computer and Emerging Sciences, Islamabad, Pakistan
index: 3

date: 5 July 2018
bibliography: paper.bib
---

# Summary
HiPS (Hierarchical Progressive Surveys) [@2015A&A...578A.114F] is built upon the HEALPix framework 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest to add this reference when mentioning HEALPix for the first time:
http://adsabs.harvard.edu/abs/2005ApJ...622..759G
Of course it's also referenced form the HiPS paper, but given that we use HEALPix a lot and it's the basis of how this works, I think it's good to have the explicit reference in this paper.


Currently, there are clients built using HiPS, such as Aladin and Aladin Lite (\url{http://aladin.u-strasbg.fr/aladin.gml}) but they are written in Java and JavaScript, respectively. There is also ipyaladin, which provides a bridge between Jupyter and Aladin Lite, and enables interactive sky visualization in IPython notebooks.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest to add a link for ipyaladin, so that people can find it easily.

Same for the other packages we use, e.g. astropy-healpix, they should be mentioned with a link.


## Scope of the Package
The `hips` package 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. Additional features include progress bar reporting, asynchronous tile fetching, and support for multiple image formats.

For a more comprehensive introduction to the 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.

# Example Usage
A sky image from HiPS image tiles can be drawn with the `hips` package, following these three steps:

1. Specify the sky image geometry you want by creating a `WCSGeometry` object:
```python
from astropy.coordinates import SkyCoord
from hips import WCSGeometry

geometry = WCSGeometry.create(
skydir=SkyCoord(0, 0, unit='deg', frame='galactic'),
width=2000, height=1000, fov="3 deg",
coordsys='galactic', projection='AIT',
)
```
2. Specify the HiPS survey by providing a valid HiPS survey ID:
```python
hips_survey = 'CDS/P/DSS2/red'
```
3. Call the [`make_sky_image`](https://hips.readthedocs.io/en/latest/api/hips.make_sky_image.html#hips.make_sky_image "hips.make_sky_image") function to fetch the HiPS data and draw it, returning an object of [`HipsDrawResult`](https://hips.readthedocs.io/en/latest/api/hips.HipsDrawResult.html#hips.HipsDrawResult "hips.HipsDrawResult"). By default a progress bar is shown for fetching and drawing HiPS tiles. For batch processing, this can be turned off by passing a keyword argument: `progress_bar=False`:
```python
from hips import make_sky_image
result = make_sky_image(geometry, hips_survey, 'png')
```
This procedure produces the following image:

![all-sky-imge](plot_jpg.hires.png)

# 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. The authors would like to thank Google for hosting this program. We gratefully acknowledge Astropy for their affiliated packages which are extensively used in this package.

# References

Binary file added docs/joss_paper/plot_jpg.hires.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.