gcfit.analysis.CIModelVisualizer

class gcfit.analysis.CIModelVisualizer(observations)

Analysis and visualization of a model, with confidence intervals.

Provides a number of plotting methods useful for the analysis of a (multimass) model, and it’s fit to all relevant observational datasets. This class is based on a full set of parameter chains, which allows for the estimation of errors on all plotted quantities, shown as confidence intervals shaded on all plots.

A number of relevant (plottable) quantities (and their ±1σ and ±2σ confidence intervals) will be initially computed and stored to be used by the various plotting functions defined by the base class _ClusterVisualizer.

Due to the time required to compute the large number of models needed, this class can also be saved to disk (through the save method) and later reloaded (through the load classmethod) instantly.

See also

_ClusterVisualizer

Base class providing all common plotting functions.

Notes

This class should not be initialized directly, but through the from_chain classmethod.

Methods

__init__(observations)
from_chain(chain, observations[, N, ...])	Initialize a CI visualizer based on a full chain of parameters.
load(filename[, observations])	Initialize this class by loading already saved model outputs.
plot_BH_mass([fig, ax, color, verbose_label])	Plot the BH mass of this model.
plot_BH_num([fig, ax, color, verbose_label])	Plot the number of BHs in this model.
plot_LOS([fig, ax, show_obs, residuals, ...])	Plot the line-of-sight velocity dispersion profiles.
plot_MF_fields([fig, ax, unit, radii, grid, ...])	Plot the on-sky HST fields corresponding to each mass function PI.
plot_all([fig, sharex])	Plot all primary model radial profiles in one figure.
plot_cumulative_mass([fig, ax, kind, ...])	Plot model cumulative mass profiles.
plot_density([fig, ax, kind, x_unit, ...])	Plot model density profiles.
plot_f_BH([fig, ax, color, verbose_label])	Plot the BH fraction of this model.
plot_f_rem([fig, ax, color, verbose_label])	Plot the remnant fraction of this model.
plot_mass_func([fig, show_obs, show_fields, ...])	Plot present day mass functions in various radial bins.
plot_number_density([fig, ax, ...])	Plot the projected number density profiles.
plot_pm_R([fig, ax, show_obs, residuals, ...])	Plot the radial proper motion dispersion profiles.
plot_pm_T([fig, ax, show_obs, residuals, ...])	Plot the tangential proper motion dispersion profiles.
plot_pm_ratio([fig, ax, show_obs, ...])	Plot the proper motion dispersion anisotropy profiles.
plot_pm_tot([fig, ax, show_obs, residuals, ...])	Plot the total proper motion dispersion profiles.
plot_potential([fig, ax, x_unit, ...])	Plot model potential profile.
plot_remnant_fraction([fig, ax, show_total, ...])	Plot model stellar and remnant mass fraction profiles.
plot_surface_density([fig, ax, kind, ...])	Plot model surface density profiles.
plot_vesc([fig, ax, x_unit, label_position, ...])	Plot model escape velocity profile.
save(filename[, overwrite])	Save model CI quantities to a file for quicker future initialization.

Attributes

chi2	Compute χ^2 between the median model and all observational data.
cmap
rlims

property chi2

Compute χ^2 between the median model and all observational data.

classmethod from_chain(chain, observations, N=100, *, verbose=False, pool=None)

Initialize a CI visualizer based on a full chain of parameters.

Classmethod which creates a model visualizer object based on a full chain of parameter values, by computing a model for each step in the chain and determining the median and 1,2σ uncertainties, on each relevant quantity, between all the models.

This function will take some time, as models must be computed for every step in the chain. Parallelizing it via a given multiprocessing pool is recommended.

Parameters:

chainnp.ndarray[…, Nparams]

Array containing chain of parameters values. Final axis must be of the size of the number of model parameters (13).

observationsgcfit.Observations

The Observations instance corresponding to this cluster. Will be used to initialize every model in the chain.

Nint

The number of samples to use in computing the confidence intervals. The chosen number of samples will be taken from the end of the chain (chain[…, -N:]). Choose an N greater than the size of the chain to use all samples.

verbosebool, optional

Optionally show a tqdm loading bar while computing the models.

poolPool, optional

A multiprocessing.Pool (or other pool-like object implementing an imap_unordered method) used to parallelize the computation of the models.

Returns:

CIModelVisualizer

The created CI model visualization object.

See also

gcfit.FittableModel

Model subclass used to initialize each model.

gcfit.scripts.generate_model_CI

Script used to generate and save model CIs for a number of clusters at once.

classmethod load(filename, observations=None)

Initialize this class by loading already saved model outputs.

Based on model outputs computed before (by initializing this class through the CIModelVisualizer.from_chain classmethod) and saved using the CIModelVisualizer.save method, loads in all required model profiles and quantities from the given file and initializes this class based on them.

Required quantities are read from the given HDF5 file under the “/model_output” group. Note that if this group was not created by the save method, unintended errors may arise only later, during some plotting.

Parameters:

filenamepathlib.Path or str

Path to the HDF5 file containing the saved “model_output”.

observationsNone or gcfit.Observations, optional

The Observations instance corresponding to this cluster. If not given, an attempt will be made to create this class based on the stored cluster name.

Returns:

CIModelVisualizer

The loaded CI model visualization object.

plot_BH_mass(fig=None, ax=None, color='tab:blue', verbose_label=True, **kwargs)

Plot the BH mass of this model.

Plots a histogram of the values of the total black hole mass in the given chain of models.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _ClusterVisualizer._setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this quantity. Should be a part of the given fig.

colorcolor, optional

The colour of the plotted histogram. This colour will be applied to the edge (border) of the histogram as is, and to the face at 33% transparency.

verbose_labelbool, optional

If True (default), quantity label will be “BH Mass”, otherwise “$mathrm{M}_{mathrm{BH}}$”.

**kwargsdict, optional

All other arguments are passed to `plt.hist`.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_BH_num(fig=None, ax=None, color='tab:blue', verbose_label=True, **kwargs)

Plot the number of BHs in this model.

Plots a histogram of the values of the total amount of black holes in the given chain of models.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _ClusterVisualizer._setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this quantity. Should be a part of the given fig.

colorcolor, optional

The colour of the plotted histogram. This colour will be applied to the edge (border) of the histogram as is, and to the face at 33% transparency.

verbose_labelbool, optional

If True (default), quantity label will be “BH Amount”, otherwise “$mathrm{N}_{mathrm{BH}}$”.

**kwargsdict, optional

All other arguments are passed to plt.hist.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_LOS(fig=None, ax=None, show_obs=True, residuals=False, *, x_unit='pc', y_unit='km/s', legend=True, label_position='top', verbose_label=True, blank_xaxis=False, res_kwargs=None, **kwargs)

Plot the line-of-sight velocity dispersion profiles.

Plots the self.LOS model profiles, and the relevant observational datasets (variable “σ” within the dataset pattern “velocity_dispersion”), corresponding to the line-of-sight velocity dispersion profiles.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this relation. Should be a part of the given fig.

show_obsbool, optional

Whether to also plot the corresponding observational datasets on top of the relevant model profile. Defaults to True.

residualsbool, optional

Whether to, if also plotting data, append a residuals ax to the figure. Defaults to False.

x_unit, y_unitu.Unit, optional

Units to convert the x and y axes to. By default, x-units are in parsecs and y-units are in kilometres per second.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top” (default), will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label.

verbose_labelbool, optional

If True (default), quantity label will be “LOS Velocity Dispersion”, otherwise “$sigma_{mathrm{LOS}}$”.

blank_xaxisbool, optional

If True, will remove the tick markers and label from the x-axis. May be useful if stacking multiple profiles vertically.

res_kwargsdict, optional

Optional arguments passed to _add_residuals.

**kwargsdict

All other arguments are passed to _plot_profile.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_MF_fields(fig=None, ax=None, *, unit='arcmin', radii=('rh',), grid=True, label_grid=False, add_legend=True)

Plot the on-sky HST fields corresponding to each mass function PI.

Plots the representation of the observed on-sky photometry footprints for each stored mass function groupings, with the origin on the cluster centre. Each grouping of mass functions bins (i.e. under a certain data source proposal) will be plotted with it’s own colour.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot the fields. Should be a part of the given fig.

unitu.Unit, optional

Units to convert the x and y axes and grid lines to. By default, the units are arcminutes.

radiilist of {‘rh’, ‘ra’, ‘rt’, ‘r0’, ‘rhp’, ‘rv’}, optional

A collection of radius values to be overplotted (as circles) on the plot. If the given radii have corresponding uncertainties, they will also be shaded in. By default plots the half-mass radius.

gridbool, optional

If True (default), adds a circular grid at 2 arcminute intervals, out to the tidal radius.

label_gridbool, optional

Optionally adds labels on to the figure noting the size of each grid interval, if grid is True.

add_legendbool, optional

If True (default), adds a legend with an entry for each grouping with the proposal PI name and ID.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

See also

util.mass.Field

Class representing a given mass function field, containing all associated plotting methods.

plot_all(fig=None, sharex=True, **kwargs)

Plot all primary model radial profiles in one figure.

Plots the six primary radial profile quantities used for fitting (excluding notably the mass functions and pulsar accelerations). That is, clockwise from the top left, number density, total PM, tangential PM, radial PM, PM ratio and LOS dispersion profiles.

Simply sets up a figure with six axes and calls the various relevant profile plotting functions to populate each ax.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place all axes on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_multi_artist for more details.

sharexbool, optional

If True, created subplots will all share the same x-axis. Will also remove the x axis ticks and labels on all but the bottom row.

**kwargsdict

All other arguments are passed to each plotting function.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_cumulative_mass(fig=None, ax=None, kind='all', *, x_unit='pc', label_position='left', colors=None)

Plot model cumulative mass profiles.

Plots the radial cumulative mass profiles of the total, main sequence, and dark remnant objects in this model.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot the profiles. Should be a part of the given fig.

kindlist of {‘tot’, ‘rem’, ‘MS’, ‘WD’, ‘NS’, ‘BH’}, optional

The mass profiles to plot. By default plots all of them.

x_unitu.Unit, optional

Units to convert the x axis to. By default, x-units are in parsecs.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top”, will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label. Defaults to the left.

colorsdict, optional

A dictionary of colours, where the keys correspond to the given kind. Each object type has it’s own default colour.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_density(fig=None, ax=None, kind='all', *, x_unit='pc', label_position='left', colors=None)

Plot model density profiles.

Plots the radial mass density (self.rho_*) profiles of the total, main sequence, and dark remnant objects in this model.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot the profiles. Should be a part of the given fig.

kindlist of {‘tot’, ‘rem’, ‘MS’, ‘WD’, ‘NS’, ‘BH’}, optional

The density profiles to plot. By default plots all of them.

x_unitu.Unit, optional

Units to convert the x axis to. By default, x-units are in parsecs.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top”, will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label. Defaults to the left.

colorsdict, optional

A dictionary of colours, where the keys correspond to the given kind. Each object type has it’s own default colour.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_f_BH(fig=None, ax=None, color='tab:blue', verbose_label=True, **kwargs)

Plot the BH fraction of this model.

Plots a histogram of the values of the total black hole mass fraction (i.e. mass fraction in BH over total mass) in the given chain of models.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _ClusterVisualizer._setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this quantity. Should be a part of the given fig.

colorcolor, optional

The colour of the plotted histogram. This colour will be applied to the edge (border) of the histogram as is, and to the face at 33% transparency.

verbose_labelbool, optional

If True (default), quantity label will be “BH Mass Fraction”, otherwise “$f_{mathrm{BH}}$”.

**kwargsdict, optional

All other arguments are passed to plt.hist.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_f_rem(fig=None, ax=None, color='tab:blue', verbose_label=True, **kwargs)

Plot the remnant fraction of this model.

Plots a histogram of the values of the total remnant mass fraction (i.e. mass fraction in WD, NS, BH) in the given chain of models.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _ClusterVisualizer._setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this quantity. Should be a part of the given fig.

colorcolor, optional

The colour of the plotted histogram. This colour will be applied to the edge (border) of the histogram as is, and to the face at 33% transparency.

verbose_labelbool, optional

If True (default), quantity label will be “Remnant Fraction”, otherwise “$f_{mathrm{remn}}$”.

**kwargsdict, optional

All other arguments are passed to plt.hist.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_mass_func(fig=None, show_obs=True, show_fields=True, *, PI_legend=False, propid_legend=False, label_unit='arcmin', model_color=None, model_label=None, logscaled=False, field_kw=None, **kwargs)

Plot present day mass functions in various radial bins.

Plots each of the stored self.mass_func radial (present-day) mass function bins (i.e. binned star counts by mean star mass), in a large figure of stacked axes, as well as the corresponding observational datasets.

Each grouping of mass functions bins (i.e. under a certain data source proposal) will be plotted with it’s own colour and sorted to be next to one another.

Optionally, a panel will be added to the left of the figure showing the related field outlines on the sky (using plot_MF_fields).

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place all axes on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_multi_artist for more details.

show_obsbool, optional

Whether to also plot the corresponding observational datasets on top of the relevant model profile. Defaults to True.

show_fieldsbool, optional

Whether to include an extra panel (on the left of the figure) showing the observed mass function fields (using plot_MF_fields).

PI_legendbool, optional

If True, also notes the PI name of each proposal grouping under each first radial bin annotation. Only applies if show_fields is False, as otherwise they will be noted in that panel better.

propid_legendbool, False

If True, also notes the ID of each proposal grouping under each first radial bin annotation. Only applies if show_fields is False, as otherwise they will be noted in that panel better.

label_unitu.Unit, optional

The unit used to denote each radial bin in it’s corresponding label. Does not change anything about what is plotted, only the label. Defaults to arcminutes (‘).

model_colorstr, optional

Optionally colour all model profiles with a specific colour. This will give the same colour to all radial bins, regardless of proposal grouping. By default, models will match the colour of their corresponding data, as dictated within self.mass_func, or as set by the default matplotlib colour cycler, if not set.

model_labelstr, optional

Optionally add a figure legend with this label corresponding to the model profiles. Only valid if a single specific model colour was given through model_color. The legend placement won’t be great, and this is mostly for inspection when overplotting multiple models on a single figure.

logscaledbool, optional

If True, applies a log scaling to the the x (i.e. mass) axis.

field_kwdict, optional

Optional arguments passed to plot_MF_fields if show_fields is True.

**kwargsdict

All other arguments are passed to each plt.errorbars call.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_number_density(fig=None, ax=None, show_background=False, subtract_background=False, show_obs=True, residuals=False, *, legend=True, x_unit='pc', y_unit='1/pc2', scale_to='model', label_position='top', verbose_label=True, blank_xaxis=False, res_kwargs=None, data_kwargs=None, model_kwargs=None, **kwargs)

Plot the projected number density profiles.

Plots the self.numdens model profiles, and the relevant observational datasets (variable “Σ” within the dataset pattern “number_density”), corresponding to the project number density profiles.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this relation. Should be a part of the given fig.

show_backgroundbool, optional

If True, also plots a horizontal line representing the value of the background density, as taken from the observational datasets (if possible).

subtract_backgroundbool, optional

If True, subtracts the background density value from the number density model profiles and data.

show_obsbool, optional

Whether to also plot the corresponding observational datasets on top of the relevant model profile. Defaults to True.

residualsbool, optional

Whether to, if also plotting data, append a residuals ax to the figure. Defaults to False.

x_unit, y_unitu.Unit, optional

Units to convert the x and y axes to. By default, x-units are in parsecs and y-units are in stars per parsec squared.

scale_to{“model”, “data”}, optional

Number densities are typically scaled to match the normalization of the data in GCfit, as they are fit to the shape, not value of the number densities. This argument allows the absolute values of the plotted quantities to be scaled to either the model (data / K; default) or the data (model * K).

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top” (default), will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label.

verbose_labelbool, optional

If True (default), quantity label will be “Tangential PM Dispersion”, otherwise “$sigma_{mathrm{PM},mathrm{T}}$”.

blank_xaxisbool, optional

If True, will remove the tick markers and label from the x-axis. May be useful if stacking multiple profiles vertically.

res_kwargs, data_kwargs, model_kwargsdict, optional

Optional arguments passed to _add_residuals, _plot_data, and _plot_model, respectively.

**kwargsdict

All other arguments are passed to _plot_profile.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_pm_R(fig=None, ax=None, show_obs=True, residuals=False, *, x_unit='pc', y_unit='mas/yr', legend=True, label_position='top', verbose_label=True, blank_xaxis=False, res_kwargs=None, **kwargs)

Plot the radial proper motion dispersion profiles.

Plots the self.pm_T model profiles, and the relevant observational datasets (variable “PM_T” within the dataset pattern “proper_motion”), corresponding to the radial proper motion dispersion profiles.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this relation. Should be a part of the given fig.

show_obsbool, optional

Whether to also plot the corresponding observational datasets on top of the relevant model profile. Defaults to True.

residualsbool, optional

Whether to, if also plotting data, append a residuals ax to the figure. Defaults to False.

x_unit, y_unitu.Unit, optional

Units to convert the x and y axes to. By default, x-units are in parsecs and y-units are in milliarcseconds per year.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top” (default), will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label.

verbose_labelbool, optional

If True (default), quantity label will be “Radial PM Dispersion”, otherwise “$sigma_{mathrm{PM},mathrm{R}}$”.

blank_xaxisbool, optional

If True, will remove the tick markers and label from the x-axis. May be useful if stacking multiple profiles vertically.

res_kwargsdict, optional

Optional arguments passed to _add_residuals.

**kwargsdict

All other arguments are passed to _plot_profile.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_pm_T(fig=None, ax=None, show_obs=True, residuals=False, *, x_unit='pc', y_unit='mas/yr', legend=True, label_position='top', verbose_label=True, blank_xaxis=False, res_kwargs=None, **kwargs)

Plot the tangential proper motion dispersion profiles.

Plots the self.pm_T model profiles, and the relevant observational datasets (variable “PM_T” within the dataset pattern “proper_motion”), corresponding to the tangential proper motion dispersion profiles.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this relation. Should be a part of the given fig.

show_obsbool, optional

Whether to also plot the corresponding observational datasets on top of the relevant model profile. Defaults to True.

residualsbool, optional

Whether to, if also plotting data, append a residuals ax to the figure. Defaults to False.

x_unit, y_unitu.Unit, optional

Units to convert the x and y axes to. By default, x-units are in parsecs and y-units are in milliarcseconds per year.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top” (default), will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label.

verbose_labelbool, optional

If True (default), quantity label will be “Tangential PM Dispersion”, otherwise “$sigma_{mathrm{PM},mathrm{T}}$”.

blank_xaxisbool, optional

If True, will remove the tick markers and label from the x-axis. May be useful if stacking multiple profiles vertically.

res_kwargsdict, optional

Optional arguments passed to _add_residuals.

**kwargsdict

All other arguments are passed to _plot_profile.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_pm_ratio(fig=None, ax=None, show_obs=True, residuals=False, *, x_unit='pc', blank_xaxis=False, legend=True, label_position='top', verbose_label=True, res_kwargs=None, **kwargs)

Plot the proper motion dispersion anisotropy profiles.

Plots the self.pm_ratio model profiles, and the relevant observational datasets (variable “PM_ratio” within the dataset pattern “proper_motion”), corresponding to the proper motion dispersion anisotropy profiles, defined as the ratio of the tangential over radial proper motion dispersions.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this relation. Should be a part of the given fig.

show_obsbool, optional

Whether to also plot the corresponding observational datasets on top of the relevant model profile. Defaults to True.

residualsbool, optional

Whether to, if also plotting data, append a residuals ax to the figure. Defaults to False.

x_unitu.Unit, optional

Units to convert the x axis to. By default, x-units are in parsecs.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top” (default), will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label.

verbose_labelbool, optional

If True (default), quantity label will be “PM Anisotropy Ratio”, otherwise “$sigma_{mathrm{PM},mathrm{T}} / sigma_{mathrm{PM},mathrm{R}}$”.

blank_xaxisbool, optional

If True, will remove the tick markers and label from the x-axis. May be useful if stacking multiple profiles vertically.

res_kwargsdict, optional

Optional arguments passed to _add_residuals.

**kwargsdict

All other arguments are passed to _plot_profile.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_pm_tot(fig=None, ax=None, show_obs=True, residuals=False, *, x_unit='pc', y_unit='mas/yr', legend=True, label_position='top', verbose_label=True, blank_xaxis=False, res_kwargs=None, **kwargs)

Plot the total proper motion dispersion profiles.

Plots the self.pm_tot model profiles, and the relevant observational datasets (variable “PM_tot” within the dataset pattern “proper_motion”), corresponding to the total proper motion dispersion profiles.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this relation. Should be a part of the given fig.

show_obsbool, optional

Whether to also plot the corresponding observational datasets on top of the relevant model profile. Defaults to True.

residualsbool, optional

Whether to, if also plotting data, append a residuals ax to the figure. Defaults to False.

x_unit, y_unitu.Unit, optional

Units to convert the x and y axes to. By default, x-units are in parsecs and y-units are in milliarcseconds per year.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top” (default), will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label.

verbose_labelbool, optional

If True (default), quantity label will be “Total PM Dispersion”, otherwise “$sigma_{mathrm{PM},mathrm{tot}}$”.

blank_xaxisbool, optional

If True, will remove the tick markers and label from the x-axis. May be useful if stacking multiple profiles vertically.

res_kwargsdict, optional

Optional arguments passed to _add_residuals.

**kwargsdict

All other arguments are passed to _plot_profile.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_potential(fig=None, ax=None, *, x_unit='pc', label_position='left', verbose_label=True, **kwargs)

Plot model potential profile.

Plots the total radial gravitational potential (self.phi) profile of this model.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot the profiles. Should be a part of the given fig.

x_unitu.Unit, optional

Units to convert the x axis to. By default, x-units are in parsecs.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top”, will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label. Defaults to the left.

verbose_labelbool, optional

If True (default), quantity label will be “Potential”, otherwise “$Phi$”.

**kwargsdict, optional

All other arguments are passed to _plot_profile.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_remnant_fraction(fig=None, ax=None, *, show_total=True, x_unit='pc', label_position='left')

Plot model stellar and remnant mass fraction profiles.

Plots the radial mass fraction profile of the main sequence stars (mass_MS / mass_tot) and the dark remnants (mass_rem / mass_tot).

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot the profiles. Should be a part of the given fig.

show_totalbool, optional

If True (default), places an anchored box in the upper centre of the ax showing the total remnant mass fraction of the cluster.

x_unitu.Unit, optional

Units to convert the x axis to. By default, x-units are in parsecs.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top”, will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label. Defaults to the left.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_surface_density(fig=None, ax=None, kind='all', *, x_unit='pc', label_position='left', colors=None)

Plot model surface density profiles.

Plots the radial surface mass density (self.Sigma_*) profiles of the total, main sequence, and dark remnant objects in this model.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot the profiles. Should be a part of the given fig.

kindlist of {‘tot’, ‘rem’, ‘MS’, ‘WD’, ‘NS’, ‘BH’}, optional

The density profiles to plot. By default plots all of them.

x_unitu.Unit, optional

Units to convert the x axis to. By default, x-units are in parsecs.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top”, will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label. Defaults to the left.

colorsdict, optional

A dictionary of colours, where the keys correspond to the given kind. Each object type has it’s own default colour.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_vesc(fig=None, ax=None, *, x_unit='pc', label_position='left', verbose_label=True, **kwargs)

Plot model escape velocity profile.

Plots the escape velocity profile (self.vesc) of this model, as given by \(v_{\mathrm{esc}}=\sqrt{2 |\phi(r)|}\).

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot the profiles. Should be a part of the given fig.

x_unitu.Unit, optional

Units to convert the x axis to. By default, x-units are in parsecs.

label_position{‘top’, ‘left’, ‘right’}, optional

Where to place the quantity (y) label. If “top”, will be set as the ax title, otherwise will be set to one side. If on a side, will also attempt to correctly append the units to the end of the label. Defaults to the left.

verbose_labelbool, optional

If True (default), quantity label will be “Escape Velocity”, otherwise “$v_{mathrm{esc}}$”.

**kwargsdict, optional

All other arguments are passed to _plot_profile.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

save(filename, overwrite=False)

Save model CI quantities to a file for quicker future initialization.

Saves the computed confidence intervals on all model profiles, and the full chains of computed quantities (e.g. BH mass, number), so that the same CIModelVisualizer can be initialized later (through the CIModelVisualizer.load classmethod) without needing to recompute a large number of models again.

The desired file must be an existing HDF5 file. All quantities will be stored under a “model_output” group, in the root group. The easiest file to use may be the run output file for the cluster fit that this CI model was based on. Note that an existing saved CI model within this file will be quietly overwritten if overwrite=True.

The full set of models used to initilize this class will not be stored, only the quantities required to initialize this class.

Parameters:

filenamepathlib.Path or str

Path to the output HDF5 file to save this CI model to.

overwritebool, optional

If True, will overwrite any existing saved model outputs in this file. By default raises a ValueError if model output exists already.