The Stacker API

class stacker.Stacker

Class to generate stacked SEDs, save them as an stacked_seds xarray, and plot them.

column_histogram(label, bins, save=False)

Plots a histogram of a given column of the loaded catalog.

Plots a histogram of a given column of the loaded catalog, with a given uniform binning. A photometric catalog needs to have been loaded before. Will also return value and number of objects of the bin(s) with the least objects. Will be saved in stack_folder if the stacked_seds xarray has been saved, or in the working directory otherwise.

Parameters

label (str) – Label of the column to be used as data for the histogram.
bins (int or array_like) – Number of bins, or array_like with the bin edges.
save_plot (bool, optional) – Saves the plot as .png and .pdf in stack_folder (or working directory).

Returns

n_obj_min (int) – Number of objects in the bin with the least objects.
value_obj_min (float) – Mean value of the bin with the least objects.

define_aliases(alias_dict)

Defines the plotting aliases for catalog labels.

Defines the plotting aliases for catalog labels (e.g., zb, sfr_log, etc.) Will only be used for plotting, not filenames. Accepts LaTeX format.

Parameters: alias_dict (dict) – Dictionary of aliases. Keys are catalog column labels, values are the aliases. Not all the column labels need to be in the dictionary.
Return type: None.

load_catalog(cat_dir, max_nan_bands=0, z_label='zb', bands_data=None, bands_error_suffix='_error', flux_units='erg / (s cm2 nm)', wavelength_units='nm')

Loads a photometric galaxy catalog to stack.

Loads a photometric galaxy catalog to stack. The catalog must have exactly one row per object.

Parameters

cat_dir (str) – Directory of the catalog to be loaded.
max_nan_bands (int, optional) – Maximum number of NaN band fluxes that can be tolerated. Objects with more NaN bands will be removed from the catalog when loading. If inhomogeneous bands (broad and narrow) are present in the catalog, it is advisable to set it to 0. The default is 0.
z_label (str, optional) – The label of the redshift column to be used. The default is ‘zb’.
bands_data (dict or str, optional) – If dict, dictionary with photometric band wavelength data. Keys must be the column labels, values their average wavelengths. If str, directory of the .json file that contains all band response functions. The .json must contain a dictionary where the keys are the column labels of the catalog, and the values are the response functions. These must be specified as dictionaries with two elements: ‘response’ (list of the throughput) and ‘wavelength’ (list of the respective wavelengths). ‘wavelength’ does not need to be the same for all bands in the .json. Will use default PAUS average wavelengths if None. The default is None.
bands_error_suffix (str, optional) – Suffix to be appended to the band flux column labels in order to refer to the band flux error columns. The default is ‘_error’.
flux_units (str or astropy unit object, optional) – The units of the band fluxes. Assumed to be power*wavelength^-1*distance^-2, or energy*time^-1*wavelength^-1*distance^-2. If string, must be compatible with the astropy.units string format. The default is ‘erg / (s cm2 nm)’.
wavelength_units (str or astropy unit object, optional) – The wavelength units of the bands. If string, must be compatible with the astropy.units string format. Does not need to match the wavelength units of flux_units. The default is ‘nm’.

Return type

None.

load_stack(stack_folder)

Loads a stacked_seds xarray, previously saved as a netCDF file (.nc).

Parameters: stack_folder (str) – Directory of the stacked_seds xarray to be loaded.
Return type: None.

plot(line_label=None, column_label=None, row_label=None, counts=False, spectral_lines=False, logscale=False, wavelength_min=None, wavelength_max=None, aspect_ratio=1.62, fig_title=False, show=True, rc_params=None)

Plots the stacked SEDs from the stacked_seds xarray.

Plots the stacked SEDs from the stacked_seds xarray. All stacking bins will be plotted; the number of files generated will depend on the parameters. Filenames will be automatically generated.

If some labels or titles overlap or are cropped in the saved plots, testing different aspect_ratio values may solve it.

Parameters

line_label (str, optional) – Label of the binning that should be plotted as different lines in each axis. The default is None.
column_label (str, optional) – Label of the binning that should be displayed as different subplot columns in the figure. If specified and row_label = None, it will be be displayed in all subplots instead. The default is None.
row_label (str, optional) – Label of the binning that should be displayed as different subplot rows in the figure. If specified and column_label = None, it will be be displayed in all subplots instead. The default is None.
counts (bool, optional) – Display in the y-axis the number of galaxies stacked per wavelength grid point instead of the stacked fluxes. The default is False.
spectral_lines (bool or dict, optional) – If bool, decides if spectral lines must be marked or not in the plots. If dict, marks the spectral lines, but the provided dict values, instead of the default ones. (OII, OIII, Halpha, Hbeta). The dictionary keys must have LaTeX string format. The default is False.
logscale (bool, optional) – Display the y axes in logarithmic scale. Will raise an error if anything in the y axis has negative values. The default is False.
wavelength_min (float, optional) – Minimum wavelength to be plotted. Does not simply adjust the plot limits; the stacked SEDs will be cropped to wavelength_min, and then plotted. The default is None.
wavelength_max (float, optional) – Maximum wavelength to be plotted. Does not simply adjust the plot limits; the stacked SEDs will be cropped to wavelength_max, and then plotted. The default is None.
aspect_ratio (float, optional) – Aspect ratio of the subplots. The default is 1.62.
fig_title (bool, optional) – Add an automatically generated title to the figure, specifying all the bins that are not in line_label, column_label and/or row_label. The default is False.
show (bool, optional) – Show the plots once generated. The default is True.
rc_params (dict, optional) – Dictionary of parameters to pass to matplotlib.rcParams. Use it to modify the default plotting layout. The default is None.

Return type

None.

return_stack()

Returns the current ‘stacked_seds’

Returns: stacked_seds – The xarray object with the stacked_seds and all the relevant metadata.
Return type: xarray

save_stack(stack_folder, overwrite=False)

Saves the current stacked_seds as an xarray (netCDF file, .nc).

Parameters

stack_folder (str) – Directory of the stacked_seds xarray to be saved.
overwrite (bool, optional) – Overwrites without asking the stacked_seds.nc in the stacked_seds folder. Default is False.

Return type

None.

stack(bin_dict={}, weight=None, error_type=None, min_n_obj=0)

Stacks the rest-frame SEDs into the specified bins, and stores them.

Stacks the rest-frame SEDs into the specified bins by computing their averages, then stores them as a multi-dimensional and labelled xarray object (stacked_seds).

Parameters

bin_dict (dict, optional) – A dictionary specifying all the bins where the SEDs will be stacked. Each key must be a column label of the catalog, and each value a list of bin edges. These can be a list of continuous edges (with n_bins+1 elements), or a list of lists of length 2, where each sub-list contains the lower and upper edges of a given bin. Mixing both binning input types is accepted. If a key is composed of column_label + ‘%%’, the bin edges will be assumed to be percentiles. The trailing ‘%%’ will be removed before querying the dataframe. If a key is composed of column_label + ‘==’, the bins will be assumed to be discrete (i.e., each bin will be defined as bin_values == bin_edg, not bin_edg [n]<= bin_values < bin_edg [n+1]). Only a non-nested list of discrete bin values will be accepted in this case. The trailing ‘==’ will be removed before querying the dataframe. The default is {} (no binning, all SEDs stacked into one).
weight (str, optional) – Weighting to be used when stacking the SEDs. Can be ‘inv_variance’ or ‘snr_square’. The default is None.
error_type (str, optional) – The type of error of the stacked SEDs. Can be ‘flux_error’ (the propagated flux error of all stacked objects), ‘std’ (the standard deviation of the flux) or ‘std_mean’ (the standard deviation of the mean of the flux). The default is None.
min_n_obj (int, optional) – Minimum number of objects per wavelength point for a stack to be considered valid. Wavelengths with less objects will be masked. The default is 0.

Return type

None.

to_rest_frame(flux_conversion='normalized', use_band_responses=False, wl_rf_step=1, wl_obs_min=None, wl_obs_max=None, z_min=None, z_max=None, compute_error=True)

Shifts all band fluxes to rest frame, with a given unit conversion.

Shifts all band fluxes to rest frame, using a given unit conversion for the photometric fluxes.

Parameters

flux_conversion (str, optional) –
The unit conversion applied with the rest-frame shifting. Possible values are:
- ’normalized’: Normalized all SEDs so their integral is equal to their wavelength span.
- ’luminosity’: Converts from spectral flux density to spectral luminosity density by multiplying by 4pi*luminosity_distance^2.
- ’nothing’: Does not apply any unit conversion, shifts fluxes as they are in the catalog.
The default is ‘normalized’.
use_band_responses (bool, optional) – If True, will shift SEDs to the rest-frame wavelength grid using a sum weighted by the integral of the response functions. If False, will shift to the rest-frame grid applying linear interpolation (assuming each band flux is located exactly at the mean wavelength of the band). This is faster, but less accurate, and does not allow the use of a inhomogeneous set of bands (i.e., bands of significantly different FWHM, or bands with an irregular spectral coverage.) The default is False.
wl_rf_step (float, optional) – Step between points of the rest-frame uniform wavelength grid, in the specified wavelength units. The default is 1.
wl_obs_min (float, optional) – Minimum observed frame wavelength to be considered. If None, will be the smallest mean wavelength of the bands. The default is None.
wl_obs_max (float, optional) – Maximum observed frame wavelength to be considered. If None, will be the largest mean wavelength of the bands. The default is None.
z_min (float, optional) – Minimum redshift to be considered. If not given, will be the minimum redshift of the catalog.
z_max (float, optional.) – Maximum redshift to be considered. If not given, will be the maximum redshift of the catalog.
compute_error (bool, optional) – Determine if the error must be determined or not when shifting to rest frame. Setting it to False will significantly reduce computation time, but will not allow the use of any specific weighting or error-based shaded areas when running Stacker.stack() or Stacker.plot(). Default is True.

Return type

None.