##############
Spectral utils
##############

The `madcubapy.utils` package offers a set of utils to perform operations on
spectra data.

Create spectral arrays
======================

The :func:`~madcubapy.utils.create_spectral_array` function creates an spectral
array by providing the following parameters:

* ``nchan`` : Number of channels in the spectrum.
* ``cdelt`` : Width of a channel.
* ``crpix`` : Reference channel of the spectrum.
* ``crval`` : Value of the reference channel.

.. code-block:: python

    >>> from madcubapy.utils import create_spectral_array
    >>> x_axis = create_spectral_array(nchan=5, cdelt=2, crpix=2, crval=10)
    >>> x_axis
    array([8, 10, 12, 14, 16])

Spectral data conversions
=========================

The user can convert between rest frequency, observed frequency, and velocity
using the predefined functions :func:`~madcubapy.utils.rest_to_obs`,
:func:`~madcubapy.utils.obs_to_rest`, :func:`~madcubapy.utils.obs_to_vel`,
:func:`~madcubapy.utils.vel_to_obs`, :func:`~madcubapy.utils.rest_to_vel`, and
:func:`~madcubapy.utils.vel_to_rest`. The user can use different conventions:

    - Radio         :math:`V = c \frac{f_0 - f}{f_0}  ;  f(V) = f_0 ( 1 - V/c )`
    - Relativistic  :math:`V = c \frac{f_0^2 - f^2}{f_0^2 + f^2} ;  f(V) = f_0 \frac{\left(1 - (V/c)^2\right)^{1/2}}{(1+V/c)}`
  
Here :math:`f_0` is the rest frequency, :math:`f` is the observed frequency,
and :math:`V` is the velocity.

For the input data, the functions accept single values and arrays of values,
which must be `~astropy.units.Quantity` objects. As an example, here is how to
convert observed frequency to velocity using
:func:`~madcubapy.utils.obs_to_vel`

.. code-block:: python

    >>> from madcubapy.utils import obs_to_vel
    >>> obs_freq_array = (263.35134466, 264.3413873) * u.GHz
    >>> line_rest_freq = 266 * u. GHz
    >>> velocity_array = obs_to_vel(obs_freq=obs_freq_array,
                                    doppler_rest=line_rest_freq,
                                    doppler_convention="relativistic")
    >>> velocity_array
    [3000, 1875.1495799 ] km / s

To avoid the use of several functions, `madcubapy.utils` also offers the
`~madcubapy.coordinates.SpectralData` class to work with spectral data with
units and automatically perform conversions between frequencies, wavelengths,
photon energies, and Doppler velocities. Check
:ref:`The SpectralData page<use_spectral_data>` to know more.

Spectral resolution units
=========================

The user can convert between the spectral resolution between Frequency and 
velocity units using the :func:`~madcubapy.utils.convert_spectral_resolution`
function.

SNR functions
=============

`madcubapy` offers functions to measure the signal-to-noise ratio of spectral
lines in various ways:

* :func:`~madcubapy.utils.measure_snr_peak` for a peak SNR measurement (peak
  intensity / rms).
* :func:`~madcubapy.utils.measure_snr_profile_fit` for a SNR integrating the
  emission of the line profile assuming a gaussian fit using the equation:
  (eq.1) 
* :func:`~madcubapy.utils.measure_snr_profile_observed` for a SNR integrating the
  emission along the line profile on the observed channels inside a selected
  window width. The function allows selecting a binary or fractional mask to
  handle the side channels. 

Similarly, `madcubapy.utils` also offers helpers to estimate the rms for a
desired SNR with the functions :func:`~madcubapy.utils.estimate_rms_peak` and 
:func:`~madcubapy.utils.estimate_rms_profile_fit`.