Merge pull request #157 from ehsteve/final-fixes

W.I.P: Final edits

main.tex

@@ -11,7 +11,7 @@
 
 \newcommand{\package}[1]{\texttt{#1}\xspace}
 \newcommand{\code}[1]{\texttt{#1}\xspace}
-\newcommand{\github}{GitHub}
+\newcommand{\github}{GitHub\xspace}
 \newcommand{\git}{\code{git}}
 \newcommand{\python}{\package{Python}}
 

sections/0-abstract.tex

@@ -1,5 +1,5 @@
 \begin{abstract}
-    The \sunpyproj facilitates and promotes the use and development of several community-led, free, and open-source data analysis software packages for solar physics based on the scientific \python environment.
+    The goal of the \sunpyproj is to facilitates and promote the use and development of community-led, free, and open-source data analysis software for solar physics based on the scientific \python environment.
     The project achieves this goal by developing and maintaining the \sunpypkg core package and supporting an ecosystem of affiliated packages.
     This paper describes the first official stable release (version 1.0) of the core package, as well as the project organization and infrastructure.
     This paper concludes with a discussion of the future of the \sunpyproj.

sections/1-introduction.tex

@@ -17,7 +17,7 @@ \section{Introduction}
 
 The choice of \python was motivated by several different factors.
 The scientific \python ecosystem provides a rich and mature ecosystem of packages for performing scientific analysis and computation.
-It is supported by foundational packages for manipulating tabular \citep[\pandaspkg,][]{pandas} and multi-dimensional array \citep[\numpypkg,][]{numpy} data, general purpose scientific computing \citep[\scipypkg,][]{scipy}, and publication-quality 2D plotting \citep[\matplotlibpkg,][]{matplotlib}\footnote{According to the The 2018 Python Developers Survey \url{https://www.jetbrains.com/research/python-developers-survey-2018/}, data analysis is the primary use for \python thanks to the broad functionality provided by these foundational packages.}
+It is supported by foundational packages for manipulating tabular \citep[\pandaspkg,][]{pandas} and multi-dimensional array \citep[\numpypkg,][]{numpy} data, general purpose scientific computing \citep[\scipypkg,][]{scipy}, and publication-quality 2D plotting \citep[\matplotlibpkg,][]{matplotlib}\footnote{According to the The 2018 Python Developers Survey \url{https://www.jetbrains.com/research/python-developers-survey-2018/}, data analysis is the primary use for \python thanks to the broad functionality provided by these foundational packages.}.
 These core packages form the backbone of hundreds of additional scientific \python packages, such as \astropypkg for functionality and tools specific to astronomy, \package{scikit-learn} for machine learning and data mining \citep{pedregosa11}, and \package{dask} for parallel and distributed computing \citep{rocklin15}.
 Interoperability between all these packages enables interdisciplinary analysis across traditional fields of study including solar physics, space physics, and astrophysics.
 
@@ -26,16 +26,16 @@ \section{Introduction}
 Therefore, early career members of the solar physics community will likely already know how to code in \python.
 
 Finally, an important cultural factor motivated the adoption of \python.
-\python and many \python packages are open-source and developed under an OSI-approved open source license.
+\python and many \python packages are open-source and developed under open source licenses approved by the Open Source Initiative\footnote{\url{https://opensource.org/licenses}}.
 The \python developer community has embraced an inclusive and open development culture, which means that anyone is welcome to develop functionality to either enhance existing packages such as \sunpypkg or create new ones (see Section \ref{sec:development}).
 This means one given person or institution does not control the development of scientific \python software.
 This approach, combined with strict version control, allows scientists to create fully reproducible results.
 
 For all these reasons, the scientific \python ecosystem played a key role in recent major scientific discoveries, such as the first detection of a gravitational wave \citep{ligo_scientific_collaboration_and_virgo_collaboration_observation_2016} and the first image of a black hole \citep{collaboration_first_2019}.
 The data and code used to generate these results are openly available, allowing anyone to reproduce them.
-Because the solar community is relatively small\footnote{For reference, out of the $\sim$9,500 members of the American Astronomy Society, approximately 500 are members of the society's Solar Physics Division.} in relation to other scientific communities, it will benefit immensely by leveraging the \python scientific ecosystem to solve increasingly difficult scientific challenges and produce world-class science.
+Because the solar community is relatively small\footnote{For reference, out of the $\sim$9,500 members of the American Astronomy Society, approximately 500 are members of the society's Solar Physics Division.} in relation to other scientific communities, it will benefit immensely by leveraging the scientific \python ecosystem to solve increasingly difficult scientific challenges and produce world-class science.
 
 This paper describes the first stable release (version 1.0) of the \sunpypkg core package.
 A previous paper describes version 0.5 \citep{Community:2015cy}.
 This article is not meant to replace the \sunpypkg documentation but provides an overview of the organization and highlights important functionality.
-The full text of the paper, including all of the code to produce the figures, is available in a \github\, repository\footnote{\url{https://github.com/sunpy/sunpy-1.0-paper}}.
+The full text of the paper, including all of the code to produce the figures, is available in a \github repository\footnote{\url{https://github.com/sunpy/sunpy-1.0-paper}}.

sections/10-community.tex

@@ -1,7 +1,7 @@
 \section{Community}
 \label{sec:community}
 
-As discussed in \citet{bangerth2013}, a vital component to the long-term success of a project requires building a healthy community of users, developers, and maintainers.
+As discussed in \citet{bangerth2013}, a vital component to the long-term success of a project is building a healthy community of users, developers, and maintainers.
 The \sunpyproj has taken a number of steps to nurture and grow the SunPy community.
 We have adopted and enforce a formal code of conduct\footnote{\url{https://docs.sunpy.org/en/stable/code_of_conduct.html}} that strives to foster an open, considerate, and respectful environment for all.
 Additionally, we maintain a number of active communication channels including mailing lists, real-time chats based on the open source Matrix protocol\footnote{\url{https://matrix.org}}, and weekly teleconferences.

sections/11-infrastructure.tex

@@ -42,4 +42,4 @@ \subsection{Documentation and Gallery}
 This system supports using plain text files with a markup language called \code{reStructuredText}.
 The build process converts these files, including documentation strings in \python files, into HTML, PDF, or \LaTeX\ documents.
 We make use of the \code{sphinx-gallery}\footnote{\url{https://sphinx-gallery.github.io}} extension to build a gallery of analysis examples and the \code{sphinx-automodapi}\footnote{\url{https://sphinx-automapi.readthedocs.io}} extension to generate documentation pages that list all of the available classes, functions, and attributes.
-Our online documentation\footnote{\url{http://docs.sunpy.org/en/stable/}} is automatically built and hosted on Read the Docs\footnote{\url{https://readthedocs.org/}} for all releases.
+Our online documentation\footnote{\url{http://docs.sunpy.org/en/stable/}} is automatically built and hosted on Read the Docs\footnote{\url{https://readthedocs.org/}} for all releases and the latest code base.

sections/12-future.tex

@@ -13,9 +13,9 @@ \section{Conclusion}
 There are a number of obstacles to the continued growth and success of the project.
 The project does not yet have any significant and long-term funding stream.
 In addition to that challenge, the current team of core developers is relatively small, which translates to an unhealthy dependence on key developers.
-A significant obstacle to the growth of the core developer team is the low familiarity of modern coding best practices in the solar community.
-Core developers must be knowledgeable of version control, code refactoring for public use, good user documentation, and unit testing.
-It can take considerable effort to provide new contributors with the appropriate guidance and training.
+A significant obstacle to the growth of the core developer team is the low familiarity of modern software engineering best practices in the solar community.
+Core developers of \sunpypkg or affiliated packages must be knowledgeable of version control, code refactoring for public use, good user documentation, and unit testing.
+It takes considerable effort to provide new contributors with the appropriate guidance and training.
 The \sunpyproj is considering a number of ways to address this issue, including providing webinars, internship opportunities, and improving online documentation.
 
 The \sunpyproj is now a member of the Python in Heliophysics Community\footnote{\url{heliopython.org}}, whose members contribute to a collection of over fifty \python packages that span every sub-discipline within heliophysics.

sections/13-acknowledgements.tex

@@ -1,7 +1,7 @@
 \acknowledgments
 
 We thank the members of the community that have contributed to the \sunpyproj, that have opened issues and provided feedback, and have supported the project in a number of other ways.
-Additionally, we thank Brian Dennis, Richard Schwartz, and William Thompson whose comments greatly improved this manuscript.
+Additionally, we thank Brian Dennis, Richard Schwartz, and William Thompson whose comments and discussion greatly improved this manuscript.
 
 The following individuals recognize support for their personal contributions.
 BMS is supported by the NSF grant AST-1715122 and acknowledges support from the DIRAC Institute in the Department of Astronomy at the University of Washington.

sections/4-development.tex

@@ -2,7 +2,7 @@ \section{Development Model}
 \label{sec:development}
 
 To satisfy the mission of the Project, the SunPy community adopted an open development model, which is widely used within the scientific \python community.
-The \sunpypkg package is hosted on \github\, and uses \code{git}\footnote{\url{https://git-scm.com/}} as its distributed version control software.
+The \sunpypkg package is hosted on \github and uses \code{git}\footnote{\url{https://git-scm.com/}} as its distributed version control software.
 The entire code base is publicly available and anyone can suggest changes through pull requests.
 Since the code base is licensed under a permissive 2-clause BSD license\footnote{\url{https://opensource.org/licenses/BSD-2-Clause}}, anyone can redistribute, improve, repackage or use it in a closed environment as long as they credit the SunPy developers and redistribute the license.
 In order to maintain high-quality code, every contribution is reviewed and must satisfy the following requirements:
@@ -17,7 +17,7 @@ \section{Development Model}
 As of version 1.0, \sunpypkg consists of 48,427 lines of code\footnote{This number includes documentation and comments.
 There are 30,906 lines of code if documentation and comments are not counted.} contributed by 123 unique contributors with over 11,659 commits\footnote{A commit is a set of one or more modifications to the code base, with an associated description, and typically created by a single contributor.}.
 The leftmost panel of \autoref{fig:metafig} shows the steady growth of the code base since 2011 with, on average, approximately 16 lines added per day.
-A large reduction in the code base occurred after the release of 0.9, primarily due to the deletion of unused code and the removal of Python 2 support.
+A large reduction in the code base occurred after the release of version 0.9, primarily due to the deletion of unused code and the removal of \python 2 support.
 
 The middle panel of \autoref{fig:metafig} shows the steady rise in the number of unique contributors with, on average, more than one new contributor added each month.
 The total number of contributors is large for a package of this size in the heliophysics community \citep{pyhc2018}.

sections/5-modules.tex

@@ -1,7 +1,7 @@
 \subsection{Data Types}
 \label{sec:data_types}
 
-The \sunpypkg package provides two core data types that are designed to provide a general, standard, and consistent interface for loading and representing solar data across different instruments and missions.
+The \sunpypkg package provides core data types that are designed to provide a general, standard, and consistent interface for loading and representing solar data across different instruments and missions.
 The two core data types currently supported in \sunpypkg are handled by \Timeseries and \Map, objects that support 1D temporal data and 2D image data, respectively.
 The purpose of these core classes is to standardize data structures regardless of the data source (e.g., observational data from independent instruments).
 The classes maintain a consistent interface for accessing data attributes such as the data array itself as well as the metadata and relevant units.
@@ -99,7 +99,7 @@ \subsubsection{\Map}
 
 The \Map class in \sunpypkg provides a framework to contain and analyze image data.
 A \Map can be created from local files or using a URL to a remote data file.
-The \Map class will automatically detect the instrument and parse the metadata to infer the coordinate system from the appropriate Flexible Image Transport System (FITS) keywords \citep{refId0, 2006A&A...449..791T}.
+The \Map class will automatically detect supported instruments and parse the metadata to infer the coordinate system from the appropriate Flexible Image Transport System (FITS) keywords \citep{refId0, 2006A&A...449..791T}.
 Other source-specific metadata is used to determine the appropriate color table and image normalization for visualization.
 It is also possible to create a custom \Map by providing a 2D data array and metadata.
 

sections/6-coordinates.tex

@@ -17,7 +17,7 @@ \subsection{Solar Coordinates}
 The observer-independent coordinate frames (HAE, HEEQ, HGC, and HGS) are useful for specifying the locations of features on the Sun or objects (e.g., spacecraft) in interplanetary space.
 The commonly-used HGS frame is of particular note because it transforms in a straightforward manner to and from the Heliocentric Celestial Reference System (HCRS).
 This reference frame consists of the combination of two rotation angles: the time-independent angle between the Sun's rotation axis and the HCRS celestial pole \citep[see][]{2007CeMDA..98..155S} and the time-dependent angle of the Sun's central meridian (as seen from Earth) relative to the vernal equinox.
-The transformation provides the link from the frames defined in \package{sunpy.coordinates} with those defined in \package{astropy.coordinates}, allowing any solar frame to be transformed to and from celestial coordinate frames (see \autoref{fig:transform_graph}).
+This transformation provides the link from the frames defined in \package{sunpy.coordinates} with those defined in \package{astropy.coordinates}, allowing any solar frame to be transformed to and from celestial coordinate frames (see \autoref{fig:transform_graph}).
 The functionality provided by the \package{sunpy.coordinates} subpackage has been extensively tested and agrees with published values in the \textit{Astronomical Almanac}.
 For example, the apparent right ascension of the Sun agrees to a precision of 0.01 arcsecond.
 

sections/9-affiliated.tex

@@ -10,7 +10,7 @@ \section{Affiliated Packages}
     \item Documentation must be provided that explains the function and use of the package, and should be of comparable quality to \sunpypkg documentation.
     \item A test suite must be provided to verify the correct operation of the package.
 \end{itemize}
-For a package to become an affiliated package, developers can apply to the lead developer, and the SunPy board provides the final approval.
+For a package to become affiliated, developers can apply to the lead developer, and the SunPy board provides the final approval.
 Packages are re-reviewed on a yearly basis to ensure that they continue to meet the standards.
 To aid discoverability, all affiliated packages are listed on the SunPy website\footnote{\url{https://sunpy.org/team\#affiliated-packages}}, and they are advertised at national and international conferences and workshops.
 Finally, the development of these packages is provided informal support by the SunPy developer community, and