Kinematics

Classes for kinematic data.

API

Classes:

BayesLOSVD(**kwargs)	Bayes LOSVD kinematic data
GaussHermite(**kwargs)	LOSVDs described by a Gauss Hermite expansion
Histogram([xedg, y, normalise])	LOSVD histograms
Kinematics([type, hist_width, hist_center, ...])	Abstract class for Kinematics

class kinematics.BayesLOSVD(**kwargs)

Bayes LOSVD kinematic data

Methods:

center_v_systemic([v_systemic])	Center the LOSVD histograms on systemtic velocity
convert_losvd_columns_to_one_multidimensional_column()	Convert 1D to multi-dim columns
convert_multidimensional_losvd_columns_to_univariate()	Convert multi-dim columns to 1D
get_observed_values_and_uncertainties(...)	Get LOSVD mean/uncertainties
has_pops()	Identifies population data in the kinematics data file.
load_hdf5(filename)	Load a hdf5 file of BAYES-LOSVD output
map_binID_blosvd_to_binID_dynamite(binID_blosvd)	Map BayesLOSVD binIDs to DYNMAITE binIDs.
rebin_orblib_to_observations(losvd_histograms)	Rebin orblib to velocity spacing of observations
save_data_table([outfile])	Special save method for BayesLOSVD data.
set_default_hist_bins([oversampling_factor])	Set default LOSVD nbins for orblibs
set_default_hist_center()	Sets orbit histogram center to 0
set_default_hist_width([scale])	Set orbit histogram width
set_mean_v_and_sig_v_per_aperture()	get mean and dispersion
transform_orblib_to_observables(...)	trasform orbit library to observed kinematics
write_aperture_and_bin_files([filename, ...])	Write aperture.dat and bins.dat files
write_losvds_to_ecsv_format([filename, outfile])	Convert BayesLOSVD output to ECSV

center_v_systemic(v_systemic='flux_weighted')

Center the LOSVD histograms on systemtic velocity

Uses velocity spacing of the data divided by oversampling_factor. Also forces nbins to be odd, so that central bin in 0-centered.

Parameters:

v_systemicstring or float. If ‘flux_weighted’, then use the flux

weighted mean-velocity of the kinematics. Otherwise, provide a float directly.

Returns:

Sets the result to attribute self.hist_bins

convert_losvd_columns_to_one_multidimensional_column()

Convert 1D to multi-dim columns

ECSV files can save 1D columns, but useful to work with multi-dim columns for the LOSVSD. This method converts.

Returns:

Re-sets self.data['losvd'] and self.data['dlosvd'] to multi-dim

columns

convert_multidimensional_losvd_columns_to_univariate()

Convert multi-dim columns to 1D

ECSV files can save 1D columns, but useful to work with multi-dim columns for the LOSVSD. This method converts.

Returns:

Re-sets self.data['losvd'] and self.data['dlosvd'] to 1D columns

called self.data['losvd_{i}'] and self.data['dlosvd_{i}'] for

i = 1, …, N_LOSVD_bins

get_observed_values_and_uncertainties(weight_solver_settings)

Get LOSVD mean/uncertainties

Parameters:

weight_solver_settingsdict

Returns:

tuple

(observed_values, uncertainties), where: - observed_values array of shape (n_aperture, n_vbins) - uncertainties array of shape (n_aperture, n_vbins)

has_pops()

Identifies population data in the kinematics data file.

If there is population data, it is removed from self.data. This method needs to be implemented for all Kinematics subclasses.

Returns:

bool

True if population data is found, False otherwise.

list

List of population data columns

load_hdf5(filename)

Load a hdf5 file of BAYES-LOSVD output

Borrowed from bayes_losvd_load_hdf5.py

Parameters:

filenamestring

the hdf5 file of BayesLOSVD output

Returns:

dict

data read from BayesLOSVD output file

map_binID_blosvd_to_binID_dynamite(binID_blosvd)

Map BayesLOSVD binIDs to DYNMAITE binIDs.

Assumes that the table self.data has colums binID_BayesLOSVD and binID_dynamite which define the mapping. Any binID_blosvd with no corresponding binID_dynamite are given binID_dynamite=0.

Parameters:

binID_blosvdarray

array of BayesLOSVD binIDs

Returns:

type

corresponding array of DYNMAITE binIDs

rebin_orblib_to_observations(losvd_histograms)

Rebin orblib to velocity spacing of observations

Creates a matrix f, the fraction of the j’th orblib vbin in the i’th data vbin. Multiplies orblib losvd_histograms by f to rebin.

Parameters:

losvd_histogramsdyn.kinematics.Histogram

a histogram object of the orblib LOSVD

Returns:

dyn.kinematics.Histogram

a orblib LOSVD re-binned to the data velocity spacing

save_data_table(outfile=None)

Special save method for BayesLOSVD data.

Handles conversion from multi-dim –> 1D columns. Should supercede the generic method dyn.data.Data.save

Parameters:

outfilestring

Name of output file

set_default_hist_bins(oversampling_factor=10)

Set default LOSVD nbins for orblibs

Uses velocity spacing of the data divided by oversampling_factor. Also forces nbins to be odd, so that central bin in 0-centered.

Parameters:

oversampling_factorfloat

scale factor to divide the data velocity spacing

Returns:

Sets the result to attribute self.hist_bins

set_default_hist_center()

Sets orbit histogram center to 0

set_default_hist_width(scale=2.0)

Set orbit histogram width

Set it to a multiple of data histogram width. Default 2 i.e. double to width of observed data. Sets result to attribute self.hist_width

Parameters:

scalefloat

scale factor

set_mean_v_and_sig_v_per_aperture()

get mean and dispersion

Returns:

creates columns self.data['v'] and self.data['sigma']

transform_orblib_to_observables(losvd_histograms, weight_solver_settings)

trasform orbit library to observed kinematics

This is a placeholder method. Specific implementations/subclasses of Kinematics should replace this with methods which transform an orbit library LOSVD to that particular type of kinematics.

Parameters:

losvd_histogramsdyn.kinematics.Histogram

the LOSVD of an orbit library

weight_solver_settingsdict

weight solver settings

Returns:

object

the orbit library LOSVD transofrmed to observed kinematics

write_aperture_and_bin_files(filename=None, angle_deg=0.0, center='max_flux', aperture_filename='aperture.dat', bin_filename='bins.dat')

Write aperture.dat and bins.dat files

Parameters:

filenamestring

filename XXX_results.hdf5 of BAYES-LOSVD output (all bins combined)

angle_degfloat

Angle in degrees measured counter clockwise from the galaxy major axis to the X-axis of the input data

centertuple or string

either pair of floats (x0,y0) defining center in pixel co-ordinates or string ‘max_flux’

aperture_filenamestring

name of aperture file

bin_filenamestring

name of bins file

write_losvds_to_ecsv_format(filename=None, outfile='bayes_losvd_kins.ecsv')

Convert BayesLOSVD output to ECSV

Reads in the hdf5 BayesLOSVD output file for all spatial bins. Saves the median and 68% Bayesian Credible Interval of the LOSVD in each LOSVD bin, into an astropy ECSV file.

Parameters:

filenamestring

BayesLOSVD hdf5 output file for all spatial bins.

outfilestring

desired name of output ECSV file

Returns:

None

class kinematics.GaussHermite(**kwargs)

LOSVDs described by a Gauss Hermite expansion

Using the Capellari et al 2016 convention

Methods:

convert_file_from_old_format(...)	Convert old format of GH kinematics to new format
evaluate_hermite_polynomials(coeffients, w)	Evaluate Hermite polynomials
evaluate_losvd(v, v_mu, v_sig, h)	evaluate LOSVDs
evaluate_losvd_normalisation(h)	Evaluate LOSVD normalisation
get_data(weight_solver_settings[, ...])	Get GH kinematics data consistent with number_GH configuration.
get_gh_expansion_coefficients([v_mu, v_sig, ...])	Calcuate GH expansion coeffients given an LOSVD
get_hermite_polynomial_coeffients(max_order)	Get Hermite poly coeffients
get_highest_order_gh_coefficient()	Get max order GH coeeff from data table
get_observed_values_and_uncertainties(...)	Extract mean/sigma from the GH kinematics
has_pops()	Identifies population data in the kinematics data file.
read_file_old_format(filename)	Read the old format of GH kinematics
set_default_hist_bins([f_sig])	Sets default nbins so they are roughly f_sig*min(sig)
set_default_hist_center()	Sets default histogram center to 0.
set_default_hist_width([n_sig])	Sets default histogram width
standardise_velocities(v, v_mu, v_sig)	Take away v_mu, divide by v_sig
transform_orblib_to_observables(...)	trasform orbit library to observed kinematics

convert_file_from_old_format(filename_old_format, filename_new_format)

Convert old format of GH kinematics to new format

Old format is that used in triaxialschwarzschild AKA schwpy codes

Parameters:

filename_old_formatstring

filename of old/shwpy format of GH kinematics file

filename_new_formatstring

desired filename of new Astropy ECSV format

Returns:

None

creates a an astropy ECSV file at filename_new_format

evaluate_hermite_polynomials(coeffients, w, standardised=True, v_mu=None, v_sig=None)

Evaluate Hermite polynomials

Parameters:

coeffientsarray (n_herm, n_herm)

coefficients of hermite polynomials as given by method get_hermite_polynomial_coeffients

warray

if standardised==True then w is array of shape (n_regions, n_vbins) of standardised (AKA whitened) velocities else, w is array of shape (n_vbins,) of physical velocities and arrays v_mu and v_sig with shape (n_regions,) must be set

standardisedBoolean

whether or not velocities w have been standardised by aperture v/sig

v_muNone or array shape (n_regions,)

aperture v_mu’s

v_sigNone or array shape (n_regions,)

aperture v_sigma’s

Returns:

array shape (n_herm, n_regions, n_vbins)

array[i,j,:] is the i’th Hermite polynomial evaluated at standardised velocities w in the j’th region

evaluate_losvd(v, v_mu, v_sig, h)

evaluate LOSVDs

Evaluate the quantity

\[\mathrm{LOSVD}(v) = \frac{1}{v_\sigma} \mathcal{N}(w; 0, 1^2) \Sigma_{m=0}^{M} h_m H_m(w)\]

where normalised velocity \(w = (v-v_\mu)/v_\sigma\)

Parameters:

varray

input velocity array

v_muarray (n_regions,)

gauss hermite v parameters

v_sigarray (n_regions,)

gauss hermite sigma parameters

harray (n_hists, n_regions, n_herm)

gauss hermite expansion coefficients

Returns:

array shape same as v

values of gauss hermite expansion evaluated at v

evaluate_losvd_normalisation(h)

Evaluate LOSVD normalisation

Evaluate the normalising integral

\[\int_{-\infty}^{\infty} \mathrm{LOSVD}(v) dv\]

which for a GH expansion is given by

\[\Sigma_{m=0}^{M} b_m a_m\]

where

• \(a_m\) are the coefficients of w in the polynomial \(\Sigma_{m=0}^{M} h_m H_m(w)\)

• \(b_m\) =

  • 1 if m=0

  • 0 if m is odd

  • (m-1)!! if m is non-zero and even

and !! is a ‘double factorial’ - which does not mean two factorials but the product integers < n with same even/odd parity as n

Parameters:

v_sigarray (n_regions,)

gauss hermite sigma parameters

harray (n_hists, n_regions, n_herm)

gauss hermite expansion coefficients for some number of histograms and regions

Returns:

array (n_hists, n_regions)

get_data(weight_solver_settings, apply_systematic_error=False, cache_data=True)

Get GH kinematics data consistent with number_GH configuration.

Returns an astropy table holding the observed Gauss Hermite kinematics with their uncertainties, adapted to the desired number of GH coefficients and optionally including the systematic errors. The number_GH setting from the configuration file determines the number of returned GH coefficients. The data in the returned table is a deep copy of the observed data.

If number_GH (configuration file) greater than max_GH_order (number of gh coefficients in the kinematics file), columns with zeros h<max_GH_order+1> dh<max_GH_order+1> … h<number_GH> dh<number_GH> will be added to the gh kinematics data. If number_GH is less than max_GH_order, the corresponding columns will be removed from the kinematics data.

Parameters:

weight_solver_settingsdict

Configuration.settings.weight_solver_settings object. Must include the key number_GH and - if apply_systematic_error is set to True - the key GH_sys_err.

apply_systematic_errorbool, optional

If set to True, apply the systematic uncertainties to the dv, dsigma, dh3, dh4, … values.

cache_databool, optional

If set to True, the first call of this method will store the calculated data table in attribute self._data_raw (if apply_systematic_error=False) or self._data_with_sys_err (if apply_systematic_error=True), respectively. Consecutive calls will return the stored data. The default is True.

Returns:

gh_dataastropy table

GH kinemtics coefficients

get_gh_expansion_coefficients(v_mu=None, v_sig=None, vel_hist=None, max_order=4)

Calcuate GH expansion coeffients given an LOSVD

Expand LOSVD around a given v_mu and v_sig using eqn 7 of vd Marel & Franx 93, ApJ 407,525

Parameters:

v_muarray (n_regions,)

gauss hermite v parameters

v_sigarray (n_regions,)

gauss hermite sigma parameters

vel_histHistogram object

velocity histograms where vel_hist.y has shape (n_orbits, n_vbins, n_regions)

max_orderint

maximum order hermite polynomial desired in the expansion e.g. max_order = 1 –> use h0, h1 i.e. number of hermite polys = max_order + 1

Returns:

harray (n_hists, n_regions, max_order+1)

where h[i,j,k] is order k GH coeffient of histogram i in region j

get_hermite_polynomial_coeffients(max_order)

Get Hermite poly coeffients

Normalised as in eqn 14 of Capellari 16

Parameters:

max_orderint

maximum order hermite polynomial desired e.g. max_order = 3 means use h0, h1, h2, h3

Returns:

array (max_order+1, max_order+1)

coeffients[i,j] = coef of x^j in polynomial of order i

get_highest_order_gh_coefficient()

Get max order GH coeeff from data table

Checks the data table for columns titled [‘h{i}’] and [‘dh{i}’], and return the largest i such that both exist

Returns:

int

the highest order GH present in the data table

get_observed_values_and_uncertainties(weight_solver_settings)

Extract mean/sigma from the GH kinematics

Parameters:

weight_solver_settingsdict

Configuration.settings.weight_solver_settings object. Must include the key number_GH.

Returns:

tuple

(observed_values, uncertainties), where: - observed_values is array of GH expansion coefficients of shape (n_apertures, number_GH) - uncertainties is array of uncertainties on GH expansion coefficients of shape (n_apertures, number_GH)

has_pops()

Identifies population data in the kinematics data file.

If there is population data, it is removed from self.data. This method needs to be implemented for all Kinematics subclasses.

Returns:

bool

True if population data is found, False otherwise.

list

List of population data columns

read_file_old_format(filename)

Read the old format of GH kinematics

Old format is that used in triaxialschwarzschild AKA schwpy codes

Parameters:

filenamestring

filename of old format of GH kinematics file

Returns:

Astropy table

the GH kinematics data

set_default_hist_bins(f_sig=0.1)

Sets default nbins so they are roughly f_sig*min(sig)

Parameters:

f_sigfloat

fraction of minimum sigma to (approximately) set histogram bin width

set_default_hist_center()

Sets default histogram center to 0.

set_default_hist_width(n_sig=3.0)

Sets default histogram width

Set it to

\(2 * \max(|v| + n_\mathrm{sig}*\sigma)\)

i.e. double the largest velcoity present in the observed LOSVD

Parameters:

n_sigfloat

number of sigma above mean velocity to extend the velocity histogram

standardise_velocities(v, v_mu, v_sig)

Take away v_mu, divide by v_sig

Parameters:

varray

input velocity array

v_muarray (n_regions,)

gauss hermite v parameters

v_sigarray (n_regions,)

gauss hermite sigma parameters

Returns:

array (n_regions,) + v.shape

velocities whitened by array v_mu, v_sigma

transform_orblib_to_observables(losvd_histograms, weight_solver_settings)

trasform orbit library to observed kinematics

This is a placeholder method. Specific implementations/subclasses of Kinematics should replace this with methods which transform an orbit library LOSVD to that particular type of kinematics.

Parameters:

losvd_histogramsdyn.kinematics.Histogram

the LOSVD of an orbit library

weight_solver_settingsdict

weight solver settings

Returns:

object

the orbit library LOSVD transofrmed to observed kinematics

class kinematics.Histogram(xedg=None, y=None, normalise=False)

LOSVD histograms

Parameters:

xedgarray (n_bins+1,)

histogram bin edges

y(n_orbits, n_bins+1, n_apertures)

histogram values

normalisebool, default=True

whether to normalise to pdf

Attributes:

xarray (n_bins,)

bin centers

dxarray (n_bins,)

bin widths

normalisedbool

whether or not has been normalised to pdf

Methods:

get_mean()	Get the mean velocity
get_mean_sigma_gaussfit()	Get the mean velocity and velocity dispersion from fitted Gaussians
get_normalisation()	Get the normalsition
get_sigma()	Get the velocity dispersions
normalise()	normalises the LOSVDs
scale_x_values(scale_factor)	scale the velocity array

get_mean()

Get the mean velocity

Returns:

array shape (n_orbits, n_apertures)

mean velcoity of losvd

get_mean_sigma_gaussfit()

Get the mean velocity and velocity dispersion from fitted Gaussians

Returns:

array shape (n_orbits, n_apertures)

mean velocity of losvd

array shape (n_orbits, n_apertures)

velocity dispersion of losvd

get_normalisation()

Get the normalsition

Calculates Sum_i losvd_i * dv_i

Returns:

float

the normalisation

get_sigma()

Get the velocity dispersions

Returns:

array shape (n_orbits, n_apertures)

velocity dispersion of losvd

normalise()

normalises the LOSVDs

Returns:

None

resets self.y to a normalised version

scale_x_values(scale_factor)

scale the velocity array

scales vel array, and dv

Parameters:

scale_factorfloat

Returns:

None

resets self.xedg, self.x, self.dx to rescaled versions

class kinematics.Kinematics(type=None, hist_width='default', hist_center='default', hist_bins='default', with_pops=False, **kwargs)

Abstract class for Kinematics

Specific implementations (e.g. GaussHermite) should be implemented as child classes

Methods:

get_data(**kwargs)	Returns the kinematics data.
get_observed_values_and_uncertainties(...)	Extract mean and uncertainties from the kinematic set
has_pops()	Identifies population data in the kinematics data file.
transform_orblib_to_observables(...)	trasform orbit library to observed kinematics
update(**kwargs)	Updates one or more attributes, including consistency check

get_data(**kwargs)

Returns the kinematics data.

This skeleton method returns a deep copy of the self.data attribute and allows for specific implementations by subclasses.

Parameters:

**kwargsargument list (optional)

Returns:

astropy table

The kinematics data

get_observed_values_and_uncertainties(weight_solver_settings)

Extract mean and uncertainties from the kinematic set

This is a placeholder method. Specific implementations/subclasses of Kinematics should replace this with methods which extract the mean and uncertainties of that particular kinematic type.

Parameters:

weight_solver_settingstype

Description of parameter weight_solver_settings.

Returns:

tuple

(observed_values, uncertainties)

has_pops()

Identifies population data in the kinematics data file.

If there is population data, it is removed from self.data. This method needs to be implemented for all Kinematics subclasses.

Returns:

bool

True if population data is found, False otherwise.

list

List of population data columns

transform_orblib_to_observables(losvd_histograms, weight_solver_settings)

trasform orbit library to observed kinematics

This is a placeholder method. Specific implementations/subclasses of Kinematics should replace this with methods which transform an orbit library LOSVD to that particular type of kinematics.

Parameters:

losvd_histogramsdyn.kinematics.Histogram

the LOSVD of an orbit library

weight_solver_settingsdict

weight solver settings

Returns:

object

the orbit library LOSVD transofrmed to observed kinematics

update(**kwargs)

Updates one or more attributes, including consistency check

Parameters:

**kwargsattribute=value pairs

Returns:

None.

Raises:

ValueError

If class attribute does not exist

Inheritance Diagram