SPAN: SPectral ANalysis software V6.4
Daniele Gasparri, February 2025

### DataCube extraction ###

This module allows you to extract a series of n 1D spectra from a 3D FITS image (i.e., a datacube) following the GIST pipeline standard (Bittner et al., 2019).

The required parameters are the same as those used in the GIST pipeline. For more detailed information, please refer to the official GIST documentation. Below is a brief description of these parameters, along with newly implemented features.


Loading and verifying the datacube
The essential files and parameters required for this module to function correctly are highlighted in bold. The first step is to load a fully reduced, valid FITS datacube. Given the lack of a standardised convention for FITS keywords and data storage extensions, it is strongly recommended to use the "View datacube" button to verify that the datacube is correctly read.

This module has been tested with MUSE and CALIFA data formats. Other formats may only be partially supported. If at least the flux values are properly read, the "View datacube" button should display the image, though the wavelength slider in the Matplotlib window may show only a generic "Wavelength index" instead of actual wavelength values.

Once the datacube is correctly loaded, configure the following basic parameters:

- A run name (arbitrary).
- The source redshift (use zero if no de-redshifting is required).
- The wavelength range for extraction.
- Selecting the extraction routine

In the middle panel, choose the routine for reading and extracting the data. Pre-loaded routines are available for MUSE and CALIFA datacubes. Users can write their own extraction routines as .py files and save them in the span_functions/cube_extract_functions folder. The pre-loaded routines in this directory can be used as references.

Important: According to the GIST standard, when entering a routine name in the graphical interface, do not include the .py extension.

Additionally, configure the zero point for spatial coordinates. This is typically the center of the datacube's spatial axes but can also be set to the spaxel coordinates of the galaxy's center. The "View datacube" option is useful for retrieving this information.


Applying a spatial mask
In the final panel, locate the required "Select a FITS mask" field to browse and load a valid mask FITS file. This mask must have the same spatial dimensions as the datacube. If mask is not needed, simply leave this field empty.
If no mask is available but you need it, generate one by clicking "Generate mask". A Matplotlib window will open, displaying the datacube with a slider to navigate across wavelength indices (note: these are indices, not actual wavelengths!). 
To mask specific spaxels (e.g., to exclude sky regions), Ctrl+left-click to mask and Ctrl+right-click to unmask. You can also mask/unmask larger areas by clicking and dragging with the left or right mouse button. Ensure you remain within the plot boundaries while dragging, or the selection may not be applied.
Once satisfied, close the Matplotlib window. The mask will be automatically saved and ready to load in the "Select a FITS mask" field.
If you open the "Generate mask" window but no masking is needed, simply close the window. An unmasked file will be created automatically but it will not have effect of the DataCube.


Signal-to-Noise Masking and Binning
Optionally, you can:
- Mask spaxels with low S/N values by specifying a threshold.
- Bin contiguous spaxels using the Voronoi method to achieve the desired S/N or by manual selection. The manual bin selection lets you to have the full control on the spaxels to bin. By clicking to the "Manual binning" button, an iterative Matplotlib will appear showing your DataCube. You can select any region to be binned by Ctrl+left-click or dragging on the image. Deselecting can be performed by Ctrl+right-click or dragging. Once set your manual regions to be binned, close the matplotlib window. 

Whether applying the automatic Voronoi or manual rebinning, you can preview the results by clicking on the "Preview bins" button. If Voronoi binning is activated, you will see the Voronoi bins colour coded by their S/N. If Manual binning is activated, you will see the regions you selected that will be binned. In this case you will see still the single spaxels inside these regions, colour coded by their S/N.


Starting the Extraction
Once all parameters are set, click "Extract!"—and grab a coffee! The extraction process may take several minutes.

Upon completion, both GIST-standard and SPAN-standard spectra will be saved.

IMPORTANT: Once the extraction has been performed, any operation of the panel is locked until you will change the "Name of the run", including the preview. If you want to change any parameters and see the result, you MUST first change the "Name of the run". 