Add JOSS article for hips package

adl1995 commented 6 years ago

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.

@cdeil and @tboch: Could you please add your ORCID in the paper.md file? Also, please let me know if I should add / modify any details, particularly regarding the citations.

coveralls commented 6 years ago

Coverage remained the same at 96.272% when pulling 2bf5bb71788530315db5983738ad8cbf69afdc70 on adl1995:joss-paper into ead742fe422fd0d8b3f2227aba5be0685d603fd0 on hipspy:master.

cdeil commented 6 years ago

Since yesterday we also have a bit of functionality to generate HiPS: #123 , and I think more is coming soon in that direction. This should be mentioned with 1-2 sentences, and there also a reference to hipsgen / Aladin Desktop should be made, which is the Java tool that made all HiPS so far: http://aladin.u-strasbg.fr/hips/HipsIn10Steps.gml

IMO we should say that we are no-where near the feature and efficiency of hipsgen, but that we're adding some HiPS gen functionatliy here because it's useful for some cases, where one wants to use Python scripting and e.g. have full control over how the HiPS pixels are filled, using e.g. scikit-image or http://reproject.readthedocs.io/ , i.e. for cases where full control and flexibility is needed.

bsipocz commented 6 years ago

@bsipocz - What's your address?

Depending on when you plan to submit, is it before 1st of Sep?

cdeil commented 6 years ago

is it before 1st of Sep?

Probably yes.

adl1995 commented 6 years ago

Thanks for the review.

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?

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:

Clone the openjournals/whedon repository in the same directory where paper.md is present.
Download this Makefile hosted GitHub gist (in the same directory as above) and run make, which executes a pandoc command.

Note: The above script might not work with older pandoc versions. I had to update to version 2.2.1. Also, I had to set --pdf-engine to pdflatex and commented the line --template "whedon/resources/latex.template", otherwise I was getting an error.

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.

cdeil commented 6 years ago

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 think they'll take up quite some space, so we should have that on the preview.

I'm not sure how much value the example and picture adds, i.e. whether we should keep or remove it. If we keep it, the quality needs to be improved, i.e. have the code example more nicely formatted as one code block, not inline, and have the Figure witout the white space at the edge, and drawing lines for the tile edges and maybe adding tile HEALPix numbers; this would then illustrate a bit what the package does, and not just show an astro image. Another example for a Figure could be a summary graphic of what the package does, ie. a server and arrow with "fetch" and then "draw", and for the other direction "make tiles", a bit similar to what I started in #44, but in a bit more detail: a single Figure which summarises the package visually.

@adl1995 - I think it's possible to have more files in the paper folder? So you could add the script to make the Figure here and we could start improving it?

@adl1995 - Are there any good examples of nice JOSS articles we should look?

cdeil commented 6 years ago

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.

adl1995 commented 6 years ago

@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

I think it's possible to have more files in the paper folder? So you could add the script to make the Figure here and we could start improving it?

Yes, the joss_paper folder can contain any files we require.

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.

cdeil commented 6 years ago

I would suggest you just commit the make file or whatever is needed to build the PDF to that folder. And also commit the latest PDF, the we always have it for review here. We can squash the commits or even remove the PDF if we want before merging this PR, but for now, it's nice to have.

The layout is very nice now. The references at the end and Axel, Brigitta as co-authors are still missing in the PDF.

cdeil commented 6 years ago

Suggest to mention and even cite both http://scikit-image.org/ and http://www.astropy.org/acknowledging.html (both papers).

adl1995 commented 6 years ago

@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 commented 6 years ago

I have a slight preference to not add the code example, but we could also keep it. @adl1995 and all - what is your preference?

Some more points:

suggest to move the Astropy and scikit-image mention from the acknowledgements to the main part of the paper. Just cite them where you explain how the package is implemented. Acknowledging GSoC is good, that belongs in the acknowledgements.
Figure needs a bit longer title, with one sentence stating something like Astronomical sky image made with the hips Python package and mention which survey is shown and that the grid shows the HiPS tiles fetched from CDS. It should be short, but some info about the image should be there for the people that don't read the text.
Mention that FITS, PNG and JPEG images are supported, and summarise that PNG and JPEG are usually for RGB color images and just display, but there is also FITS which can contain int or float data and is the professional astronomy image format standard?
Mention basic info that this is a pure Python package supporting 3.6 or later, runs on all OS, and maybe also mention that we use Pillow and aiohttp? See https://hips.readthedocs.io/en/latest/installation.html I don't mean write a lot of text, just ~ 2 sentences to summarise in the paper.
I think in the paper we could also explain the origin / timeline, i.e. that work on this started in early 2017, then there was v0.1 and v0.2 in summer 2017 and now a v0.3 in summer 2018 (let's decide to make the next v0.3 the release we describe in this paper).

bsipocz commented 6 years ago

I'm not super familiar with the customs of JOSS about code examples, but unless it's required I also prefer not to have one. The paper points to the documentation and that has up to date code examples that actually work with the given version, and that cannot be guaranteed for any such example added to the paper. Given the example produces the figure, the caption may point to a page in the docs that guaranteed to have that example.

I also agree with @cdeil's other points. In addition, you may also want to mention that hips is an astropy affiliated package.

adl1995 commented 6 years ago

@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.

bsipocz commented 6 years ago

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 hips.

adl1995 commented 6 years ago

@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?

cdeil commented 6 years ago

@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.

@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?

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)

adonath commented 6 years ago

@adl1995 Thanks for your work! My orcid is 0000-0003-4568-7005 or alternatively you can give me push access to this branch and I'll add it myself.

adl1995 commented 6 years ago

@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).

adl1995 commented 6 years ago

@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).

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)

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.

cdeil commented 6 years ago

@adl1995 - Can you please schedule the Google hangout for this? I'm mostly available, starting next Monday. I don't remember your time zone shift. For us in Europe, 9 am to 4 pm CEST are usually good slots to offer.

adl1995 commented 6 years ago

@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?

cdeil commented 6 years ago

@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.

adl1995 commented 6 years ago

@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.

bsipocz commented 6 years ago

@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).

tboch commented 6 years ago

@adl1995 I'll be on vacation next week. I won't be able to join you.

cdeil commented 6 years ago

@tboch - Are you available the week after? (July 30 to Aug 3)? That would work for me as well.

I think it's important to have @tboch in the call. And actually also @bmatthieu3 if possible. He hasn't committed to hipspy yet, but he's written mocpy with @tboch and we should use that soon in hipspy, e.g. to decide which tiles to fetch. Discussing the JOSS paper would probably only be a small part of the call, mainly I'd like to discuss the remaining work for hipspy v0.3 and get it done within the next weeks.

tboch commented 6 years ago

@cdeil - no, my earliest availability would be the week of August 13.

cdeil commented 6 years ago

@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 hipspy. That shows the power / real use case of this Python package, that one has full control / scriptability to make, fetch, draw HiPS, i.e. a case where one would actually use it instead of using Aladin or hipsgen. @adonath is working on this this week, so it depends on his time investment / progress in the next weeks if we change to that example in the JOSS paper. Anyways the text would only change by a few lines, it would remain a short summary.

tboch commented 6 years ago

@cdeil - Tomorrow July 19 between 2 and 3:30pm could work for me. In any case, I'll leave my comments by tomorrow evening.

tboch commented 6 years ago

My main remaining comment would be that I'd prefer if we change the example to Fermi-LAT and HiPS produced by hipspy. That shows the power / real use case of this Python package, that one has full control / scriptability to make, fetch, draw HiPS, i.e. a case where one would actually use it instead of using Aladin or hipsgen. @adonath is working on this this week, so it depends on his time investment / progress in the next weeks if we change to that example in the JOSS paper. Anyways the text would only change by a few lines, it would remain a short summary.

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.

tboch commented 6 years ago

@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 commented 6 years ago

@tboch - Thanks for the review! I have updated the summary section and tried to describe what the hips package does at the beginning. Updated PDF: paper.pdf

Please let me know if this can be further improved.

cdeil commented 5 years ago

@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.

hipspy / hips

Add JOSS article for hips package #125