I did my best to make sure that this was consistent. It needs to be verified that Astropy refers to the project and \texttt{astropy} refers to the package.

• Any reason constructs like shown in line 11 page 11 (lasco_query.num_records()) don't use a more Python-like idiom, e.g.,len(lasco_query.records)
• There are sometimes details not explained in the examples. For example, line 23 on page 11. Probably some readers can figure out that the library is using this to construct the actual path for the files based on attributes in the object, but it may look a bit mysterious to others. Probably in this case a simple comment saying that this will result in files being moved into different directories according to the instrument and detector.
• Is there a need for a show() method (line 40, page 11)? Can __str__ or __repr__ serve as well?
• Is there an easy interactive means of displaying what two letter abbreviations are relevant (along with full descriptions). I'd say this issue also comes up elsewhere in wondering what introspective tools are generally available for seeing what the options are for queries and such).
• The term " a database supported by SQLAlchemy" on line 8 page 18 should probably say something like "can make use any database software supported by...". I draw a distinction between a database and the software used to create and access it.

• I'm curious why the Python indexing facility isn't used to select subimages (as illustrated in line 19 of page 5 and other places). It would seem the indexing scheme that Python provides would be a more natural way of creating subimages.

Typically, the instrument's paper is referenced when instruments are referenced for the first time. I can contribute some of these, but some I dont have.

ping @Cadair

It is important that \texttt{Map} be used carefully. It is the factory instance, not the type. map should likely be used to refer to the object in general, unless we want to refer to \texttt{MapBase} specifically.

• Please be consistent in either abbreviating or spelling out author first
  names in the list of references. If you abbreviate, do so either with a period
  or don't, but be consistent.

• Any reason constructs like shown in line 11 page 11 (lasco_query.num_records()) don't use a more Python-like idiom, e.g.,len(lasco_query.records)

On line 53 page 5 the pairs of objects CompositeMap and MapCube seem switched relative to the temporally and spatially aligned descriptions following (i.e., MapCube appears to be temporally ordered, and CompositeMap appears to be spatially aligned from later descriptions). But perhaps I misunderstand.

• The authors list a number of other software packages on p.3 of the
  manuscripts (e.g., pandas, astropy, etc), as well as later on in the paper,
  but they are not properly referenced. If, as I assume the authors will agree,
  we want to get to a community where publishing on software packages is given
  the appropriate credit, then I would encourage the authors to reciprocate and
  provide proper citations for the packages they use or reference in the paper.

I left a few comments throughout the document. Grep for RJH to find them. I've replicated their locations here:

1-Introduction.tex:24
2-1-Map.tex:27
2-1-Map.tex:119
2-2-Lightcurve.tex:21
2-3-Spectra.tex:38
3-3-HELIO.tex:61
3-3-HELIO.tex:64
5-Dev.tex:39
5-Dev.tex:41
6-Future.tex:9
solarsoft.tex:11
solarsoft.tex:72

I did a few greps on this, but it should be verified that i.e. and e.g. are used correctly.

1. i.e. is 'that is'
2. e.g. is 'for example'
3. A comma should follow them
4. This is a style thing, but I prefer them not italicised (some journals prefer the opposite). If they are italicised, it must be consistent.

I removed the italics and added the commas.

• It may be useful to explain how units are handled internally (e.g., are astropy units used? Or everything is converted to standard units.)

• The paper is good at providing an overview of what is available in
  SunPy. However, what I was really missing is a description of how this enables
  science. To this end, it would have been useful to provide a discussion of
  typical workflows in solar physics (i.e., what solar physicists do in their
  day to day science) and how these workflows are mapped on SunPy features. Even
  better, of course, would have been a description of workflows solar physicists
  would really like to do, that are currently too onerous but are now possible
  with SunPy.

• There are sometimes details not explained in the examples. For example, line 23 on page 11. Probably some readers can figure out that the library is using this to construct the actual path for the files based on attributes in the object, but it may look a bit mysterious to others. Probably in this case a simple comment saying that this will result in files being moved into different directories according to the instrument and detector.

pdflatex complains because the file 2-1-Map.tex attempts to include the file aia_map_example and it currently does not exist in this repo.

Either in the sections or at the end, but not both. At the end, or in a separate acknowledgement section, is ideal.

assigned to wafels, should be done by Sunday.

assigned to Aringlis

zenodo offers DOI numbering for code directly from the release in github. It even makes a nice and beautiful badge :)

I think this should be done once we got the paper done with the final release we are writing about.

I'm not sure what's the difference between zenodo or figshare... We could do either I assume. Zenodo is the product of a EU project and it has the data stored at the CERN facilities.

Can we use href (i.e. links) directly in the text?

In case anyone is still looking for it, here's a link to the PDF of the IOP Latex author guidelines:

https://dl.dropboxusercontent.com/u/59101674/IOPLaTeXGuidelines.pdf

I couldn't find anything more specific for the individual journal.

I removed the leading period from class attributes. This appears to be consistent with other python papers in this journal.

I also added parentheses at the end of function calls (which helps ID them as functions). It should be verified that none are missing.

• The term " a database supported by SQLAlchemy" on line 8 page 18 should probably say something like "can make use any database software supported by...". I draw a distinction between a database and the software used to create and access it.

Section headers need to be made consistent. Either capital letters or no. Also, no capitalizing prepositions and articles.

Mission/instruments need to either be capitalized or italicised consistently. This can be fixed when a decision is made. I think italics should go.

• The authors list a number of other software packages on p.3 of the manuscripts (e.g., pandas, astropy, etc), as well as later on in the paper, but they are not properly referenced. If, as I assume the authors will agree, we want to get to a community where publishing on software packages is given the appropriate credit, then I would encourage the authors to reciprocate and provide proper citations for the packages they use or reference in the paper.

Right now all the single open-quotes in the minted code blocks are actually displayed as close-quotes.

I tried replacing ' with ` in the TeX but this didn't render properly in the resulting PDF (a red box highlighted the quote symbol for some reason).

A quick search online didn't yield much. Any ideas?

• URLs move to inline text
• Get rid of all the comments

• It probably would be good to indicate if the convenience properties mentioned in line 11 of page 5 are kept in sync with corresponding values in the meta attribute. On the one hand, keeping these consistent automatically is a nice safety feature and prevents users from being surprised by discrepancies, on the other, doing so introduces complexity in the supporting software.
• I'm curious why the Python indexing facility isn't used to select subimages (as illustrated in line 19 of page 5 and other places). It would seem the indexing scheme that Python provides would be a more natural way of creating subimages.
• On line 53 page 5 the pairs of objects CompositeMap and MapCube seem switched relative to the temporally and spatially aligned descriptions following (i.e., MapCube appears to be temporally ordered, and CompositeMap appears to be spatially aligned from later descriptions). But perhaps I misunderstand.
• While the term "factory" is familiar to experienced Python users (line 55 page 7), I suspect is isn't so clear to more casual users. Perhaps a little more explanation is useful here.

• It probably would be good to indicate if the convenience properties mentioned in line 11 of page 5 are kept in sync with corresponding values in the meta attribute. On the one hand, keeping these consistent automatically is a nice safety feature and prevents users from being surprised by discrepancies, on the other, doing so introduces complexity in the supporting software.

I left a few [REF] blocks in the text were a reference should be.

Time passes and SunPy moves on, I suggest we try and update the manuscript as much as possible to be relevant to 0.5.0 and onwards.

• While the term "factory" is familiar to experienced Python users (line 55 page 7), I suspect is isn't so clear to more casual users. Perhaps a little more explanation is useful here.

Each section should be properly labelled, for example with:

\section{Maps}\label{sec:maps}
...
\subsection{submap}\label{ssec:smaps}
...

So we could write in a different sections something like

\section{Future}\label{sec:future}
... as seen in \s\ref{sec:maps} ...

slocount $$$ and lines of code is a dubious measure. If it is used, be sure that docs and comments are ignored (or should they be?). I don't think it should be used, personally.

• Is there an easy interactive means of displaying what two letter abbreviations are relevant (along with full descriptions). I'd say this issue also comes up elsewhere in wondering what introspective tools are generally available for seeing what the options are for queries and such).

• Is there a need for a show() method (line 40, page 11)? Can __str__ or __repr__ serve as well?

• The paper is good at providing an overview of what is available in
  SunPy. However, what I was really missing is a description of how this enables
  science. To this end, it would have been useful to provide a discussion of
  typical workflows in solar physics (i.e., what solar physicists do in their
  day to day science) and how these workflows are mapped on SunPy features. Even
  better, of course, would have been a description of workflows solar physicists
  would really like to do, that are currently too onerous but are now possible
  with SunPy.
• The authors list a number of other software packages on p.3 of the
  manuscripts (e.g., pandas, astropy, etc), as well as later on in the paper,
  but they are not properly referenced. If, as I assume the authors will agree,
  we want to get to a community where publishing on software packages is given
  the appropriate credit, then I would encourage the authors to reciprocate and
  provide proper citations for the packages they use or reference in the paper.
• Please be consistent in either abbreviating or spelling out author first
  names in the list of references. If you abbreviate, do so either with a period
  or don't, but be consistent.
• It may be useful to explain how units are handled internally (e.g., are astropy units used? Or everything is converted to standard units.)

The main file contains labels after the inputs... this would produce that the labels links to the last subsection or figure in these files and not the section itself. They should go just after the \section{} command.

\section{blah}\label{sec:blah}