GalSpecFitX

Full Spectrum Galaxy Fitting Software Utilizing STARBURST99 and BPASS stellar population models.

This software applies the Penalized PiXel-Fitting method (pPXF) created and distributed by Cappellari (2023), which extracts the stellar or gas kinematics and stellar population from galaxy spectra via full spectrum fitting using a maximum penalized likelihood approach. The GalSpecFitX software provides several routines for preparing galaxy data to ensure the highest efficiency with the fitting routine. It also provides additional enhancements such as Milky Way absorption line masking. A full suite of STARBURST99 and BPASS libraries have been included for compatible use with the software.

HOW TO RUN

1. Clone the GalSpecFitX repository.
2. In the GalSpecFitX root directory create a new Conda environment: conda env create -n galspecfitx
3. After creating and activating the environment run pip install . You should now be able to run the software by calling galspecfitx from the command line.
4. Create a directory for your galaxy data and copy over the 'config.ini' file from the GalSpecFitX root directory.
5. You can use this configuration file as a template and adjust the parameters accordingly (see the Configuration File Parameters and Spectral Fitting Parameters - Recommended sections below).
6. Command line options:

   galspecfitx [--options]
      galspecfitx --input_path --config_file --output_path
   
   options
      --input_path : Input path containing galaxy data. If not provided it is assumed to be located in the current directory. Please provide galaxy filename in your configuration file.
      --config_file : Configuration filename (default: config.ini). If it is not located in input_path please include the whole path to the file. E.g. /path/to/config.ini
      --output_path : Output path for results. If not provided results will be generated in input_path.
   

DATA PREPARATION

This software prepares a raw galaxy spectrum for spectral fitting by performing de-redshifting, binning, log re-binning and median normalization routines. This ensures the best compatibility with the fitting algorithm. Multiple spectra can be combined by creating an Astropy FITS table for each spectrum with columns 'wavelength', 'flux', and 'error'. Each table should then be stored in a separate hdu extension under one FITS file. Please provide a list of the extension numbers to the 'segments' parameter of your configuration file (e.g. 1,2,3,...). If multiple 'segments' are listed, the code will automatically combine the data into one combined spectrum ordered by smallest to largest wavelength before performing the fit.

Please see the example below for instructions on how to save your spectrum to an Astropy table and save it as a FITS file in Python.

from astropy.table import Table
from astropy.io import fits
import numpy as np

# Creating sample spectra

def create_sample_spectrum(lam_min, lam_max):
    wavelength = np.linspace(lam_min, lam_max, 1000)
    flux = np.random.random(1000)
    noise = np.full_like(flux, 0.05)
    return wavelength, flux, error

# Creating multiple spectra
spectrum1 = create_sample_data(4000, 5000)
spectrum2 = create_sample_data(5000, 6000)
spectrum3 = create_sample_data(6000, 7000)

# Create Astropy Tables
table1 = Table(spectrum1, names=('wavelength', 'flux', 'error'))
table2 = Table(spectrum2, names=('wavelength', 'flux', 'error'))
table3 = Table(spectrum3, names=('wavelength', 'flux', 'error'))

# Convert the tables to FITS HDUs and give them specific names
hdu1 = fits.BinTableHDU(table1, name='SPECTRUM1')
hdu2 = fits.BinTableHDU(table2, name='SPECTRUM2')
hdu3 = fits.BinTableHDU(table3, name='SPECTRUM3')

# Create a Primary HDU
primary_hdu = fits.PrimaryHDU()

# Create an HDU list with the primary HDU and the table HDUs:
hdul = fits.HDUList([primary_hdu, hdu1, hdu2, hdu3])

# Write the HDU list to a new FITS file
hdul.writeto('example_multiple_spectra.fits', overwrite=True)

NOTE: For HST/COS data the 'segments' parameter should be a list of the detector segments contained in an x1dsum.fits file (e.g. FUVA,FUVB).

Optional: Milky Way Absorption line masking

GalSpecFitX allows the user to mask parts of a spectrum containing milky way absorption lines and exclude them from the fit. This is NOT line subtraction. The original flux density of the spectrum remains preserved. Masking is done by fitting a single gaussian to a line at a given wavelength and finding its approximate width. The pixels within this range will simply not be included in the fit.

Configuration File Parameters

The software requires a configuration .ini file to run. The configuration file is divided into several sections, each of which contains specific parameters. Below is a breakdown of the required parameters for each section.

1. Settings Section

This section contains general settings related to the galaxy data processing.

Parameter	Type	Description
galaxy_filename	string	Name of the galaxy spectrum file.
use_hst_cos	bool	Whether to use HST/COS data (True or False).
segments	string	Comma-separated list of segments to process.
bin_width	int	Width for binning the galaxy spectrum.
default_noise	float	Default noise value for the galaxy spectrum.
z_guess	float	Initial guess for the redshift of the galaxy.

2. Instrument Section

This section contains information about the instrument used for the observations. Note: These parameters do not affect the continuum fit; they are exclusively used for emission line fitting and the absorption masking feature.

Parameter	Type	Description
FWHM_gal	float	Spectral resolution full width at half maximum (FWHM) in Angstroms.
or the following three parameters if FWHM_gal is not provided:
instr_lam_min	float	Minimum wavelength of the instrument in microns.
instr_lam_max	float	Maximum wavelength of the instrument in microns.
R	float	Resolving power of the instrument.

3. Library Section

This section defines the stellar population models used for fitting.

Parameter	Type	Description
lib_path	str/None	Path to library (BPASS or STARBURST99). If None or not provided only sample libraries are used.
Library	string	Name of the library for stellar population templates (STARBURST99 or BPASS).
evol_track	string	(Optional) Evolutionary track. Only applies to Starburst99 libraries. If not provided default is geneva_high.
IMF	string	Initial mass function (IMF) used in the library (See Accessing Libraries section).
star_form	string	Star formation model (See Accessing Libraries section).
age_min	float	(Optional) Minimum stellar population age for fitting (in Gyr).
age_max	float	(Optional) Maximum stellar population age for fitting (in Gyr).

4. Fit Section

This section contains additional parameters for customizing the fitting process. These parameters are optional and can vary depending on the user's needs. All available fitting parameters and default values are also listed in the provided config.ini template.

Parameter	Type	Description
start_stars	None/list	Initial kinematic parameters (velocity and sigma required in km/s) for stars; defaults are used if set to None.
start_gas	None/list	Initial kinematic parameters (velocity and sigma required in km/s) for gas; defaults are used if set to None.
bias	float	Optional bias term to control fit sensitivity; default is None.*
bounds_stars	None/list	Parameter bounds (e.g., min and max values) for fitting constraints in start_stars; default is None.
bounds_gas	None/list	Parameter bounds (e.g., min and max values) for fitting constraints in start_gas; default is None.
clean	bool	Enables outlier removal if True; default is False.
constr_templ	dict	Constraints applied to templates during fitting; default is None.*
constr_kinem	dict	Constraints on kinematic parameters (e.g., velocity); default is None.*
degree	int	Degree of additive polynomial for continuum fitting; default is 4. Set degree=-1 to not include any additive polynomial.
dust_stars	None/dict	Dust attenuation parameters for stars; default is None. {"start":..., "bounds":..., "fixed":...}
dust_gas	None/dict	Dust attenuation parameters for gas; default is None. {"start":..., "bounds":..., "fixed":...}
fixed_stars	None/list	Boolean vector set to True where a given kinematic parameter has to be held fixed with the value given in start_stars. This is a list with the same dimensions as start_stars.
fixed_gas	None/list	Boolean vector set to True where a given kinematic parameter has to be held fixed with the value given in start_gas. This is a list with the same dimensions as start_gas.
fraction	float	Ratio between stars and gas component.*
ftol	float	Tolerance level for fit convergence; default is 1e-4.
global_search**	bool or dict	Enables global optimization of the nonlinear parameters (kinematics) before starting the usual local optimizer.if True; default is False.
linear	bool	Only performs linear fitting if set to True; default is False.
linear_method	str	Method for linear fitting (options vary based on pPXF settings); default is lsq_box.
mask	None/list	List of wavelength ranges to exclude from fit; default is None (e.g. [[lam_i1, lam_f1], [lami2, lamf2], ...]
method	str	Algorithm to perform the non-linear minimization step (options vary based on pPXF settings); default is capfit.
mdegree	int	Degree of multiplicative polynomial for continuum fitting; default is 0.
quiet	bool	Suppresses verbose output of the best fitting parameters at the end of the fit if True; default is False.
absorp_lam	None/list	Absorption line central wavelengths for milky way line masking; default is None.
sigma_diff	float	Quadratic difference in km/s defined as: sigma_diff**2 = sigma_inst**2 - sigma_temp**2 between the instrumental dispersion of the galaxy spectrum and the instrumental dispersion of the template spectra.
trig	bool	Enables trigonometric series as an alternative to Legendre polynomials, for both the additive and multiplicative polynomials if True; default is False.
vsyst	float	Reference velocity in km/s; default is 0.0. Output will be w.r.t. this velocity.
x0	None	Initialization for linear solution; default is None.

---

*See pPXF documentation for further explanation on these parameters.
**Computationally intensive and generally unnecessary.

Spectral Fitting Parameters - Recommended

These are the parameters I recommend focusing on as they tend to have the greatest influence on the quality of the fit:

• start_stars: Initial guess for the LOSVD parameters (V, sigma, ...) for the stars component.
• start_gas: Initial guess for the LOSVD parameters (V, sigma, ...) for the gas component.
• Degree: Degree of the additive Legendre polynomial used to correct the template continuum shape during the fit. Set degree=-1 to not include any additive polynomial.
• Linear: If set to True only performs a linear least-squares routine for the templates and additive polynomial weights.

Accessing the Starburst99 and BPASS Libraries

After following the installation instructions you will have automatic access to the sample libraries located in the GalSpecFitX subfolder sample_libraries. The sample libraries provided are the Starburst99 Geneva High evolutionary track, Salpeter IMF for instantaneous star formation models, and BPASS Salpeter IMF (imf135all_100) single star formation models. The provided config.ini file uses these libraries by default by setting the lib_path parameter to None.

How to access the full suite of libraries using GIT LFS

The full suite of libraries although present in the root folder of the repository under full_suite will not be useable when you've first cloned the repository. Git Large File Storage (LFS) must be installed to fetch and download them. The first thing you will need to do is install Git LFS. If you have Homebrew you can do this by running:

brew install git-lfs or by way of one of the methods listed in the Git LFS docs.

Next, run git lfs install to initialize it.

Now you can download the models by running git lfs pull in the directory containing full_suite. WARNING: These libraries are LARGE, so if you would like to store the libraries somewhere with more storage space feel free to move the full_suite folder after downloading them.

Finally, all that needs to be done to start using the full suite is to direct the code to the directory via the lib_path parameter of your configuration file (e.g. lib_path=/path/to/full_suite). Now, you can explore all the models by choosing parameters based on the All Available Libraries section directly below.

All Available libraries

A full suite of STARBURST99 and BPASS are currently available, and are provided in the root directory of the repository. The table below identifies the full criteria and keywords for selecting a set of models in your configuration file based on parameters such as evolutionary track, IMF slopes, and type of star formation.

For Starburst99:

Evolutionary Track (evol_track)	Star Formation (star_form)	Initial Mass Function (IMF)
geneva_high -> Geneva tracks with high mass loss	inst -> Instantaneous	salpeter kroupa

For further explanation of these choices see: https://massivestars.stsci.edu/starburst99/docs/run.html#IZ

For BPASS:

Star Formation (star_form)	Initial Mass Function (IMF)
single binary	imf_chab100 imf_chab300 imf100_100 imf100_300 imf135_100 imf135_300 imf135all_100 imf170_100 imf170_300

For further explanation of these choices see the BPASS manual.

Output

Following a run of the GalSpecFitX software, the following outputs are produced:

Filename	Format	Description
bestfit.fits	FITS format	The galaxy spectrum after de-redshifting, binning, log-rebinning, and median normalization. The number of extensions corresponds to the number of segments with names PROCESSED_DATA_<segment>. The last extension contains the best fitting continuum to your combined galaxy spectrum with the name BESTFIT.
fitted_spectrum_static	PNG	Static plot of the best fitting solution and residuals.
interactive_fitted_spectrum	HTML	Interactive plot of the best fitting solution.
light_weights	PNG	The fraction of each model in the best-fit continuum, where model ages are plotted on the x-axis and model metallicities are provided in different colors. The best-fit age and metallicity are given in this plot.
normalized_log_rebinned_spectrum_<segment>	PNG and FITS Table	Plots of the galaxy spectrum after de-redshifting, binning, log-rebinning, and median normalization. The number of files corresponds to the number of segments.
<segment>_<absorp_wave>_masked	HTML	Plots of the masked absorption lines fit with a single gaussian. Check these plots to make sure the line widths are being well-approximated.
spectral_fitting.log	Log File	Log containing the input configuration file parameters and best fit parameters.