Merge pull request #75 from warrickball/editorial-tweaks-1

Some editorial tweaks for JOSS
MichielsenM · May 16, 2024 · 90c921e · 90c921e
2 parents 4ff88dd + 84f7fba
commit 90c921e
Show file tree

Hide file tree

Showing 2 changed files with 11 additions and 9 deletions.
diff --git a/paper/paper.bib b/paper/paper.bib
@@ -55,7 +55,8 @@ @BOOK{Aerts2010
 	title = "{Asteroseismology}",
 	booktitle = {Asteroseismology, Astronomy and Astrophysics Library. ISBN 978-1-4020-5178-4. Springer Science+Business Media B.V., 2010, p.},
 	year = "2010",
-	adsurl = {https://ui.adsabs.harvard.edu/\#abs/2010aste.book.....A},
+	doi = {10.1007/978-1-4020-5803-5},
+	adsurl = {https://ui.adsabs.harvard.edu/abs/2010aste.book.....A},
 	adsnote = {Provided by the SAO/NASA Astrophysics Data System},
 	publisher = {Springer, Astronomy and Astrophysics Library}
 }
@@ -375,4 +376,5 @@ @BOOK{Claeskens2008
 	author = {{Claeskens}, G. and {Hjort}, N. L.},
 	title = "{Model Selection and Model Averaging, Cambridge Series in Statistical and Probabilistic Mathematics}",
 	year = 2008,
-}
+	doi = {10.1017/CBO9780511790485}
+}
diff --git a/paper/paper.md b/paper/paper.md
@@ -3,12 +3,12 @@ title: 'Foam: A Python package for forward asteroseismic modelling of gravity mo
 tags:
   - Python
   - astronomy
-  - stellar astrophysics  
+  - stellar astrophysics
   - asteroseismology
 authors:
   - name: Mathias Michielsen
     orcid: 0000-0001-9097-3655
-    affiliation: 1 
+    affiliation: 1
 
 affiliations:
  - name: Institute of Astronomy, KU Leuven, Celestijnenlaan 200D, B-3001 Leuven, Belgium
@@ -20,7 +20,7 @@ bibliography: paper.bib
 # Summary
 
 Asteroseismology, the study of stellar pulsations, offers insights into the internal structures and evolution of stars. Analysing the variations in a star's brightness allows the determination of fundamental properties such as mass, radius, age, and chemical composition. Asteroseismology heavily relies on computational tools, but a significant number of them are closed-source, thus inaccessible to the broader astronomic community.
-This manuscript presents `Foam`, a python package designed to perform forward asteroseismic modelling of stars exhibiting gravity modes. It automates and streamlines a considerable fraction of the modelling process, comparing grids of theoretical stellar models and their oscillation frequencies to observed frequency sets in stars. 
+This manuscript presents `Foam`, a Python package designed to perform forward asteroseismic modelling of stars exhibiting gravity modes. It automates and streamlines a considerable fraction of the modelling process, comparing grids of theoretical stellar models and their oscillation frequencies to observed frequency sets in stars.
 
 `Foam` offers the flexibility to employ diverse modelling approaches, allowing users to choose different methodologies for matching theoretically predicted oscillations to observations. It provides options to utilise various sets of observables for comparison with their theoretical counterparts, employ different merit functions for assessing goodness of fit, and to incorporate nested subgrids in a statistically rigorous manner. For applications of these methodologies in modelling observed gravity modes, refer to @Michielsen2021 and @Michielsen2023.
 
@@ -40,17 +40,17 @@ Some tools have been developed and made publicly available to model and determin
 
 # Software package overview
 
-`Foam` is designed as a customisable pipeline. It will match theoretical models to observations, computing the goodness of fit of each model based on the selected merit function. Afterwards it will determine the best model alongside the uncertainty region of this solution based on statistical criteria. On the observational side, it will take a list of frequencies as an input, optionally complemented by additional information such as a set of surface properties (effective temperature, surface gravity, luminosity, element surface abundances...). On the theoretical side `Foam` will use a grid of theoretical stellar models, calculated by the user to suit their specific needs. Although the current implementation is made for a grid of stellar equilibrium models computed by `MESA`[@Paxton2011;@Paxton2013;@Paxton2015;@Paxton2018;@Paxton2019;@Jermyn2023], whose pulsation frequencies are computed with `GYRE`[@Townsend2013;@Townsend2018], the majority of the code is not inherently dependent on `MESA`. By making certain adjustments to the modelling pipeline, `Foam` could potentially employ grids generated by different stellar evolution codes. Some suggestions how to approach this are given in the description of [the theoretical model grid](https://michielsenm.github.io/FOAM/Walkthrough) in the online documentation. However, the implementation of such functionality currently remains out of the scope of the project.
+`Foam` is designed as a customisable pipeline. It will match theoretical models to observations, computing the goodness of fit of each model based on the selected merit function. Afterwards it will determine the best model alongside the uncertainty region of this solution based on statistical criteria. On the observational side, it will take a list of frequencies as an input, optionally complemented by additional information such as a set of surface properties (effective temperature, surface gravity, luminosity, element surface abundances...). On the theoretical side `Foam` will use a grid of theoretical stellar models, calculated by the user to suit their specific needs. Although the current implementation is made for a grid of stellar equilibrium models computed by `MESA` [@Paxton2011;@Paxton2013;@Paxton2015;@Paxton2018;@Paxton2019;@Jermyn2023], whose pulsation frequencies are computed with `GYRE` [@Townsend2013;@Townsend2018], the majority of the code is not inherently dependent on `MESA`. By making certain adjustments to the modelling pipeline, `Foam` could potentially employ grids generated by different stellar evolution codes. Some suggestions how to approach this are given in the description of [the theoretical model grid](https://michielsenm.github.io/FOAM/Walkthrough) in the online documentation. However, the implementation of such functionality currently remains out of the scope of the project.
 
-The script to run the pipeline can be altered in order to change the modelling approach you want to take. The various configuration options, the installation procedure, and a walkthrough of how to create your own modelling setup, are described in more detail in the [online documentation](https://michielsenm.github.io/FOAM). Although it relies on grids of stellar equilibrium models computed by `MESA` as the source of the theoretical model grid, `MESA`'s installation itself is not required for `Foam` to function. The installation of `GYRE` is however required, specifically since `Foam` relies on the `tar_fit.mX.kX.h5` files included in the `GYRE` installation. This allows us to rescale the g-modes for various stellar rotation rates, following the traditional approximation of rotation [e.g. @Eckart1960, see @Townsend2020 for its implementation in `GYRE`] and assuming rigid rotation. This facilitates computing the oscillation frequencies for the grid of stellar equilibrium models only once, and subsequently rescaling them to find the optimised rotation rate [see @Michielsen2023]. This approach avoids repeating the oscillation computations for a variety of rotation values, which would introduce extra dimensionality in the modelling problem in the form of adding the rotation rate as an additional free parameter.
+The script to run the pipeline can be altered in order to change the modelling approach you want to take. The various configuration options, the installation procedure, and a walkthrough of how to create your own modelling setup, are described in more detail in the [online documentation](https://michielsenm.github.io/FOAM). Although it relies on grids of stellar equilibrium models computed by `MESA` as the source of the theoretical model grid, `MESA`'s installation itself is not required for `Foam` to function. The installation of `GYRE` is however required, specifically since `Foam` relies on the `tar_fit.mX.kX.h5` files included in the `GYRE` installation. This allows us to rescale the g-modes for various stellar rotation rates, following the traditional approximation of rotation [e.g. @Eckart1960; see @Townsend2020 for its implementation in `GYRE`] and assuming rigid rotation. This facilitates computing the oscillation frequencies for the grid of stellar equilibrium models only once, and subsequently rescaling them to find the optimised rotation rate [see @Michielsen2023]. This approach avoids repeating the oscillation computations for a variety of rotation values, which would introduce extra dimensionality in the modelling problem in the form of adding the rotation rate as an additional free parameter.
 
 `Foam`'s modelling procedure can be broken down into following sequential [steps of the pipeline](https://michielsenm.github.io/FOAM/Pipeline):
 
  - Extract all required parameters and quantities from the files in the theoretical `MESA` and `GYRE` grids.
  - Construct the theoretical pulsation patterns for each stellar model. Thereafter select theoretical pulsation patterns matching the observational pattern whilst optimising their rotation rates. Finally combine this information with the models' surface properties.
  - Calculate the likelihood of all the theoretical patterns according to the specified merit functions and observables. This list of observables consist of the pulsations, but can optionally be extended with spectroscopic or astrometric information.
  - Exclude all the models that fall outside an n-sigma error box on the spectroscopic and astrometric constraints as acceptable solutions.
- - Calculate the Akaike information criterion (AIC) [@Claeskens2008] corrected for small sample size. This statistical criterion rewards goodness of fit, but penalises model complexity in the form of additional free parameters. The AIC thus allows a statistical comparison between models of different (nested) grids where the number of free parameters is not the same.
+ - Calculate the Akaike information criterion [AIC, @Claeskens2008] corrected for small sample size. This statistical criterion rewards goodness of fit, but penalises model complexity in the form of additional free parameters. The AIC thus allows a statistical comparison between models of different (nested) grids where the number of free parameters is not the same.
  - Calculate the 2 sigma uncertainty region of the maximum likelihood solution using Bayes’ theorem.
  - Make corner plots for all combinations of the different modelling choices (See \autoref{fig:cornerplot} for an example).
  - Construct a table with the best model of the grid for each combination of different modelling choices.
@@ -64,4 +64,4 @@ Next to the tables with the best model parameters and their AIC values, the corn
 The research leading to the development of this package has received funding from the Research
 Foundation Flanders (FWO) by means of a PhD scholarship to MM under project No. 11F7120N. MM is grateful to Timothy Van Reeth for his help concerning the scaling of g-modes with rotation, to Alex Kemp for his suggestions regarding the online documentation, and to the reviewers Ashley Chontos and Ankit Barik for their constructive remarks.
 
-# References
+# References