Writing a JOSS paper

[dfm]

I've decided to write and submit a JOSS paper for exoplanet since the AAS Journals paper that I had been preparing was really taking too long. I'm hoping to write that up some day, but for now I think it's worth having a JOSS paper as a reference in the meantime. I've put together a first rough draft of the manuscript and I think that everything else is pretty much ready to go. So I'd like to open the floor for comments and co-authorship.

I'd like to invite everyone who has contributed code so far to exoplanet or any of the related projects (@arjunsavel, @rodluger, @iancze, @ericagol, @adrn, @christinahedges, @emilygilbert, @lgbouma, @mrtommyb, @t-brandt, @bmorris3, @barentsen, @jacksonloper, @dylex) to be a co-author (no contribution is too small!). Similarly, if you're seeing this through some other channel, I'd be happy to include anyone else who has made substantive contributions in other ways. Exactly how we'll select the order is TBD (suggestions welcome!) and no pressure if you'd rather not be a co-author.

If you would like to be a co-author, please do the following steps before May 5, 2021 or let me know if you need more time:

1. Take a look at the current draft (I will continue to make edits to it, but this will stay up to date): https://github.com/exoplanet-dev/exoplanet/blob/gh-pages/paper.pdf
2. Send comments (if you have any) via pull request to the joss branch, or as comments here
3. Add a comment in this thread saying that you would like to be a co-author with the following format:

   - name: Daniel Foreman-Mackey
     orcid: 0000-0002-9328-5652
     affiliation:
       - Center for Computational Astrophysics, Flatiron Institute, New York, NY
       - Other affiliations...
   

If I don't hear from you by May 5, I will follow up with you offline to make sure that you got this message, but please feel free to do this before then :D and let me know if you have any other comments or questions.

[mrtommyb]

Hi @dfm, I'm happy to be involved. I've taken a look at the draft. Obviously it's very barebones (following JOSS format), but I think you might want to be a bit more specific in places.
Obviously exoplanet has general applications to time series data but the primary purpose is to learn measure the physical properties of exoplanets, so I think that you might want to state that in the Summary and/or Statement of Need.

I think a little more discussion of the example use cases would be a benefit. So, I think laying the types of measurements that can be included (time-series photometry, time-series radial velocity measurements, and time series position data).

- name: Thomas Barclay
  orcid: 0000-0001-7139-2724
  affiliation:
    - University of Maryland Baltimore County, Baltimore, MD, USA

[ericagol]

Looking over list of comparison packages, here are a few others which I have seen get some use in recent literature (these may be 'trending'):

http://www.transits.hu

https://github.com/captain-exoplanet/misttborn

https://github.com/3fon3fonov/exostriker

https://github.com/oscaribv/pyaneti

https://github.com/hpparvi/PyTransit

[dfm]

@mrtommyb: good suggestions! I've added a little bit more about the specifics to the manuscript.

@ericagol: Thanks! I've added a few more and a disclaimer that the list is not comprehensive :D

[jiayindong]

- name: Jiayin Dong
  orcid: 0000-0002-3610-6953
  affiliation:
    - The Pennsylvania State University, University Park, PA
    - Center for Exoplanets & Habitable Worlds, 525 Davey Laboratory, The Pennsylvania State University, University Park, PA

[tagordon]

- name: Tyler A. Gordon
  orcid: 0000-0001-5253-1987
  affiliation:
    - Department of Astronomy, University of Washington, Box 351580, U.W., Seattle, WA 98195-1580, USA

[emilygilbert]

I'd love to be included, thanks! :D name: Emily A. Gilbert orcid: 0000-0002-0388-8004 affiliation: Department of Astronomy and Astrophysics, University of Chicago, 5640 S. Ellis Ave, Chicago, IL 60637, USA

…

On Fri, Apr 23, 2021 at 4:00 PM Tyler Gordon ***@***.***> wrote: - name: Tyler A. Gordon orcid: 0000-0001-5253-1987 affiliation: - Department of Astronomy, University of Washington, Box 351580, U.W., Seattle, WA 98195-1580, USA — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#174 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACBMLBVXY4RUDIR7OE3XSB3TKHGV3ANCNFSM43O6EFCA> .

[iancze]

I'd love to be involved, thanks!

- name: Ian Czekala
  orcid: 0000-0002-1483-8811
  affiliation: 
    - name: Department of Astronomy and Astrophysics, 525 Davey Laboratory, The Pennsylvania State University, University Park, PA 16802, USA
    - name: Center for Exoplanets and Habitable Worlds, 525 Davey Laboratory, The Pennsylvania State University, University Park, PA 16802, USA
    - name: Center for Astrostatistics, 525 Davey Laboratory, The Pennsylvania State University, University Park, PA 16802, USA
    - name: Institute for Computational \& Data Sciences, The Pennsylvania State University, University Park, PA 16802, USA

[arjunsavel]

Hi @dfm — thanks so much for including me! I've made a PR to the JOSS branch with some minor edits (#175).

- name: Arjun B. Savel
  orcid: 0000-0002-2454-768X
  affiliation:
    - Department of Astronomy, University of Maryland, College Park, MD 20742-0001, USA

[lgbouma]

Hi Dan, happy to be involved, and thank you for developing this awesome tool.

- name: Luke G. Bouma
  orcid: 0000-0002-0514-5538
  affiliation:
    - Department of Astrophysical Sciences, Princeton University, 4 Ivy Lane, Princeton, NJ 08540, USA

[danhey]

Hey Dan, thanks again :) The paper looks good!

- name: Daniel R Hey
  orcid: 0000-0003-3244-5357
  affiliation:
    - Sydney Institute for Astronomy (SIfA), School of Physics, University of Sydney, Camperdown, New South Wales, Australia
    - Stellar Astrophysics Centre, Department of Physics and Astronomy, Aarhus University, Aarhus, Denmark

[bmorris3]

This looks great, happy to help out any way I can.

  - name: Brett M. Morris
    orcid: 0000-0003-2528-3409
    affiliation:
        - Center for Space and Habitability, University of Bern, Gesellschaftsstrasse 6, CH-3012, Bern, Switzerland

[rodluger]

  - name: Rodrigo Luger
    orcid: 0000-0002-0296-3826
    affiliation: 
      - Center for Computational Astrophysics, Flatiron Institute, New York, NY
      - Virtual Planetary Laboratory, University of Washington, Seattle, WA

[christinahedges]

Hey Dan I'd love to be involved here are some v.small comments:

Summary

• In summary, you don’t mention that exoplanet is designed to focus on observations of exoplanets, while simultaneously mitigating stellar variability. This might show the skeptical reader one of the many reasons why exoplanet is unique at the very beginning.

Similar Tools

• One of your coauthors wrote the quite popular ktransit which could be mentioned in that list
• Starry is getting put in as a similar tool, but isn’t starry a dependency? (Is it an optional dependency?) Might be worth highlighting that as it's not just a similar tool
• In similar tools you say that exoplanet has differentiable components. Can you add a half sentence at the end saying that using modern inference algorithms that use this feature are better because ____. (speed?)

- name: Christina Hedges
  orcid: 0000-0002-3385-8391
  affiliation:
    - NASA Ames Research Center, Moffett Field, CA, 94035, USA
    - Bay Area Environmental Research Institute, P.O. Box 25, Moffett Field, CA 94035, USA

[dfm]

Thanks @christinahedges!

In summary, you don’t mention that exoplanet is designed to focus on observations of exoplanets, while simultaneously mitigating stellar variability. This might show the skeptical reader one of the many reasons why exoplanet is unique at the very beginning.

I'll add this - great suggestion!

One of your coauthors wrote the quite popular ktransit which could be mentioned in that list

I'll let @mrtommyb open a PR with a reference to ktransit if he thinks it would be suitable :D

Starry is getting put in as a similar tool, but isn’t starry a dependency? (Is it an optional dependency?) Might be worth highlighting that as it's not just a similar tool

starry is not a dependency - the algorithm is the same, but the implementations have actually diverged and they would generally be used for different use types of applications, so I think it's correct as written. @rodluger: what do you think?

In similar tools you say that exoplanet has differentiable components. Can you add a half sentence at the end saying that using modern inference algorithms that use this feature are better because ____. (speed?)

Good point! I'll try to be a little more specific, but I don't want to go into too many details since a detailed comparison would be subtle and beyond the scope. I think I can put in something reasonable!

[rodluger]

@christinahedges I agree with @dfm. The correct dependency is Eric Agol's modification of starry for efficient limb darkening light curves, which is mentioned under the exoplanet-core section.

[christinahedges]

@dfm @rodluger thanks that's great, sounds good. Paper is in really great shape already!

[trevordavid]

Thanks for including me @dfm! This has been a hugely useful tool for me. The paper looks great and I've sent you some really minor comments. I like the comment about stellar variability from @christinahedges too.

- name: Trevor J. David
  orcid: 0000-0001-6534-6246
  affiliation:
    - Center for Computational Astrophysics, Flatiron Institute, New York, NY 10010, USA
    - Department of Astrophysics, American Museum of Natural History, New York, NY 10024, USA

[t-brandt]

Thanks, Dan! One request I have is to reference 2017MNRAS.467.1702R for the Kepler solver, for example

... an efficient solver for Kepler's equation based on 2017MNRAS.467.1702R.

 - name: Timothy D. Brandt 
   orcid: 0000-0003-2630-8073
   affiliation: 
    - Department of Physics, University of California, Santa Barbara, Santa Barbara, CA 93106, USA

[dfm]

I've added that reference - thanks @t-brandt!

[adrn]

JOSS paper looks great to me! Thanks for the invitation

- name: Adrian M. Price-Whelan
  orcid: 0000-0003-0872-7098
  affiliation:
    - Center for Computational Astrophysics, Flatiron Institute, New York, NY 10010, USA

[dfm]

Hey team - thanks all for the comments, suggestions, and positive responses. Please feel free to send comments (up until next week: May 5) or add yourself as an author if you haven't already!

Re author order, in absence of a better method, I propose that we do: me, @rodluger, and then alphabetical after that. Please let me know (here or offline) if you you have concerns about that proposal or if you have a better idea. I'd be happy to adjust as necessary.

If you have already been included as an author, please check the current version of the manuscript to make sure that I got your name and affiliation right. I tried to be careful, but I normalized and rearranged the affiliations a little so I could well have messed it up. If I don't hear from you, I'll expect that you're happy with it.

[dfm]

@all: Quick final reminder that the deadline for comments is this Wednesday May 5. I'm planning on submitting to ArXiv and the journal at some point on Wednesday. Please let me know if that timing doesn't work for you and thanks again for all the edits and feedback so far!

[dfm]

The pre-review thread for this paper is now open over at JOSS: openjournals/joss-reviews#3256

And it should also be on this evening's ArXiv mailing. I'll email all the co-authors with the ArXiv info when I get it.

Thanks all!!