Contributing to TurbuStat¶
We welcome new contributions to TurbuStat!
To make changes to the source code, make a fork of the TurbuStat repository by pressing the button on the top right-hand side of the page. Changes to the code should be made in a new branch, pushed to your fork of the repository, and submitted with a pull request to the main TurbuStat repository. For more information and a detailed guide to using git, please see the astropy workflow page.
Contributing a new statistic or distance metric¶
Increasing the number of statistics implemented in TurbuStat is a key goal for the project. If you plan on providing a new implementation, the contribution should address the following criteria:
- Statistics and distance metrics should be a python class. A new folder can be added to the statistics folder for the new classes. Note that the new folder should contain an
__init__.pythe imports the statistic and/or distance metric classes (see here for an example). - Statistics should inherit from the BaseStatisticMixIn class. This mixin class handles unit conversions, extracts the required information from the FITS header, and allows the class to be saved and loaded.
- Statistic classes should accept the required data products in
__init__. At a minimum, the class should require the data and a FITS header. Other parameters that define the data or observed object (e.g., distance) can also be specified here. Functions within the class should take the data and compute the statistic. For example, the spectral correlation function (SCF) has separate function to create the SCF surface, to make an azimuthally-averaged spectrum, to fit two-dimensional and one-dimensional, and to make a summary plot. - All statistic classes should have a
runfunction that computes the statistic and optionally returns a summary plot (e.g., for the SCF). Therunfunction should use sensible defaults, but should have keyword arguments defined for the most important parameters. - Distance classes should accept the required data for two data sets in
__init__. The statistic class should be run on both data sets and keyword arguments should allow the important parameters to be passed to the statistic class (e.g., for the SCF distance). The distance class should then have adistance_metricfunction defined (for example) that computes the distance metric and optionally returns a summary plot of the statistic run on both of the data sets. - New statistics and distance metrics should have documentation explaining each argument, keyword argument, parameter, and function in the class. TurbuStat follows the astropy docstring rules.
- New statistics and distance metrics must have consistency tests. There are two types of consistency tests in TurbuStat: (i) Unit tests against the small test data included in the package (see here). An output from the statistic and distance metric is saved when the GetVals.py script is run. This type of test determines whether new additions to the code/updates the dependent package change the statistic’s output. (ii) Simple model tests where the statistic’s output is known. For example, the power-spectrum can be tested by generating an fBM image with a specified index (e.g., see this test).
- New statistics and distance metrics should have a tutorial for users (e.g., see this tutorial). Ideally, the tutorial will use the data sets already used in the TurbuStat tutorials. If these data are not useful for demonstrating the new statistic, we ask that the tutorial data be (i) small so the computation is relatively quick to run and (ii) publicly-available so users can reproduce the tutorial results.