Rewrite paper, add community guidelines, clarify docs

MichielsenM · Feb 18, 2024 · f88ec05 · f88ec05
1 parent 7d36685
commit f88ec05
Show file tree

Hide file tree

Showing 8 changed files with 103 additions and 15 deletions.
diff --git a/docs/Guidelines.md b/docs/Guidelines.md
@@ -0,0 +1,28 @@
+---
+layout: default
+title: Community guidelines
+---
+# Vision
+
+Several tools have been developed for asteroseismic analyses, but many of them are closed-source and therefore inaccessible to the general astronomy community. Whereas some efforts have been made to provide publicly available open-source tools for asteroseismic modelling, these predominantly concern the analysis of solar-like oscillators. Foam tries to extend this effort to the modelling of gravity mode oscillators.
+
+# Contributing
+
+## Contribute to the software
+If you have features or other ideas you want to contribute to the code, please submit them as a pull request.
+If you're unsure about how to approach the implementation of your idea, feel free to contact [Mathias](mailto:michielsenmathias@gmail.com).
+
+## Report issues or bugs
+If you run into issues or bugs, you can [create an issue on github](https://github.com/MichielsenM/FOAM/issues). If you managed to find a solution, you're also welcome to create a pull request alongside the issue with a fix.
+
+## Questions or problems
+If you have specific questions or run into problems, you can contact [Mathias](mailto:michielsenmathias@gmail.com).
+
+
+## Collaborators
+
+Many thanks to these amazing collaborators that have helped with the development and/or testing of the software.
+
+Foam collaborators:
+- Timothy Van Reeth
+- Alex Kemp
diff --git a/docs/Installation.md b/docs/Installation.md
@@ -4,6 +4,8 @@ title: Installation
 ---
 # Installation
 
+Pleas note that FOAM was written and tested on Linux. The installation procedure was tested on MacOS, but the functionality was not as extensively tested as on Linux. No tests for Windows have been performed.
+
 ## Prerequisites
 FOAM is a python package which requires python 3.9 or newer, additionally the package uses <a href="https://python-poetry.org/docs/" target="_blank"> poetry</a> for dependency management. Follow their installation instructions to install poetry on your system as well.
 

diff --git a/docs/Pipeline.md b/docs/Pipeline.md
@@ -35,7 +35,7 @@ Each word in the filenames enclosed by {} indicates that it is replaced by a val
 </details>
 
 ### pipe0_extract_grid
-Extract all required information from the MESA profiles and GYRE summary files in the theoretical grids.
+Extract all required parameters and quantities from the MESA profiles and GYRE summary files in the theoretical grids.
 Requires the grids to be structured as explained in the [walkthrough](./Walkthrough.md).
 This step will be required once for a (group of) theoretical grid(s). Modelling different stars with the same theoretical grid will all use the same summary files that this step creates.
 
@@ -49,8 +49,8 @@ This step will be required once for a (group of) theoretical grid(s). Modelling
 </ul>
 </details>
 
-### pipe1_construct_pattern        
-Construct the theoretical pulsation patterns, optimise their rotation rates, select theoretical pulsation patterns matching the observational pattern, and merge with the models surface properties into one file.
+### pipe1_construct_pattern   
+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 into one file.
 <details>
 <summary> <b>Output</b> (click to expand) </summary> <br>
 
@@ -64,7 +64,7 @@ Creates folder <code>extracted_freqs/</code> to store
 After this step, subdirectories will be made in case the pipeline is ran for a nested grid where one or more free parameters are fixed to a certain value.
 
 ### pipe2_calculate_likelihood     
-Calculate the likelihood of all the theoretical patterns according to the specified merit functions.
+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. (See <code>observable_seismic</code> and <code>observable_additional</code> in the [pipeline configuration](./Configuration.md).)
 <details>
 <summary> <b>Output</b> (click to expand) </summary> <br>
 
@@ -80,7 +80,8 @@ Creates folder <code>meritvalues/</code> to store
 </details>
 
 ### pipe3_add_constraints
-Select all the models that fall inside an n-sigma error box on the provided Teff, logg and logL. If `n_sigma_box` in the configuration is set to None, this step will be skipped. If `constraint_companion` is also provided in the pipeline configuration, those constraints on a binary companion are also taken into account using isochrone-clouds. 
+Exclude all the models that fall outside an n-sigma error box on the spectroscopic and astrometric constraints as acceptable solutions.
+The models that fall inside the n-sigma error box on the provided Teff, logg and logL will be written into a new file. If `n_sigma_box` in the configuration is set to None, this step will be skipped. If `constraint_companion` is also provided in the pipeline configuration, those constraints on a binary companion are also taken into account using isochrone-clouds. 
 <details>
 <summary> <b>Isochrone-clouds</b> (click to expand) </summary> <br>
 An isochrone-cloud of a model is made up of all models that have the same metallicity, an age equal within 1 timestep, and whose mass is compatible within the error margin of the observed mass ratio. (However other parameters can differ between models, e.g. internal mixing processes).
@@ -102,8 +103,7 @@ The innermost dictionary will hold certain columns of MESA history files, effect
 </details>
 
 ### pipe4_AICc
-Calculate the <a href="https://en.wikipedia.org/wiki/Akaike_information_criterion" target="_blank"> Akaike information criterion (AIC)</a> corrected for small sample size (AICc).
-This AICc is calculated for the best model for each combination of modelling options.
+Calculate the <a href="https://en.wikipedia.org/wiki/Akaike_information_criterion" target="_blank"> Akaike information criterion (AIC)</a> corrected for small sample size (AICc). This AICc is calculated for the best model for each combination of modelling options. 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.
 <details>
 <summary> <b>Output</b> (click to expand) </summary> <br>
 

diff --git a/docs/Walkthrough.md b/docs/Walkthrough.md
@@ -213,7 +213,7 @@ Model_grids
 </details>
 
 
-## Example setup
+## Running an example setup
 
 A practical example of the setup can be found in the following directory <a href="https://github.com/MichielsenM/FOAM/tree/master/example_setup" target="_blank"> example_setup</a>.
 The folder `KIC7760680` contains an example of a file with observational data (<a href="https://github.com/MichielsenM/FOAM/blob/master/example_setup/KIC7760680/data_KIC7760680.tsv" target="_blank"> data_KIC7760680.tsv </a> ), and two setups for the modelling pipeline. One for modelling the full grid, and one setup to perform the modelling for a subgrid of nested models (in this case for both Convective Boundary Mixing parameters fixed at 0). Some print statements have been included to keep you informed how far the pipeline has progressed, but these can easily be removed or adjusted.

diff --git a/docs/_includes/nav.html b/docs/_includes/nav.html
@@ -5,4 +5,5 @@
   <a href="{{site.baseurl}}/Pipeline">Pipeline modules</a>
   <a href="{{site.baseurl}}/Configuration">Pipeline configuration</a>
   <a href="{{site.baseurl}}/Plottools">Plotting tools</a>
+  <a href="{{site.baseurl}}/Guidelines">Community guidelines</a>
 </div>
diff --git a/paper/example-modelling-output.png b/paper/example-modelling-output.png
diff --git a/paper/paper.bib b/paper/paper.bib
@@ -342,3 +342,37 @@ @ARTICLE{Jermyn2023
       adsnote = {Provided by the SAO/NASA Astrophysics Data System}
 }
 
+@article{Eckart1960,
+	author = "Eckart, G.",
+	doi = "10.1002/qj.49708938224",
+	issn = "1477-870X",
+	journal = "Hydrodynamics of oceans and atmospheres, Pergamon Press, Oxford",
+	title = "{Hydrodynamics of oceans and atmospheres}",
+	url = "http://dx.doi.org/10.1002/qj.49708938224",
+	year = "1960"
+}
+
+
+@ARTICLE{Townsend2020,
+       author = {{Townsend}, R.~H.~D.},
+        title = "{Improved asymptotic expressions for the eigenvalues of Laplace's tidal equations}",
+      journal = {\mnras},
+     keywords = {hydrodynamics, waves, methods: analytical, methods: numerical, stars: oscillations, stars: rotation, Astrophysics - Solar and Stellar Astrophysics, Mathematical Physics},
+         year = 2020,
+        month = sep,
+       volume = {497},
+       number = {3},
+        pages = {2670-2679},
+          doi = {10.1093/mnras/staa2159},
+archivePrefix = {arXiv},
+       eprint = {2006.12596},
+ primaryClass = {astro-ph.SR},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2020MNRAS.497.2670T},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@BOOK{Claeskens2008,
+	author = {{Claeskens}, G. and {Hjort}, N. L.},
+	title = "{Model Selection and Model Averaging, Cambridge Series in Statistical and Probabilistic Mathematics}",
+	year = 2008,
+}