Outer Functions

Functions in the outermost folder contain the most general operations.

Matrix Operations (fns.mat)

Contains functions that can be applied to any matrix. Includes functions that normalize, resize, and concatenate matricies.

fns.mat.normalize01(item)

Function to normalize an array between 0 and 1

Parameters

item (npt.ArrayLike) – array to be normalized (typically rho, activation features, etc)

Returns

item (npt.ArrayLike) – normalized array

fns.mat.normalize_mat(mat, norm)

Function to extract the features from a given layer of a model

Parameters

  • mat (npt.ArrayLike) – 3D tensor to be normalized

  • norm (str) – {‘ft01’, ‘all01’, ‘none’} a string to indicate which normalization methodology to use; ‘ft01’ normalizes each tensor element between 0 and 1 (using min/max of that element); ‘all01’ normalizes entire tensor between 0 and 1 (using min/max of entire tensor); ‘none’ does not normalize the tensor

Returns

new_mat (np.array) – normalized tensor

See also

fns.mat.normalize01()

fns.mat.matrix_padding(mat, x, y)

Function to add zero padding to a matrix to match some size

Dimensions of mat must be smaller than (y, x)

Parameters

  • mat (npt.ArrayLike) – 2D array

  • x (int) – desired width (no. of columns)

  • y (int) – desited height (no. of rows)

Returns

mat_pad (np.ndarray) – an array with new size (y, x)

fns.mat.matrix_cutting(mat, x, y)

Function to cut a matrix down to match some size

Dimensions of mat must be larger than (y, x)

Parameters

  • mat (npt.ArrayLike) – 2D array

  • x (int) – desired width (no. of columns)

  • y (int) – desired height (no. of rows)

Returns

mat_cut (npt.ArrayLike) – an array with new size (y, x)

fns.mat.matrix_scale(mat, x, y)

Function to scale a matrix to match some size

Parameters

  • mat (np.ndarray) – single array (2D)

  • x (int) – desired width (no. of columns)

  • y (int) – desired height (no. of rows)

Returns

mat_scaled (np.ndarray) – an array with new size (x, y)

fns.mat.concat_avg(matrix, axis=0, spacer=True)

Function to expand an array to include the absolute value averages of it’s rows or columns, with or without a spacer of zeros between original matrix and averages

Parameters

  • matrix (npt.ArrayLike) – starting array

  • axis (int) – {0, 1}: axis to take average along, =0 for columns, =1 for rows

  • spacer (bool) – whether or not to include a spacer of zeros between original matrix and averages

Returns

avg_matrix (np.ndarray) – a copy of the starting matrix with the average concatenated

fns.mat.scalar_2Dcorr(f, g)

Function to compute the sclar cross-correlation of two 2D arrays

Uses first formula from https://en.wikipedia.org/wiki/Digital_image_correlation_and_tracking considering i = j = 0
Equivalent to pearson correlation coefficient
Parameters

  • f (npt.ArrayLike) – 2D array

  • g (npt.ArrayLike) – 2D array

Returns

r (float) – 2D discrete cross correlation

fns.mat.get_statsig(corr, pvals, threshold=0.05)

Function to extract the statistically significant values from a matrix of correlation coefficients

Parameters

  • corr (npt.ArrayLike) – matrix of correlation coefficients

  • pvals (npt.ArrayLike) – matrix of p-values corresponding to coorrelation coefficients

  • threshold (float) – p-value cuttoff for significance (if p-val > threshold, correlation coefficient is discarded)

Returns

statsig (npt.ArrayLike) – a matrix of correlation coefficients with non-stattistically-significant values set to zero

Misc Operations (fns.misc)

Contains functions that don’t fit into any existing category.

fns.misc.warning_on_one_line(message, category, filename, lineno, file=None, line=None)

Function to reformat warnings.warn() to display all on one line

Code from: http://pymotw.com/2/warnings/

To use: warnings.formatwarning = fns.misc.warning_on_one_line

fns.misc.search_list(list_l, query)

Function to return the list of elements that contain the query from a masterlist

Parameters

  • list_l (list) – masterlist of strings to be searched

  • query (str) – key to search elements of masterlist for

Returns

elements (list) – list of elemenmts from the masterlist that contain the query

fns.misc.find_path(me, goal)

Function to return the path to the goal directory, looking starting at the me directory and moving outwards

Parameters

  • me (str) – the directory to start searching from

  • goal (str) – the directory to find

Returns

path (str) – absoulte path to the goal directory; will return “none” if path could not be found with less than 5 steps out of starting directory

fns.misc.load_filelist(file_list_path)

Function to parse a file list path into an array of sample paths

Parameters

file_list_path (str) – path to .txt file containing list of samples

Returns

  • num_samples (int) – number of samples in the sample list

  • sample_list (np.array) – array of file paths to .npz samples

Save Operations (fns.save)

Contains functions to save neural network outputs, such as features.

fns.save.makefilelist(search_dir, num_samples, save_path='None', save=True)

Function to make list of .npz files to sample from

Parameters

  • search_dir (str) – file path to directory to search for samples in; include any restrictions for file name

  • num_samples (str) – integer number of samples to include, or ‘All’ for all samples found

  • save_path (str) – path to save .txt file contianing list of samples

  • save (bool) – boolean for if the sample list is saved to a .txt file

Returns

  • num_samples (int) – number of samples in the sample list

  • sample_list (np.ndarray[str]) – array of file paths to .npz samples; if save=True,sample_list is also saved to a .txt file

fns.save.features2npz(ft_mat, save_path, ft_suffix='')

Function to save extracted features (or other simialr objects) to an .npz file

Parameters

  • ft_mat (np.ndarray[(any, any, any), float]) – tensor of all features

  • save_path (str) – path to save .npz file

  • ft_suffix (str) – suffix to append to the .npz internal file names (deafult file names are “feature#”)

Returns

No Return Objects

fns.save.fields2npz(fld_mat, fields, save_path, suffix='')

Function to save extracted features (or other simialr objects) to an .npz file

Parameters

  • fld_mat (np.ndarray[(any, any, any), float]) – tensor of all fields

  • fields (list[str]) – names of fields

  • save_path (str) – path to save .npz file

  • suffix (str) – suffix to append to the .npz internal file names (deafult file names are “field”)

Returns

No Return Objects

Plotting Operations (fns.plot)

Contains functions relate to or make matplotlib.pyplot plots. Includes functions to create custom colormaps, plot features, and plot heatmaps.

fns.plot.split_ticks(labels, ticks)

Function split a set of axis ticks and labels into major and minor ticks and labels

Parameters

  • labels (npt.ArrayLike) – Array of labels for radial axis

  • ticks (npt.ArrayLike) – Array of pixel locations where tick marks go, corresponding to labels

Returns

  • MajorLabels (npt.ArrayLike) – Array of labels for major radial axis

  • MajorTicks (npt.ArrayLike) – Array of pixel locations where major axis tick marks go, corresponding to MajorLabels

  • MinorTicks (npt.ArrayLike) – Array of pixel locations where minor tick marks go, corresponding to labels not included in MajorLabels

fns.plot.custom_colormap(color1, color2, alpha1, alpha2)

Function to make a custom colormap for values [0,1]

Function creates two global callable mpl colormaps:

  • Colormap Object c_map with name “my_cmap” is a two color gradient from color1 –> color2, with an alpha1 –> alpha2 opacity gradient

  • Colormap Object new_cmap with name “new_cmap” is a two color gradient from color1 –> color2, with an alpha1 –> alpha2 opacity gradient, with the zero value replaced with 100% transparent white

Parameters

  • color1 (str) – name of the first color in the color gradient, must be in the matplotlib CSS4 color list

  • color2 (str) – name of the last color in the color gradient, must be in the matplotlib CSS4 color list

  • alpha1 (float) – [0,1] value of first opacity in the gradient (0=full transparency, 1=full opacity)

  • alpha2 (float) – [0,1] value of last opacity in the gradient (0=full transparency, 1=full opacity)

Returns

No Return Objects

fns.plot.feature_plot(field, ft, Rlabels, Rticks, Zlabels, Zticks, RMinorTicks=False, ZMinorTicks=False, lims=[0, 1], c_map='new_cmap', resize='scale')

Function to plot one extracted feature over a given hydrodynamic field

Function will plot feature over field image on existing mpl axes and will adjust axis ticks/labels appropriately

Parameters

  • field (np.ndarray[(any, any), float]) – picture to underlay the feature (typically radiographic fields)

  • ft (np.ndarray[(any, any), float]) – single extracted feature array; assumed the ft array is the same size or smaller than the field array

  • Rlabels (np.ndarray[str]) – Array of labels for radial axis

  • Rticks (np.ndarray[int]) – Array of pixel locations where tick marks go, corresponding to Rlabels

  • Zlabels (np.ndarray[str]) – Array of labels for vertical axis

  • Zticks (np.ndarray[int]) – Array of pixel locations where tick marks go, corresponding to Zlabels

  • lims (list[float, float]) – array of colorbar limits

  • c_map (str) – name of color map to plot the activation intensity with; default “new_cmap” is a custom colormap creaated by the custom_colormap function

  • resize (str) – {‘cut’, ‘pad’, ‘scale’, ‘None’} method of resizing feature and field arrays to be the same size; ‘pad’ adds zeros to border of feature; ‘cut’ removes borders of field; ‘scale’ upsamples feature to be same size as field; ‘None’ implies the feature and field are already the same size

  • RMinorTicks (bool) –

  • ZMinorTicks (bool) –

Returns

im (mpl.image.AxesImage) – the mpl image object of just the feature plot (does NOT contain field_pic image)

See also

fns.coupondata.get_ticks() and fns.nestedcylinderdata.get_ticks() to generate Rlabels, Rticks, Zlabels, Zticks

fns.plot.custom_colormap() to generate colormap “new_cmap”

fns.plot.heatmap_plot(matrix, xticklabels, yticklabels, xlabel, ylabel, title, save_path, grid=False)

Function to plot a matrix heatmap with labeled cells

Parameters

  • matrix (np.ndarray[(any, any), float]) – matrix to plot

  • xticklabels (np.ndarray[str]) – array of tick labels for the x-axis

  • yticklabels (np.ndarray[str]) – array of tick labels for the y-axis

  • xlabel (str) – label for the x-axis

  • ylabel (str) – label for the y-axis

  • title (str) – title for plot

  • save_path (str) – path to save figure to

  • grid (bool) – determines if the matrix grid is visible or not

Returns

No Return Objects