This guide steps you through using spaxelsleuth with SAMI data, and are included in the series of example scripts and Jupyter notebooks that come pre-installed to help you get started:

• scripts/basic_sami_script.py - steps you through creating & loading the necessary DataFrames.
• examples/Examples - SAMI.ipynb - steps you through creating & loading the necessary DataFrames, plus demonstrates plotting capabilities.
• examples/Quick look plots - SAMI.ipynb - how to plot "summary" figures for SAMI galaxies.

The most basic way to use spaxelsleuth with SAMI data is as follows:

1. Download the SAMI data following the steps below.

2. Create a config file and save it as /path/to/config/file/.my_custom_config:

{
    "sami": {
        "output_path": "/some/path/spaxelsleuth_outputs/",
        "input_path": "/some/path/sami_data_products/",
        "data_cube_path": "/some/path/sami_data_cubes/"
    }
}

3. Load the config file:

from spaxelsleuth import load_user_config
load_user_config("/path/to/config/file/.my_custom_config.json")

4. Create the metadata DataFrame, which containts redshifts, stellar masses, and other "global" galaxy properties for each SAMI galaxy:

from spaxelsleuth.io.io import make_metadata_df
import os
make_metadata_df(survey="sami", nthreads=os.cpu_count())

5. Create the SAMI spaxel DataFrame:

from spaxelsleuth.io.io import make_df
DEBUG = True
make_df(survey="sami",
        bin_type="default", 
        ncomponents="recom", 
        eline_SNR_min=5, 
        eline_ANR_min=3, 
        correct_extinction=False,
        metallicity_diagnostics=["R23_KK04"],
        nthreads=nthreads,
        debug=DEBUG)

where DEBUG = True will cause make_df to run only on a subset of galaxies to save time (and disk space).

See the docstrings within for details on how to process data with different emission line fitting and/or binning schemes, how to apply different S/N cuts, etc. Note that you will need approximately 8 GB to store the DataFrame containing all SAMI galaxies.

5. Load the DataFrames:

from spaxelsleuth.io.io import load_df, load_metadata_df
df_metadata = load_metadata_df(survey="sami")
df, ss_params = load_df(survey="sami",
                ncomponents="recom",
                bin_type="default",
                eline_SNR_min=5,
                eline_ANR_min=3,
                correct_extinction=False,
                debug=DEBUG)

where df_metadata contains "metadata" (e.g. stellar masses, coordinates, redshifts) for each galaxy and should look like this:

and df is the DataFrame containing the spaxel-by-spaxel information for each galaxy and should look like this:

and ss_params is a Pandas Series containing the settings that were used to create the DataFrame:

6. Do your analysis - e.g., make some plots:

# Histograms showing the distribution in velocity dispersion
import matplotlib.pyplot as plt
from astropy.visualization import hist
fig, ax = plt.subplots(nrows=1, ncols=1)
for nn in range(1, 4):
    hist(df[f"sigma_gas (component {nn})"].values, bins="scott", ax=ax, range=(0, 500), density=True, histtype="step", label=f"Component {nn}")
ax.legend()
ax.set_xlabel(r"\sigma_{\rm gas}")
ax.set_ylabel(r"N (normalised)")


# Plot a 2D histogram showing the distribution of SAMI spaxels in the WHAN diagram
from spaxelsleuth.plotting.plottools import plot_empty_BPT_diagram, plot_BPT_lines
from spaxelsleuth.plotting.plotgalaxies import plot2dhistcontours, plot2dscatter
plot2dhistcontours(df=df,
              col_x=f"log N2 (total)",
              col_y=f"log HALPHA EW (total)",
              col_z="count", log_z=True,
              plot_colorbar=True)

Which (depending on the galaxies for which you have data) should produce the outputs

In order to use spaxelsleuth with SAMI data, the SAMI Data Release 3 data cubes and data products must be downloaded from the DataCentral Bulk Download page.

Here is the simplest way to download the data:

1. In Source List: leave blank to download the full SAMI sample, or enter the IDs of the subset of galaxies you would like to analyse.
2. In Data Release(s): select SAMI Data Release 3.
3. Leave Loose matching unchecked.
4. In Data products: Integral Field Spectra (IFS), select all by using ctrl+a or cmd+a.
5. Do not select anything in Data products: Spectra.
6. If you are not logged in to DataCentral, make sure to enter your email address in Email.

This will download all SAMI DR3 data products, including some that are not used (yet) by spaxelsleuth; however, this is much easier than manually selecting only the necessary data products. Note that the full list of files for each galaxy can exceed 100 MB, so you will need a lot of disk space to download the full data set for all 3068 SAMI galaxies!

When downloaded and unzipped, the data products for each galaxy will be organised into sub-folders with name

/sami/dr3/ifs/<gal>/

and will have the following naming convention:

• Unbinnned blue/red data cubes: <gal>_<A/B>_cube_<blue/red>.fits
• Binned blue/red data cubes: <gal>_<A/B>_<bin_type>_<blue/red>.fits
• Emission line flux maps: <gal>_<A/B>_<emission line>_<bin_type>_<ncomponents>-comp.fits
• Gas velociy map: <gal>_<A/B>_gas-velocity_<bin_type>_<ncomponents>-comp.fits
• Gas velocity dispersion map: <gal>_<A/B>_gas-vdisp_<bin_type>_<ncomponents>-comp.fits
• Stellar velocity dispersion map: <gal>_<A/B>_stellar-velocity-dispersion_<bin_type>_two-moment.fits
• Stellar velocity map: <gal>_<A/B>_stellar-velocity_<bin_type>_two-moment.fits
• Halpha extinction correction factor map: <gal>_<A/B>_extinct-corr_<bin_type>_<ncomponents>-comp.fits
• SFR surface density map: <gal>_<A/B>_sfr-dens_<bin_type>_<ncomponents>-comp.fits
• SFR map: <gal>_<A/B>_sfr_<bin_type>_<ncomponents>-comp.fits

For simplicity, spaxelsleuth assumes this default file structure when it searches for the files. To point spaxelsleuth to the right location, simply set settings["sami"]["input_path"] in your config file to the folder containing ifs/, i.e. /path/to/datacentral/data/sami/dr3/. Note that settings["sami"]["input_path"] and settings["sami"]["data_cube_path"] can be the same path.

SAMI galaxy "metadata", such as galaxy redshifts and stellar masses, is also required. For your convenience, this data is provided in data/, but may be downloaded in CSV format from the (DataCentral Schema)[https://datacentral.org.au/services/schema/] where they can be found under the following tabs:

• SAMI
  • Data Release 3
    • Catalogues
      • SAMI
        • CubeObs:
          • sami_CubeObs
        • Other
          • InputCatGAMADR3
          • InputCatClustersDR3
          • InputCatFiller
          • VisualMorphologyDR3

and stored in data/ using the naming convention

• sami_InputCatGAMADR3.csv
• sami_InputCatClustersDR3.csv
• sami_InputCatFiller.csv
• sami_VisualMorphologyDR3.csv
• sami_CubeObs.csv.

Using the DR3 CubeObs table as described in Croom et al. (2021), galaxies with bad sky subtraction residuals (as indicated by WARNSKYR and WARNSKYB), those with flux calibration issues (WARNFCAL and WARNFCBR), and those containing multiple objects in the SAMI field-of-view (WARNMULT) are removed, leaving 2997 unique galaxies.

• Distances are computed from the redshifts assuming a flat ΛCDM cosmology with H0 = 70 km/s/Mpc, ΩM = 0.3 and ΩΛ = 0.7. For the SAMI sample, the flow-corrected redshifts are used to compute distances when available.
• Morphologies are taken from the VisualMorphologyDR3 catalogue. For simplicity, the ?, No agreement and Unknown categories are all merged into a single category labelled Unknown.
• MGE effective radius measurements are taken from the MGEPhotomUnregDR3 catalogue. For galaxies for which measurements from both VST and SDSS photometry are available, only the VST measurements are kept.