API Reference

The ‘dqm’ package has one class, DQM, and several utility functions.

Everything can be imported directly from the package. Examples:

from dqm import DQM
from dqm import plot_frames, get_clusters

DQM Class

class dqm.DQM

This is the main class for using DQM (Dynamic Quantum Mapping).

The code has a reasonable number of error checks, but it’s a complicated system. The onus is currently on the user to make sure that the choice of parameter settings makes sense and that a given instance of the class doesn’t wind up in an inconsistent state.

Class variables:

Variables:: min_report_time – Report class-level execution times that are this many seconds or longer. Default 10.

Instance variables (general):

Variables:

verbose – Boolean: whether to report on various operations. Default True.
min_report_time – Report instance-level execution times that are this many seconds or longer. Default 10.
raw_data – The raw data (a 2-D matrix). Default None.
call_c – Boolean: whether to call compiled (C++) code. Default True if the module can find the compiled library, otherwise default False (with a printed warning).

Instance variables (for PCA):

Variables:

pca_transform – Boolean: whether to do PCA rotation/truncation of the raw data when creating frame 0. Default True. (If False, all other PCA settings are ignored.)
pca_num_dims – Integer number of PCA dimensions to use. Takes precedence over pca_var_threshold if set. Default None.
pca_var_threshold – Threshold used for choosing number of PCA dimensions to use, representing required proportion of total cumulative variance (e.g., 0.9) in the PCA dimensions used. Ignored if pca_num_dims is set. Default None.
raw_col_means – Stored column means of raw data. (Needed for PCA rotation/truncation of any new ‘out-of-sample’ points.) Default None.
pca_eigvals – Stored vector of PCA eigenvalues (in descending order). Default None.
pca_eigvecs – Stored matrix of PCA eigenvectors (columns correspond to entries in pca_eigvals). Default None.
pca_cum_var – Stored vector of proportional cumulative variance for the first n PCA dimensions. Default None.

Instance variables (for the basis):

Variables:

basis_size – Integer number of points to use in the basis. (All rows will be used by default for the basis if this value is not set.) Default None.
basis_num_chunks – Choose the basis by partitioning all rows into this number of ‘chunks’. (Multiple chunks offers a useful speedup when working with large numbers of rows.) Default 1.
basis_rand_seed – Random seed, used to choose a random starting row for the basis. Ignored if basis_start_with_outlier is True. Default 1.
basis_start_with_outlier – Boolean: whether to use the single greatest outlier row as the starting row for the basis. (Will be slow, O(n^2), for large numbers of points.) Default True.
basis_row_nums – Stored list of row numbers for rows in the basis. Default None.
non_basis_row_nums – Stored list of row numbers for rows not in the basis. Default None.
basis_rows – Stored matrix of basis rows (i.e., data for the basis rows, taken from frame 0). Default None.

Instance variables (for choosing sigma – see method ‘choose_sigma_for_basis’):

Variables:

overlap_min_threshold – Minimum overlap for non-basis rows. Default 0.5.
overlap_mean_threshold – Minimum mean overlap for non-basis rows. Default 0.9.
mean_row_distance – Stored estimated mean pairwise distance between rows in the data set. (See method ‘estimate_mean_row_distance’). Default None.

Instance variables (main DQM parameters):

Variables:

sigma – Width (standard deviation) of the multidimensional Gaussian placed around every data point. Default None.
mass – Value of mass assigned to each data point during DQM evolution. Typically set manually by the user less often than sigma (see method ‘default_mass_for_num_dims’). Default None.
step – Time step used during DQM evolution. Typically set manually by the user rarely or never. Default 0.1.

Instance variables (DQM operators):

Variables:

simt – Stored transpose of the ‘similarity’ matrix, used to convert state vectors from the ‘raw’ basis to the orthonormal basis of eigenstates. Default None.
xops – Stored 3-D array of position-expectation operator matrices. (Each slice in 3rd dim is the operator matrix for the corresponding column/dimension in 2nd dim in ‘frames’.)
exph – Stored ‘evolution’ operator matrix. (This is the exponentiated time-evolution Hamiltonian operator matrix.) Has complex values. Default None.

Instance variables (frames):

Variables:

stopping_threshold – A given data point is considered to have ‘stopped’ when it moves less than this distance from one frame to the next frame. Typically is automatically set to mean_row_distance / 1e6, but can be set manually. Default None.
frames – Stored 3-D array of frames: <num rows x num dims x num frames>. First slice in 3rd dim contains the original data (possibly PCA rotated/truncated), stored here before evolution has taken place. Default None.

build_frames(num_frames_to_build=100, frames=None, pare_frames=True, verbose=None)

Build new frames in a DQM evolution and concatenate them with existing frames.

Instance must have basis rows, operators, and positive sigma.

If ‘frames’ is passed in, we return all frames (old and new together). otherwise, we set self.frames to be all frames (old and new together) and return None.

Stopped rows are not evolved further. (A row is ‘stopped’ when it fails to move at least self.stopping_threshold distance from one frame to the next.)

Parameters:

num_frames_to_build – Number of new frames to build. Default 100.
frames – 3-D array of existing frames (<num rows x num dims x num frames>). If None, we use self.frames. Default None.
pare_frames – Boolean: if True, we delete any final frames where nothing is changing. Default True.
verbose – Boolean: if not None, overrides self.verbose. Default None.

Returns:

If ‘frames’ was passed in, we return all frames (old and new together). Otherwise, we return None.

build_frames_auto(batch_size=100, frames=None, pare_frames=True, max_num_frames=10000)

Add new frames in batches (by calling build_frames) until all rows have stopped.

If ‘frames’ is passed in, we return all frames (old and new together). Otherwise, we set self.frames to be all frames (old and new together) and return None.

Parameters:

batch_size – Number of new frames to add in each batch. Default 100.
frames – 3-D array of frames (<num rows x num dims x num frames>). If None, we use self.frames. Default None.
pare_frames – Boolean: if True, we delete any final frames where nothing is changing. Default True.
max_num_frames – Maximum number of frames, including any initial frames. Default 10,000. (This parameter is important because a too small value of mass can cause data points to oscillate around a minimum – overshooting the minimum at each step – meaning that they will never stop moving.)

Returns:

If ‘frames’ was passed in, we return all frames (old and new together). Otherwise, we return None.

build_operators(n_potential=None)

Build the DQM operators and store them in the instance.

If basis has not been set, we use all rows as the basis by default. (For large numbers of rows, this default will be unusably slow.)

Note: the relative order of the basis rows is baked into the operators, so the relative ordering of the basis rows must not change later (when building frames).

The operators are:

simt: Transpose of ‘similarity’ matrix, which converts state vectors from ‘raw’ basis of basis rows to orthonormal basis of eigenstates. Dimensions: <num basis vectors x num basis rows>.
xops: 3-D array, where slice i in 3rd dimension is the position-expectation operator matrix for data dimension i (in 2nd dimension in frames). Dimensions: <num basis vectors x num basis vectors x num dims>.
exph: Complex-valued ‘evolution’ operator matrix (the exponentiated time-evolution Hamiltonian operator matrix). Dimensions: <num basis vectors x num basis vectors>.

Parameters:: n_potential – USED MAINLY FOR DEBUGGING AND SPEED TESTING. Use this number of rows to build the potential, starting from the first row. If None, we use all rows (not just the basis rows). Default None.
Returns:: None

build_overlaps(rows=None, row_nums=None, sigma=None, batch_size=100000, verbose=None)

Build basis overlaps for a given set of rows.

If ‘rows’ is passed in, we build overlaps for those rows. Otherwise, if row_nums is passed in, we build overlaps for those rows. Otherwise, we build overlaps for all non-basis rows.

‘Overlap’ is a measure of how well a given data point is represented by the basis. Basis points will all have an overlap of 1, meaning perfect representation. (For technical details, see the section on “Reconstruction of Wave Functions in the Eigenbasis” in the technical-summary document “Understanding DQM”.)

Parameters:

rows – 2-D array of data rows. Takes precedence if not None. Default None.
row_nums – List of row numbers, used if rows is None. Default None.
sigma – Value of sigma. If None, we use self.sigma. Default None.
batch_size – Number of rows in a batch. (For very large numbers of rows, memory management can become an issue.) Default 100,000.
verbose – Boolean: if not None, overrides self.verbose. Default None.

Returns:

Vector containing scalar overlap value for each row.

choose_basis_by_distance()

Choose and store a set of basis rows, based on Euclidean distance, and store the results.

self.basis_size must be set to a positive number less than the number of rows in self.frames (which must exist).

First basis row: if self.basis_start_with_outlier is True, we use the largest outlier (with the farthest nearest neighbor) as the first basis row. Otherwise, we choose a random row as the first basis row.

Subsequent basis rows: we choose the non-basis row whose closest distance to any current basis row is largest, until the desired basis size is reached.

If self.basis_num_chunks is > 1, we partition all rows into ‘chunks’ and choose basis rows separately for each chunk. (This is faster but less ‘accurate’, since 2 basis rows in 2 different chunks may be arbitrarily close to each other.)

Returns:: None

choose_sigma_for_basis(batch_size=None, num_batches_to_test=10, rand_seed=11)

Choose the smallest value of sigma that meets overlap-threshold requirements (self.overlap_min_threshold and self.overlap_mean_threshold) for non-basis rows.

self must already have frame 0 (in self.frames) and a selected basis that is smaller than the total number of rows (i.e., not a ‘full’ basis).

We set self.sigma to the final resulting value of sigma.

Default values for the arguments are good enough in most cases. (The ‘batch’ mode is for handling large numbers of non-basis rows more efficiently.)

Parameters:

batch_size – Number of rows in a single batch. if None, test all non-basis rows at once. Default None.
num_batches_to_test – Number of batches that must return the same value of sigma before we’re done (if batch_size is not None). Default 10.
rand_seed – random seed for shuffling the order of non-basis row numbers. Default 11.

Returns:

None

clear_basis()

Clear instance variables storing information about the basis, INCLUDING self.basis_size.

Use this method to clear a basis when you want to return to the default behavior of using all rows as the basis.

Returns:: None

clear_frames(keep_frame_0=True)

Keep frame 0 and clear all frames in self.frames after frame 0.

(Note that create_frame_0 and build_operators will both fail if self.frames has multiple frames in 3rd dim. This is to prevent accidental loss of information, particularly since building frames can be slow.)

Parameters:: keep_frame_0 – Boolean: if False, we set self.frames to None. default True.
Returns:: None

clear_pca()

Clear all PCA results (self.raw_col_means, self.pca_eigvals, self.pca_eigvecs and self.pca_cum_var).

Returns:: None

create_frame_0(dat_raw=None, _num_pca_dims=None)

Create frame 0 from raw data.

If dat_raw is passed in, we return the created frame 0. Otherwise, we use self.raw_data and store the created frame 0 in self.frames.

If self.pca_transform is True, frame 0 will be the PCA-rotated/truncated coordinates of each row. Otherwise, frame 0 will simply be the raw data.

Note: if dat_raw is passed in and pca_transform is True, we apply the ‘in-sample’ PCA rotation/truncation derived originally from self.raw_data. It’s important that any new ‘out-of-sample’ points be transformed using the in-sample PCA transformation. (For more detail, see the discussion of running new points in the user guide.)

Parameters:

dat_raw – A raw-data matrix. if None, we use self.raw_data. default None.
_num_pca_dims – ONLY USED BY INTERNAL CODE. Use self.pca_num_dims or self.pca_var_threshold instead. Default None.

Returns:

If ‘dat_raw’ was passed in, we return frame 0. otherwise, we return None.

default_mass_for_num_dims(num_dims=None)

Use a simple heuristic formula (derived from random-data experiments) to return a suggested default value of mass for a given number of dimensions:

mass = -1 + 2 * log10(num_dims)

We set a minimum default mass of 1, which overrides the heuristic for small numbers of dimensions (< 10), to avoid oscillation caused by a ‘too transparent’ landscape.

Important note: for any given data set, the effective dimensionality of the data cloud might be significantly lower than the number of dimensions being used, which could affect the appropriateness of the suggested value of mass. We make no attempt to deal with that issue here.

Parameters:: num_dims – Number of dimensions. if None, we attempt to infer the number of dimensions from self.frames (by size of 2nd dim). Default None.
Returns:: Suggested default mass value for the given number of dimensions.

estimate_mean_row_distance(rel_err_threshold=0.01, rand_seed=500)

Estimate the mean pairwise distance between rows in frame 0. (self.frames must exist.)

Use a successively larger number of row pairs to estimate the overall mean distance, until the ‘relative error’ (standard error of the mean divided by the mean) drops below rel_err_threshold.

The final result is stored in self.mean_row_distance.

Parameters:

rel_err_threshold – Threshold for ‘relative error’ (standard error of mean divided by mean). Must be positive. Default 0.01.
rand_seed – Random seed for choosing row pairs for distance calculations. Default 500.

Returns:

None

classmethod exists(main_dir, sub_dir=None)

Check whether main_dir contains a saved DQM instance. If sub_dir is not None, also check whether sub_dir contains saved DQM info.

Parameters:

main_dir – Relative or absolute path to a folder. No default.
sub_dir – Name of subdirectory (inside the ‘main_dir’ folder) for landscape-specific saved data. Default None.

Returns:

Boolean: True if main_dir contains a saved DQM instance. (If sub_dir is not None, sub_dir must also have saved landscape-specific DQM info in order for us to return True.)

classmethod load(main_dir, sub_dir=None, load_raw_data=True, verbose=True)

Load an instance of the DQM class from disk and return it.

Parameters:

main_dir – Relative or absolute path to folder. No default.
sub_dir – Name of subdirectory (inside the ‘main_dir’ folder) for landscape-specific saved data. Default None.
load_raw_data – Boolean: if True, we load raw data. Set to False to save time if raw data is very large. Default True.
verbose – Boolean: whether to report on various operations. Default True.

Returns:

a DQM instance with data loaded from ‘main_dir’ (and from sub_dir, if not None).

pare_frames(frames)

Drop any duplicate frames (where frame n + 1 is identical to frame n) at the end of an evolution.

Parameters:: frames – A 3-D array of frames. No default.
Returns:: A pared 3-D array of frames (which will be a reference to the frames passed in if no frames were dropped).

pca_projection(dat_raw=None, num_pca_dims=None)

Apply PCA ‘projection’ (centering + rotation + truncation) to a raw data matrix, as follows:

Center the columns by subtracting self.raw_col_means (which must exist).
Create a rotated and truncated matrix by applying the combination of self.pca_eigvecs (rotation) and the number of PCA dimensions being used (truncation). (Number of PCA dimensions can be specified via the num_pca_dims parameter. If num_pca_dims is None, we infer the number of PCA dimensions being used from the 2nd dimension of self.frames, which must then exist.)
Calculate the proportional norms for each row in the raw data – meaning, the centered/rotated/truncated L2 norm divided by the centered-only L2 norm.

The instance must have stored PCA results.

Importantly, if dat_raw is passed in, we apply the ‘in-sample’ PCA projection based on the original self.raw_data, not based on this new raw data. (For more detail, see the discussion of running new points in the user guide.)

Parameters:

dat_raw – 2-D raw-data matrix. If None, we use self.raw_data. Default None.
num_pca_dims – Number of PCA dimensions to use in the projection. If None, we infer from the number of columns in 2nd dimension of self.frames (which must then exist). default None.

Returns:

A vector of proportional norms (projected / original) for each row.

plot_pca(num_dims=None)

Display 3 PCA plots:

normalized eigenvalues (all divided by first eigenvalue)

log10 of normalized eigenvalues

proportional cumulative variance of data (all divided by total variance of data)

Note: an assertion will fail if the Matplotlib PyPlot module is not loaded.

Parameters:: num_dims – Number of PCA dimensions to show in the plots. Default None (meaning show all PCA dims).
Returns:: None

run_new_points(dat_raw_oos)

Given dat_raw_oos, which is a raw-data matrix of new (‘out-of-sample’) points:

Apply the ‘in-sample’ PCA projection (subtract in-sample column means, apply in-sample PCA rotation, and truncate to in-sample number of PCA dimensions being used).
Build basis overlaps for the new points.
Evolve the new out-of-sample points, using the in-sample map (that is, the stored DQM operators), to as many frames as currently exist in self.frames.

Important note: for running new out-of-sample points to make sense, the new raw data must be preprocessed in exactly the same way that the original raw data was.

Parameters:

dat_raw_oos – A 2-D raw-data matrix of new ‘out-of-sample’ points. Must have the same number of columns as self.raw_data.

Returns:

A tuple of:

frames_oos: 3-D array of out-of-sample evolved frames
overlaps_is: vector of in-sample basis overlaps (for all non-basis rows)
overlaps_oos: vector of out-of-sample basis overlaps
norm_props_is: vector of in-sample proportional norms (projected L2 norms divided by original L2 norms)
norm_props_oos: vector of out-of-sample proportional norms (projected L2 norms divided by original L2 norms)

run_pca()

Run PCA on self.raw_data (which must exist) and store results.

Returns:: None

run_simple(dat_raw, sigma)

Do a simplified full DQM ‘run’, as follows – given dat_raw (raw-data matrix) and a value of sigma:

Store raw data and sigma in the instance.
Create and store frame 0 (using all PCA dimensions)
Build and store operators (using a full basis and default value of mass)
Build and store frames (using build_frames_auto) until all points stop moving

Note: default behaviors can be overridden by setting relevant instance parameters before calling this method.

For small data sets, doing simple runs with various values of sigma can be the quickest way to understand the landscape that DQM is revealing.

Parameters:

dat_raw – Raw data (2-D matrix).
sigma – Positive value for sigma.

Returns:

None

save(main_dir, sub_dir=None)

Save an instance of the DQM class:

Save numpy arrays separately.
Pickle everything else in the instance.

Things that are common to multiple landscapes (raw data, PCA results) are saved in main_dir, which can be an absolute or relative path to a folder.

Things that are specific to a given landscape (basis, DQM parameters, operators, evolved frames) are saved in sub_dir, which is relative to main_dir (so, typically sub_dir is just a folder name)

Both main_dir and sub_dir (if not None) are created if they do not exist.

Parameters:

main_dir – Relative or absolute path to a folder. No default.
sub_dir – Name of subdirectory (inside the ‘main_dir’ folder) for basis-specific saved data. Default None.

Returns:

None

set_stopping_threshold()

Set self.stopping_threshold to self.mean_row_distance / 1e6. (First call self.mean_row_distance, if needed.)

Returns:: None.

Utility Functions

dqm.utils.add_bookend_frames(frames, num_bookend_frames)

Add ‘bookend’ frames at beginning and end of a set of frames – bookend frames are just duplicates of the first and last frames. (Bookend frames can make an animation playing on repeat much easier to follow.)

Parameters:

frames – 3-D array of frames: <num rows x num dims x num_frames>.
num_bookend_frames – number of bookend frames to add at beginning and end of frames.

Returns:

New array of frames with bookend frames added.

dqm.utils.cat_frames(frames1, frames2=None)

Given multiple sets of frames, concatenate them in 1st dim.

All sets of frames must have the same number of columns in 2nd dim.

If the numbers of frames in 3rd dim don’t match in each set of frames, we replicate the last frame in each set as needed.

Parameters:

frames1 – 3-D array of frames, or list of 3-D arrays of frames. If it’s a list, we cat together all sets of frames in the list and return the result. No default.
frames2 – 3-D ndarray of frames. Must be None if frames1 is a list. Default None.

Returns:

New combined 3-D array of frames.

dqm.utils.get_clusters(mat, max_dist)

Get clusters from a matrix.

We here define a cluster as a group of rows such that every row is within max_dist Euclidean distance of at least one other row in the cluster. The largest distance between 2 rows in a cluster may be much larger than max_dist. (‘Cluster’ is defined here in a way that will include extended structures.)

Parameters:

mat – A 2-D real-valued matrix. No default.
max_dist – A row being within max_dist Euclidean distance of any other row in a cluster will make that row part of that same cluster. No default.

Returns:

A tuple of:

a list of lists of row numbers for the clusters. the list of clusters is sorted by cluster size (number of rows), in descending order.
a parallel list of cluster sizes

dqm.utils.nearest_neighbors(mat)

Return nearest-neighbor row number and distance for each row in mat.

Parameters:

mat – A 2-D real-valued matrix. No default.

Returns:

A tuple of:

Vector of nearest-neighbor row number for each row.
Vector of nearest-neighbor distance for each row.

dqm.utils.pca(mat, verbose=True)

Given a matrix, compute and return the PCA eigenvalues and associated eigenvectors (principal components).

Parameters:

mat – A 2-D real-valued matrix.
verbose – Boolean: whether to report on various operations. Default True.

Returns:

A tuple of:

Vector of eigenvalues, in descending order of magnitude (all are non-negative).
Matrix with corresponding eigenvectors (principal components) in the columns.

dqm.utils.plot_frames(frames, color='blue', size=5, skip_frames=1, fps=10, title='', labels=['X', 'Y', 'Z'], width=800, height=800, show_as_cube=True, show_gridlines=True, show_ticklabels=True)

Display interactive animated 3-D plot of a set of frames, using Plotly.

WARNING – WHEN PLOTTING LARGE NUMBERS OF POINTS AND/OR FRAMES:

File sizes can get very big for saved plots. (This may be a problem if, for example, you’re working in a Jupyter notebook with autosave turned on.)

Specifying different colors and/or different sizes for each frame will make rendering take much longer.

Parameters:

frames – 2-D or 3-D array of frames. If there are more than 3 columns in 2nd dim, we use the first 3 columns for plotting. Animation is only enabled if there are multiple frames in 3rd dim. No default.
color –
Color information for points – can be:
- String (must be a color understood by Plotly), applied to all points. Default ‘blue’.
- Array/list/tuple of length 3 (RGB) or 4 (RGBA), with float values in [0, 1], applied to all points.
- 2-D array, <num_rows x 3 (RGB) or 4 (RGBA)>, with float values in [0, 1], applied to each point in all frames.
- 3-D array, <num_rows x 3 (RGB) or 4 (RGBA) x num_frames>, with float values in [0, 1], applied to each point in each frame. (If using skip_frames > 1, frames and colors should line up as passed in – both will be subselected.)
size –
Size information for points – can be:
- Scalar, applied to all points. default 5.
- 1-D array, <num_rows>, applied to each point in all frames.
- 2-D array, <num_rows x num_frames>, applied to each point in each frame. (If using skip_frames > 1, frames and sizes should line up as passed in – both will be subselected.)
skip_frames – Positive integer: if > 1, plot every nth frame (so, for a value of 2, plot every other frame). Default 1. (This feature is useful because plotting a large number of frames can be slow and memory-intensive.)
fps – Frames per second. Default 10. (Plotly may not be able to handle a frame rate much larger than 10 or 15 fps. You can use skip_frames to help with this.)
title – Title for the plot. Default “”.
labels – Array/list/tuple of axis labels, or None. Default [‘X’, ‘Y’, ‘Z’].
width – Figure width in pixels. Default 800.
height – Figure height in pixels. Default 800.
show_as_cube – Boolean: if True show plot as a cube, if False show plot with correct axis-range proportions. Default True.
show_gridlines – Boolean: whether to show gridlines. Default True.
show_ticklabels – Boolean: whether to show axis tick labels. Default True.

Returns:

None

dqm.utils.plot_frames_ipv(frames, color='blue', size=4, skip_frames=1, fps=10, labels=['X', 'Y', 'Z'], show_axes=True)

Display interactive animated 3-D plot of a set of frames, using IPyVolume.

WARNING: IPyVolume is not a fully mature/stable package – it may be buggy. (However, it may handle large numbers of data points and/or frames much better than Plotly will in plot_frames.)

Parameters:

frames – 2-D or 3-D array of frames. If there are more than 3 columns in 2nd dim, we use the first 3 columns for plotting. Animation is only enabled if there are multiple frames in 3rd dim. No default.
color –
Color information for points – can be:
- String (must be a color understood by Plotly), applied to all points. Default ‘blue’.
- Array/list/tuple of length 3 (RGB) or 4 (RGBA), with float values in [0, 1], applied to all points.
- 2-D array, <num_rows x 3 (RGB) or 4 (RGBA)>, with float values in [0, 1], applied to each point in all frames.
- 3-D array, <num_rows x 3 (RGB) or 4 (RGBA) x num_frames>, with float values in [0, 1], applied to each point in each frame. (If using skip_frames > 1, frames and colors should line up as passed in – both will be subselected.)
size –
Size information for points – can be:
- Scalar, applied to all points. default 4.
- 1-D array, <num_rows>, applied to each point in all frames.
- 2-D array, <num_rows x num_frames>, applied to each point in each frame. (If using skip_frames > 1, frames and sizes should line up as passed in – both will be subselected.)
skip_frames – Positive integer: if > 1, plot every nth frame (so, for a value of 2, plot every other frame). Default 1.
fps – Frames per second. default 10.
labels – Array/list/tuple of axis labels. default [‘X’, ‘Y’, ‘Z’].
show_axes – Boolean: whether to show axes (axis label and tick labels). ‘labels’ is ignored if this is False. default True.

Returns:

None

dqm.utils.rescale_frames(frames)

Rescale each frame so that the first column always has the same scale.

This function is useful for ‘zooming in’ on structures that shrink as DQM evolution proceeds.

We do the following separately for each frame:

center all columns (by subtracting the mean from each)

divide all columns by the range (max value minus min value) of the first column

Parameters:: frames – 3-D array of frames. No default.
Returns:: Rescaled frames.

dqm.utils.smooth_frames(frames, num_new_frames=100, acc_mult=1, verbose=True)

Given a 3-D array of frames, interpolate new frames based on a target average speed between frames.

This function is useful for highlighting the most interesting parts of a DQM evolution. (A common ‘problem’ is waiting hundreds of frames for the last few points to stop moving.)

Parameters:

frames – 3-D array of frames. No default.
num_new_frames – Number of frames to create in the output. Default 100.
acc_mult – Acceleration multiplier. Must be positive. If starting average speed of points (between first 2 output frames) is S, final average speed (between last 2 output frames) will be acc_mult * S. Default 1 (constant average speed for moving points).
verbose – Boolean: whether to report progress. Default True.

Returns:

New 3-D array of smoothed frames.