Using statistics classes

The statistics implemented in TurbuStat are python classes. This structure allows for derived properties to persist without having to manually carry them forward through each step.

Using most of the statistic classes will involved two steps:

1. Initialization – The data, relevant WCS information, and other unchanging properties (like the distance) are specified here. Some of the statistics calculated at specific scales (like Wavelet or SCF) can have those scales set here, too. Below is an example using Wavelet:

   >>> from turbustat.statistics import Wavelet
   >>> import numpy as np
   >>> from astropy.io import fits
   >>> from astropy.units import u
   >>> hdu = fits.open("file.fits")[0]  # doctest: +SKIP
   >>> spatial_scales = np.linspace(0.1, 1.0, 20) * u.pc   # doctest: +SKIP
   >>> wave = Wavelet(hdu, scales=spatial_scales,
   ...                distance=260 * u.pc)  # doctest: +SKIP
   

2. The run function – For most use-cases, the run function can be used to compute the statistic. All of the statistics have this function. It will compute the statistic, perform any relevant fitting, and optionally create a summary plot. The docstring for each of the run functions describe the parameters that can be changed from this function. The parameters that are critical to the behaviour of the statistic can all be set from run. Continuing with the Wavelet example from above, the run function is called as:

   >>> wave.run(verbose=True, xlow=0.2 * u.pc, xhigh=0.8 * u.pc)  # doctest: +SKIP
   

This function will run the wavelet transform and fit the relation between the given bounds (xlow and xhigh). With verbose=True, a summary plot is returned.

What if you need to set parameters not accessible from run? run wraps multiple steps in one function, however, the statistic can be run in steps when fine-tuning is needed for a particular data set. Each of the statistics has at least one computational step. For Wavelet, there are two steps: (1) computing the transform (compute_transform) and (2) fitting the log of the transform (fit_transform). Running these two functions is equivalent to using run.

The statistics also have plotting functions. From run, these functions are called whenever verbose=True is given. All of the plotting functions start with plot_; for Wavelet, the plotting function is plot_transform. Supplying a save_name to this function will save the figure, the x-units can also be set for spatial transforms (like the wavelet transform) as pixel, angular, or physical (when a distance is given) units, and additional arguments can be given to set the colours and markers used in the plot.

Statistic classes can also be saved or loaded as pickle files. Saving is performed with the save_results function:

>>> wave.save_results("wave_file.pkl", keep_data=False)  # doctest: +SKIP

Whether to include the data in saved file is set with keep_data. By default, the data is not saved to save storage space.

Note

If the statistic is not saved with the data, it cannot be recomputed after loading.

Loading the statistic from a saved file uses the load_results function:

>>> new_wave = Wavelet.load_results("wav_file.pkl")  # doctest: +SKIP

Unless the data is saved, everything but the data is new accessible from new_wave.