Analysis

Classes related to results analysis.

API

Classes:

Analysis(config[, model, kin_set])	Class to hold results' analysis methods.
Decomposition([config, model, ocut, names, ...])	Class for decomposition.

class analysis.Analysis(config, model=None, kin_set=0)

Class to hold results’ analysis methods.

This class contains methods that help analyzing DYNAMITE results and can be called, e.g. by plotting routines.

Parameters:

configa dyn.config_reader.Configuration object

modela dyn.model.Model object, optional, default: best model so far

kin_setint, optional, default: 0

Methods:

get_gh_model_kinematic_maps([model, ...])	Generates an astropy table that holds the model's data for creating Gauss-Hermite kinematic maps: flux, v, sigma, h3 .
get_orbit_bundle_maps([model, kin_set, ...])	Generates an astropy table that holds the weight-contribution of the orbit bundles defined in bundle_mapping to the model's projected mass in each aperture.

get_gh_model_kinematic_maps(model=None, kin_set=None, v_sigma_option='fit', kinematics_as='table', weights=None)

Generates an astropy table that holds the model’s data for creating Gauss-Hermite kinematic maps: flux, v, sigma, h3 … h<number_GH>. v and sigma are either directly calculated from the model’s losvd histograms or from fitting a Gaussian in each aperture.

Parameters:

modela dyn.model.Model object, optional

The default is the Analysis object’s model.

kin_setint, optional

Which kinematics set to use. The default is the Analysis object’s kin_set.

v_sigma_optionstr, optional

If ‘fit’, v_mean and v_sigma are calculated based on fitting Gaussians, if ‘moments’, v_mean and v_sigma are calculated directly from the model’s losvd histograms. The default is ‘fit’.

kinematics_asstr, optional

If ‘table’, return gh_table, the model’s kinematics as an astropy table, if ‘file’, write the table to the model directory in ascii.ecsv format and return its full path f_name, if ‘both’, write the table to disk and return a tuple (gh_table, f_name). The default is ‘table’.

weightsnumpy.array like, optional

Orbital weights to use. The default is None and will determine the weights via model.get_weights(orblib).

Returns:

gh_tableastropy table (if kinematics_as=’table’)

The astropy table holding the model’s gh kinematics.

f_namestr (if kinematics_as=’file’)

The file name (full path) of the astropy table holding the model’s gh kinematics.

(gh_table, f_name)tuple (if kinematics_as=’both’)

Raises:

ValueError

if v_sigma_option or kinematics_as are invalid.

get_orbit_bundle_maps(model=None, kin_set=None, pop_set=None, weights=None, bundle_mapping=None, normalize=False, flux_as='table', create_figure=False, figtype='.png')

Generates an astropy table that holds the weight-contribution of the orbit bundles defined in bundle_mapping to the model’s projected mass in each aperture. The spatial binning pixels -> apertures is defined in either a Kinematics or a Populations object.

Parameters:

modela dyn.model.Model object, optional

The default is the Analysis object’s model.

kin_setint or None, optional

pop_setint or None, optional

kin_set and pop_set refer to the Kinematics or Populations object that defines the spatial binning. If kin_set=None and pop_set=None, then the Analysis object’s kin_set is used. If kin_set is an integer, then the kinematics set with that index is used for the spatial binning, regardless of pop_set. If kin_set=None and pop_set!=0, then the spatial binning defined in the pop_set is used. The default is kin_set=None, pop_set=None.

weightsnumpy.array like, shape=(n_orbits,), optional

Orbital weights to use. The default is None and will determine the weights via model.get_weights(orblib).

bundle_mappingnumpy.array like, shape=(n_bundles, n_orbits),

mandatory The mapping of orbits to orbit bundles. The values in the array indicate what weight a specific orbit contributes to a specific bundle. Note that an orbit may contribute to more than one bundle because - depending on the dithering configuration setting - each orbit may in fact represent a family of similar orbits (not to be mistaken for the bundles in the sense of this method).

normalizebool, optional

If True, the fluxes in the returned table are normalized to the total flux in each aperture, i.e., the sum of all bundles’ fluxes in each aperture is 1. If False, the fluxes are the raw contributions of the orbit bundles’ weights. The default is False.

flux_asstr, optional

If ‘table’, return map_table, if ‘file’, write the table to the model directory in ascii.ecsv format and return its full path f_name, if ‘both’, write the table to disk and return a tuple (gh_table, f_name). The default is ‘table’.

create_figurebool, optional

If True, the method will also plot surface brightness maps for the orbit bundles and all orbits. The default is False.

figtypestr, optional

Determines the file format and extension to use when saving the sb maps. The default is ‘.png’.

Returns:

map_tableif flux_as=’table’, sb_maps=False

(map_table, figure)if flux_as=’table’, sb_maps=True

f_nameif flux_as=’file’, sb_maps=False

(f_name, figure)if flux_as=’file’, sb_maps=True

(map_table, f_name)if flux_as=’both’, sb_maps=False

(map_table, f_name, figure)if flux_as=’both’, sb_maps=True

map_table f_name figure

flux_as=’table’ X

flux_as=’file’ X

flux_as=’both’ X X

sb_maps=True X

where

map_tableastropy table

The astropy table holding the model’s weighted contribution of the orbit bundles defined in bundle_mapping to the model’s projected mass in each aperture. The table columns are flux_000, …, flux_n_b, flux_all, where flux_xxx is the weighted contribution of orbit bundle xxx, flux_all the weighted contribution of all orbit bundles, and n_b is the number of orbit bundles. If normalized is True, the fluxes are normalized to the total flux in each aperture, i.e., the sum of all bundles’ fluxes in each aperture is 1.

f_namestr

The file name (full path) of the astropy table holding the data in map_table.

figurematplotlib figure

The matplotlib figure holding the orbit bundle maps.

Raises:

ValueError

if flux_as is invalid.

class analysis.Decomposition(config=None, model=None, ocut=None, names='bulgedisk', cache=True, comps_weights=False)

Class for decomposition.

Upon instatiating, the orbits are decomposed by the method decompose_orbits and the results stored in astropy table self.decomp. The components’ flux and moments (currently mean velocity and velocity dispersion only) are plotted by calling self.plot_decomp which also writes the plotted data into the model directory.

The methodology in this class has been contributed by Ling Zhu and Giulia Santucci. Please cite Zhu+18, MNRAS 473, 3000 and Santucci+22, ApJ 930, 153 if used.

Parameters:

configa dyn.config_reader.Configuration object, mandatory

modela dyn.model.Model object or None, optional

Determines which model is used. If model = None, the model corresponding to the minimum chisquare (so far) is used; the setting in the configuration file’s parameter settings is used to determine which chisquare to consider. The default is None.

ocutlist of floats, optional

The orbit cuts in lambda_z. The default is None, which translates to ocut=[0.8, 0.25, -0.25, -0.8], the selection in lambda_z following Santucci+22.

namesstr, optional

Nomenclature of the component names. If ‘bulgedisk’, the components are [‘thin_d’, ‘thick_d’, ‘disk’, ‘cr_thin_d’, ‘cr_thick_d’, ‘cr_disk’, ‘bulge’, ‘all’]. If ‘hotcold’, the components are [‘cold’, ‘warm’, ‘cold+warm’, ‘cr_cold’, ‘cr_warm’, ‘cr_cold+warm’, ‘hot’, ‘all’]. The default is ‘bulgedisk’.

cachebool, optional

If True, the orbit decomposition is read from decomp_table.ecsv instead of recomputing the decomposition if the file exists in the model directory and the ocut matches. Also, a new decomp_table.ecsv file will be written every time a new decomposition is computed. If False, the decomposition is always recomputed. The default is True.

comps_weightsbool, optional

If True, write a table of aggregated weights in each component. The default is False.

Raises:

ValueError

if no config object is given or the kin_set does not exist.

Methods:

comps_aphist([v_sigma_option])	Calculate components' flux, mean velocity, and velocity dispersion.
comps_weights()	Write a table of aggregated weights in each component.
decompose_orbits([ocut])	Decompose orbits based on lambda_z.
plot_decomp([xlim, ylim, kin_set, ...])	Generate decomposition plots.

comps_aphist(v_sigma_option='fit')

Calculate components’ flux, mean velocity, and velocity dispersion.

Parameters:

v_sigma_optionstr, optional

If ‘fit’, v_mean and v_sigma are calculated based on fitting Gaussians, if ‘moments’, v_mean and v_sigma are calculated directly from the model’s losvd histograms. The default is ‘fit’.

Returns:

comp_flux_v_sigmaastropy table

The table columns are: aperture index (starting with 0), followed by three columns per component holding the flux, mean velocity, and velocity dispersion. The chosen v_sigma_option is in the table meta data.

Raises:

ValueError

if v_sigma_option is neither ‘moments’ nor ‘fit’.

comps_weights()

Write a table of aggregated weights in each component.

decompose_orbits(ocut=None)

Decompose orbits based on lambda_z.

Parameters:

ocutDEPRECATED, will be removed in the next major release.

Use ocut= when instatiating the Decomposition object.’

Returns:

decompastropy table

The table has two columns, id and component. The former is the orbit id (starting with 0), component is a string describing the component(s) an orbit belongs to. Note that an orbit can belong to multiple components. In that case, the component strings are concatenated. For easier parsing later, the component descriptors are surrounded by pipe symbols |. The table’s meta data comps holds a list of all components.

plot_decomp(xlim=None, ylim=None, kin_set=0, v_sigma_option='fit', comps_plot='all', individual_colorbars=False, figtype='.png', dpi=100)

Generate decomposition plots.

Parameters:

xlimfloat or None, optional

Restricts plot x-coordinates to abs(x) <= xlim. If None, no restriction is applied. The default is None.

ylimfloat or None, optional

Restricts plot y-coordinates to abs(y) <= ylim. If None, no restriction is applied. The default is None.

kin_setint, optional

Determines which kinematic set to use. The value of this parameter is the index of the data set (e.g. kin_set=0, kin_set=1). The default is 0.

v_sigma_optionstr, optional

If ‘fit’, v_mean and v_sigma are calculated based on fitting Gaussians, if ‘moments’, v_mean and v_sigma are calculated directly from the model’s losvd histograms. The default is ‘fit’.

comps_plotdict or string ‘all’, optional

If ‘all’, all components will be in the decomposition plot. Specific components can be selected by passing a dictionary, e.g., comps_plot = {‘thin_d’: True, ‘thick_d’: True, ‘disk’: True, ‘cr_thin_d’: False, ‘cr_thick_d’: False, ‘cr_disk: False’, ‘bulge’: False, ‘all’: False} will only create the plots for ‘thin_d’, ‘thick_d’, and ‘disk’. False entries can be omitted in the dictionary. NOTE: The component nomenclature must match the names argument used when instantiating the Decomposition object. The default is ‘all’.

individual_colorbarsbool or dict, optional

If True, then the sb (surface brightness), vel (velocity), and sig (velocity dispersion) colorbars adapt to their respective value ranges. This can be useful for identifying structures invisible otherwise. If False, the sb, vel, and sig colorbars will be the same for all components. The individual colorbars are accessed by passing a dict. For example: {‘sb’: True, ‘vel’: False, ‘sig’: False} will only adapt the sb colorbar to the respective component’s value range. ‘False’ entries can be omitted. The default is individual_colorbars=False.

figtypestr, optional

Determines the file format and extension to use when saving the figure. The default is ‘.png’.

dpifloat, optional

The resolution of saved figures (if not overridden later). The default is 100 dpi.

Returns:

None.

Inheritance Diagram