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([weight, type, hist_width, ...])

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

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)

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_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([max_gh_check])

Get max order GH coeeff from data table

get_observed_values_and_uncertainties(...)

Extract mean/sigma from the GH kinematics

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_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

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=None)

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(max_gh_check=20)

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

Parameters:
max_gh_checkint, optional

check up to this order

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_settingstype

Description of parameter weight_solver_settings.

Returns:
tuple

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

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_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_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(weight=None, type=None, hist_width='default', hist_center='default', hist_bins='default', **kwargs)

Abstract class for Kinematics

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

Methods:

get_observed_values_and_uncertainties(...)

Extract mean and uncertainties from the kinematic set

transform_orblib_to_observables(...)

trasform orbit library to observed kinematics

update(**kwargs)

Updates one or more attributes, including consistency check

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)

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

Inheritance diagram of kinematics