LUCI: A Python package for SITELLE spectral analysis

High-resolution optical integral field units (IFUs) are rapidly expanding our knowledge of extragalactic emission nebulae in galaxies and galaxy clusters. By studying the spectra of these objects -- which include classic HII regions, supernova remnants, planetary nebulae, and cluster filaments -- we are able to constrain their kinematics (velocity and velocity dispersion). In conjunction with additional tools, such as the BPT diagram, we can further classify emission regions based on strong emission-line flux ratios. LUCI is a simple-to-use python module intended to facilitate the rapid analysis of IFU spectra. LUCI does this by integrating well-developed pre-existing python tools such as astropy and scipy with new machine learning tools for spectral analysis (Rhea et al. 2020). Furthermore, LUCI provides several easy-to-use tools to access and fit SITELLE data cubes.


STATEMENT OF NEED
Recent advances in the science and technology of integral field units (IFUs) have resulted in the creation of the highresolution, wide field-of-view (11 arcmin x 11 arcmin) instrument SITELLE (Drissen et al. 2019) at the Canada-France-Hawaii Telescope. Due to the large field-of-view and the small angular resolution of the pixels (0.32 arcseconds), the resulting data cubes contain over 4 million spectra. Therefore, a simple, fast, and adaptable fitting code is paramount -it is with this in mind that we created LUCI.

FUNCTIONALITY
At her heart, like any fitting software, LUCI is a collection of pre-processing and post-processing functions coupled with a fitting algorithm (in this case, a scipy.optimize.minimize function call) to extract information from a spectrum. That being said, LUCI is more than a simple wrapper for a fitting call.
Since SITELLE data cubes are available as HDF5 files, LUCI was built to parse the original file and create an instance of a LUCI cube which contains the 2D header information and a 3D NumPy array (spatial X, spatial Y, spectral). Once the data cube has been successfully converted to a LUCI cube, there are several options for fitting different regions of the cube (e.g., fit cube, fit entire cube, fit region) or fitting single spectra (e.g., fit spectrum region). The primary use case of LUCI is to fit a region of a cube defined either as a box (in this case, the user would employ the fit cube method and pass the limits of the bounding box) or to fit a region of the cube defined by a standard ds9 file (in this case, the user would pass the name of the region file to fit region). Regardless of the region being fit, the user needs only specify the lines they wish to fit, the fitting function, and the constraint relations between the lines.  Hα). The user chooses between three fitting functions: a pure Gaussian, and pure sinc function, or a sinc function convolved with a Gaussian (Martin et al. 2016). In either case, LUCI will solve for the three primary quantities of interest, which are the amplitude of the line, the position of the line (often described as the velocity and quoted in km/s), and the broadening of the line (often described as the velocity dispersion and quoted in units of km/s). LUCI's suite of post-processing tools allows us to extract kinematic parameters and line fluxes directly from these quantities.

Fitting Functions
The three fitting functions are mathematically described below where p 0 corresponds to the amplitude, p 1 corresponds to the line position, and p 2 corresponds of the broadening of the line.
The pure Gaussian function is expressed as The pure sinc function is expressed as The convolved sincgauss function is expressed as where x represents a given spectral channel, a = p2 where σ is the pre-defined width of the sinc function. We define this as σ = 1 2MPD where MPD is the maximum path difference. We note that erf is the error function.

Kinematic Equations
In each case, after solving for these values, the velocity and velocity dispersion (also called the broadening) are calculated using the following equations: where 3e5 represents the speed of light in kilometers per second, p 1 is p 1 in nanometers, and v 0 is the reference wavelength of the line in nanometers.
where again 3e5 represents the speed of light in kilometers per second.

Flux Equations
Similarly, we define the flux for each fitting function. Flux for a Gaussian Function: Flux for a sinc Function: Flux for a sincgauss Function:

Uncertainty Estimates
A full Bayesian approach is implemented in order to determine uncertainties on the three key fitting parameters (p 0 , p 1 , and p 2 ) using the emcee python package (Foreman-Mackey et al. 2013). It can be activated by added bayes bool=True to the argument of any fitting function. Thus, we are able to calculate posterior distributions for each parameter. There is a dedicated discussion to this in our online documentation. Additionally, LUCI can calculate the uncertainties by calculating the covariance matrix of the fit; this allows users to calculate uncertainties using a classical method by adding the argument uncertainty bool=True to any fitting function (again, there is a dedicated discussion on this calculation in our online documentation).

Installation, Documentation, & Examples
LUCI is available as an open-source software package on our GitHub page: https://github.com/crhea93/LUCI. Moreover, we have included, on this page, a detailed set of instructions to install and use the software package. We have included detailed documentation outlining the features of LUCI and the mathematics behind her at https: //crhea93.github.io/LUCI/index.html. On this site, we have included several key examples that can be adapted to any use-case of the software.

Other Software
Several fitting software packages exist for fitting generalized functions to optical spectra (such as astropy; Collaboration et al. 2013;Astropy Collaboration et al. 2018). Additionally, there exist software for fitting IFU datacubes for several instruments such as MUSE (Richard et al. 2012) and SITELLE (Martin et al. 2012). Although these are mature codes, we opted to write our own fitting package that is transparent to users and highly customize-able.