Add JOSS article for hips package #125
Conversation
The article briefly explains the purpose of the hips package with a high-level example. It also acknowledges GSoC and Astropy for the development of this package.
There was a problem hiding this comment.
Please add Axel and Brigitta:
https://github.com/hipspy/hips/graphs/contributors
Axel is working at MPIK also, so same address as me.
@bsipocz - What's your address?
Is there a command to build a PDF or HTML version for review? To decide a bit how much text to put: Are we aiming to have 1 or 2 pages in the PDF?
docs/joss_paper/paper.md
Outdated
|
|
||
| authors: | ||
| - name: Christoph Deil | ||
| orcid: |
There was a problem hiding this comment.
This is me: http://orcid.org/0000-0002-4198-4005
docs/joss_paper/paper.md
Outdated
| # 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. | ||
|
|
||
| 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. |
There was a problem hiding this comment.
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.
docs/joss_paper/paper.md
Outdated
| orcid: | ||
| affiliation: 2 | ||
|
|
||
| - name: Adeel Ahmad |
There was a problem hiding this comment.
Put your name as first author!
There was a problem hiding this comment.
Thank you!
Please see the updated authors list and let me know if it needs any changes.
|
Since yesterday we also have a bit of functionality to generate HiPS: #123 , and I think more is coming soon in that direction. IMO we should say that we are no-where near the feature and efficiency of |
Depending on when you plan to submit, is it before 1st of Sep? |
Probably yes. |
|
Thanks for the review.
The most authentic way to build the PDF file is to use Whedon, which is a collection of command-line utilities used during the JOSS review process. I followed these steps:
Note: The above script might not work with older Output file: paper.pdf (this is still missing the JOSS logo, author names, and references) Currently, the text fits in 2 pages. To fit the text in a single page, we might have to exclude the example and some other content. Is there an advantage to having a single page article? The ones I found on JOSS were mostly 2 pages. |
|
Haha, that's a bit complicated, I think I'll leave it to you to make a PDF for review every once in a while. We can write as much as we want, but yes, I think 1 page is tough. So let's target 2 pages for now, and only extend to more if needed. Is it possible to add the authors and references? Or does the script not do that? I'm not sure how much value the example and picture adds, i.e. whether we should keep or remove it. @adl1995 - I think it's possible to have more files in the @adl1995 - Are there any good examples of nice JOSS articles we should look? |
|
I looked around a bit; here's nice examples with 1, 2, or 4 pages:
My first reaction is this: remove "tile drawing" and "example code" sections, just a single "summary", not the separate "scope" section. keep the Figure (but improve it to illustrate better that there are tiles, i.e. what the package does). Make it so that one can read the paper in 3 min max. |
docs/joss_paper/paper.md
Outdated
| affiliation: 1 | ||
|
|
||
| - name: Thomas Boch | ||
| orcid: |
There was a problem hiding this comment.
This is me:
https://orcid.org/0000-0001-5818-2781
docs/joss_paper/paper.md
Outdated
| affiliations: | ||
| - name: Max Planck Institute for Nuclear Physics, Heidelberg, Germany | ||
| index: 1 | ||
| - name: Centre de Données astronomiques de Strasbourg, Strasbourg, France |
There was a problem hiding this comment.
My affiliation is:
Université de Strasbourg, CNRS, Observatoire astronomique de Strasbourg
|
@tboch Thanks for sharing those details. @cdeil I was able to add the missing details in the PDF (expected for References). The Makefile was outdated, so I used this command instead. Here is the output file: paper.pdf
Yes, the For now, I will add a script for creating the output image with additional information. I think it would be similar to what we currently use in the documentation with Sphinx. Regarding the sections, I agree we should cut down to just the useful information. I will upload multiple drafts and then we can decide which one to go with. |
|
I would suggest you just commit the make file or whatever is needed to build the PDF to that folder. The layout is very nice now. The references at the end and Axel, Brigitta as co-authors are still missing in the PDF. |
docs/joss_paper/paper.md
Outdated
| --- | ||
|
|
||
| # 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. |
There was a problem hiding this comment.
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.
|
Suggest to mention and even cite both http://scikit-image.org/ and http://www.astropy.org/acknowledging.html (both papers). |
|
@cdeil @bsipocz Please check the updated content. Output PDF: https://github.com/hipspy/hips/blob/c7d52471f1ab1de94d5cadc951c112ceb40e6c85/docs/joss_paper/paper.pdf The references are showing up now. @cdeil Currently, the article fits in three pages. I think we would have to exclude the code block to fit it in two pages, or cut down on other content. Which one do you prefer? Also, the output image only shows the grid for now. I have yet to add the tile number in the center. |
|
@cdeil Thank you for the feedback. I'm also fine with excluding the code example, and just provide a link to the documentation. I have tried to address the points you mentioned above in this PDF (except for numbering the HiPS tiles): paper.pdf I haven't yet pushed these changes to GitHub in case it needs further changes. Also, would you prefer if we provide hyperlinks instead of the currently used format? E.g. change (aiohttp https://github.com/aio-libs/aiohttp) to aiohttp. |
|
I feel hyperlinks would be OK, unless JOSS has other preferences. Also, you may want to use the same monospace font for the other package name as you did for |
|
@bsipocz I looked at some papers, and they all seem to provide a full URL link instead of a hyperlink. Maybe we can keep this as is for now, and make changes during the JOSS review, if required. The font for package names is updated to monospace, and I have pushed all changes to GitHub. Updated PDF file: paper.pdf @adonath Can you please add your ORCID? @cdeil When would be a good time to make the submission? The current papers requesting review can be found at: https://github.com/openjournals/joss-reviews/issues. I've noticed that it takes a few months for some papers to get reviewed. Should we submit the paper for a pre-review and make changes while we work on the next release? |
|
@adl1995 - Thank you for all your work here! I would suggest to remove the "scope of the package" heading. (just the heading, not the content) It's not very useful, and actually that section contains many things, not just a description of the scope. Similarly I would suggest to remove the "Tile drawing algorithm" heading (just the heading, not the content). The algorithm we have is preliminary, we plan to add a better one shortly. And as given, the algorithm isn't fully described. I think such a 4-line summary is exactly what we should put, but I don't like putting a big heading in front of those four lines. Suggest to just have a single section "summary" like many JOSS articles, and then a few paragraphs there.
I'm not sure when to submit. My first thought is that submitting a "pre" version won't help getting this published faster. Is it possible that we all work on this a bit more in July and have v0.3 and the paper fully ready in ~ 2 weeks? Would a short telcon to discuss what is essential and distribute the tasks help? (I'm available) |
hips/draw/paint.py
Outdated
| @@ -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: | |||
There was a problem hiding this comment.
I thought we already had such a helper method?
Suggest to either make a separate PR for additions to the hips package, or to just move this to the plot_jpg.py script. (let's not mix package additions / changes with this paper, e.g. the paper might be merged after v0.3).
There was a problem hiding this comment.
Ah, this was committed by mistake. The current function only drew grid lines around the tiles. I was trying to add the tile numbers to it, similar to what Aladin Lite does (with HEALPix grid turned on).
Once this functionality is complete, I think this can be merged with the current function plot_mpl_hips_tile_grid (in a separate PR).
|
@adl1995 Thanks for your work! My orcid is |
This commit also removes the plot_mpl_hips_tile_number_grid function. The image plot is also rescaled and its bordres are trimmed.
|
@adonath Thanks for sharing those details. If you want to commit these changes yourself, you can open a pull request in adl1995:joss-paper (similar to #2). |
|
@cdeil Thanks for the review. I have merged the headings "Scope of the Package" and "Tile Drawing Algorithm" within Summary. The paper fits in 2 pages now and looks neat (paper.pdf).
Yes, I think we can get the v0.3 ready by this month's end. A telcon would certainly help. I will be available from tomorrow onwards. Please let me know what time suits you well, and I'll prepare a Google Doc with the points we should discuss. |
|
@adl1995 - Can you please schedule the Google hangout for this? |
|
@cdeil - Sure. My time zone is 3 hours ahead of CEST (GMT+5), so the slots you listed work for me as well. Should I confirm your availability during this weekend, or just schedule the telcon in between 9 am to 4 pm CEST for Monday? |
|
@adl1995 - I would suggest you make a Doodle where you offer a few days / timeslots here, and then post the link to it here, asking all co-authors to fill it. Hopefully we'll find a slot where everyone can join. |
Add adonath orcid to paper.md
|
@cdeil, @tboch, @bsipocz, @adonath - Please fill out this Doodle: https://doodle.com/poll/7vip8rynipwg9e32#calendar to indicate your availability. I have provided 1 hour slots between 9 am to 4 pm CEST from July 23 - July 27. Once everyone has filled out the form, I'll create a Google Hangouts event. |
|
@adl1995 - I'm afraid I won't have any time to directly sprint on hipspy in the near future, but feel free to tag me with any infrastructure issues you run into while pushing for 0.3 (either on GH, or on the astropy slack). |
|
@adl1995 I'll be on vacation next week. I won't be able to join you. |
|
@tboch - Are you available the week after? (July 30 to Aug 3)? I think it's important to have @tboch in the call. |
|
@cdeil - no, my earliest availability would be the week of August 13. |
|
@tboch - A short call this week still possible? If no, or in any case, could you please look at the latest draft and leave comments? I think it's already in pretty good shape, no? My main remaining comment would be that I'd prefer if we change the example to Fermi-LAT and HiPS produced by |
|
@cdeil - Tomorrow July 19 between 2 and 3:30pm could work for me. |
I fully agree. If @adonath has enough time to make hipspy generating a full working HiPS, that would be very beneficial for the package and the JOSS paper. |
|
@adl1995 - many thanks for initiating this paper! Given that we want a short text, I think that the current version is good. In the summary section, I would find it better if we started by a general sentence on what the hips package intends to do. Otherwise, I find it strange as this section currently only talks about the HiPS standard and HEALPix. cc @cdeil |
|
@adl1995 - I think the paper is mostly done. Now we have to finish up v0.3, and then we can come back to final review of the paper text and submitting it. If you have time, please help close out issues under the v0.3 milestone. My time is very limited, but I'll try to work on it a bit in the next two weeks. |
The article briefly explains the purpose of the
hipspackage with a high-level example. It also acknowledges GSoC and Astropy for the development of this package.@cdeil and @tboch: Could you please add your ORCID in the
paper.mdfile? Also, please let me know if I should add / modify any details, particularly regarding the citations.