PyPI: pypiV pypiDM
Help! Documentation Status Join the chat at https://gitter.im/jat255/FIBtortuosity

Module Method Summary

tortuosity_from_labels_x(electrolyte_fname, ...) Calculate the tortuosity (normal to electrolyte interface, x-direction)
tortuosity_from_labels_y(electrolyte_fname, ...) Calculate the tortuosity (parallel to electrolyte interface, y-direction)
tortuosity_from_labels_z(electrolyte_fname, ...) Calculate the tortuosity (parallel to electrolyte interface, z-direction)
calculate_geodesic_distance(...[, units, ...]) Calculate the geodesic distance of an indexed tif file.
save_results([fname, phase, direction, ...]) Saves all the results into a compressed numpy archive
load_results(fname) Loads the results that have been previously saved with save_results()
run_full_analysis_lsm_ysz(electrolyte_file, ...) Run full tortuosity analysis for LSM/YSZ, calling other functions as necessary.
save_as_tiff(fname, data, dtype, desc) Save a numpy array as tiff (useful for transferring data back to Avizo)
tortuosity_profile(tort, euc[, axis]) Calculate the average tortuosity along an axis
plot_tort_prof(tort_prof, euc_prof, direction) Plot a profile of the average tortuosity.
save_profile_to_csv(fname, x, y, direction, ...) Saves two profiles (x and y) into a text file.
load_profile_from_csv(fname[, delimiter, ...]) Loads columns of a text file into 1D numpy arrays.
_geo_dist(data, vox_x, vox_y, vox_z) Internal helper method to call scikit-fmm distance method
_calc_interface(electrolyte_data) Calculates interface between bulk electrolyte and the cathode
_calc_tort(geo_d, euc_d, electrolyte_data) Calculates tortuosity from geodesic and euclidean distances
_calc_euc_x(x_interface, electrolyte_data, vox_x) Calculates euclidean distance from electrolyte interface

Module API Documentation

fibtortuosity.tortuosity_from_labels_x(electrolyte_fname, phase_fname, phase, units='nm', print_output=True, save_output=False)[source]

Calculate the tortuosity (normal to electrolyte interface, x-direction) from supplied label fields

Parameters:
  • electrolyte_fname (str) – Filename of a 3D tiff file that contains only the bulk electrolyte labelfield (as 1 values)
  • phase_fname (str) – Filename of a 3D tiff file that contains the bulk electrolyte and the phase for which the geodesic distance is to be calculated
  • phase (str) – Phase that is being calculated. i.e. ‘pore’, ‘LSM’, ‘YSZ’, etc.
  • units (str) – units of the given dimensions
  • print_output (bool) – switch to control whether output is printed
  • save_output (bool) – switch to control whether data is saved to .npz files for later recall
Returns:

  • geo_d (np.array) – Numpy array with geodesic distance from supplied surface
  • euc_d (np.array) – Numpy array with euclidean distance from electrolyte
  • tort (np.array) – Numpy array with tortuosity at each point
  • desc (str) – description string to be used when saving the file with save_as_tiff() (for proper reading into Avizo)
fibtortuosity.tortuosity_from_labels_y(electrolyte_fname, phase_fname, phase, units='nm', print_output=True, save_output=False)[source]

Calculate the tortuosity (parallel to electrolyte interface, y-direction) from supplied label fields

Parameters:
  • electrolyte_fname (str) – Filename of a 3D tiff file that contains only the bulk electrolyte labelfield (as 1 values)
  • phase_fname (str) – Filename of a 3D tiff file that contains the bulk electrolyte and the phase for which the geodesic distance is to be calculated
  • phase (str) – Phase that is being calculated. i.e. ‘pore’, ‘LSM’, ‘YSZ’, etc.
  • units (str) – units of the given dimensions
  • print_output (bool) – switch to control whether output is printed
  • save_output (bool) – switch to control whether data is saved to .npz files for later recall
Returns:

  • geo_d (np.array) – Numpy array with geodesic distance from supplied surface
  • euc_d (np.array) – Numpy array with euclidean distance from electrolyte
  • tort (np.array) – Numpy array with tortuosity at each point
  • desc (str) – description string to be used when saving the file with save_as_tiff() (for proper reading into Avizo)
fibtortuosity.tortuosity_from_labels_z(electrolyte_fname, phase_fname, phase, units='nm', print_output=True, save_output=False)[source]

Calculate the tortuosity (parallel to electrolyte interface, z-direction) from supplied label fields

Parameters:
  • electrolyte_fname (str) – Filename of a 3D tiff file that contains only the bulk electrolyte labelfield (as 1 values)
  • phase_fname (str) – Filename of a 3D tiff file that contains the bulk electrolyte and the phase for which the geodesic distance is to be calculated
  • phase (str) – Phase that is being calculated. i.e. ‘pore’, ‘LSM’, ‘YSZ’, etc.
  • units (str) – units of the given dimensions
  • print_output (bool) – switch to control whether output is printed
  • save_output (bool) – switch to control whether data is saved to .npz files for later recall
Returns:

  • geo_d (np.array) – Numpy array with geodesic distance from supplied surface
  • euc_d (np.array) – Numpy array with euclidean distance from electrolyte
  • tort (np.array) – Numpy array with tortuosity at each point
  • desc (str) – description string to be used when saving the file with save_as_tiff() (for proper reading into Avizo)
fibtortuosity.calculate_geodesic_distance(electrolyte_fname, phase_fname, units='nm', print_output=True)[source]

Calculate the geodesic distance of an indexed tif file.

Note

Deprecated. This function will work, but it is better to use tortuosity_from_labels_x(), tortuosity_from_labels_y(), and tortuosity_from_labels_z().

Parameters:
  • electrolyte_fname (str) – Filename of a 3D tiff file that contains only the bulk electrolyte labelfield (as 1 values)
  • phase_fname (str) – Filename of a 3D tiff file that contains the bulk electrolyte and the phase for which the geodesic distance is to be calculated
  • units (str) – units of the given dimensions
  • print_output (bool) – switch to control whether output is printed
Returns:

  • d (np.array) – Numpy array with geodesic distance from supplied surface
  • desc (str) – description string to be used when saving the file (for proper reading into Avizo)
fibtortuosity.save_results(fname=None, phase='', direction='', geo_d=None, euc_d=None, tort=None, desc=None)[source]

Saves all the results into a compressed numpy archive

Parameters:
  • geo_d (numpy array) – Geodesic distance array
  • euc_d (numpy array) – Euclidean distance array
  • tort (numpy array) – Tortuosity array
  • desc (str) – Image description string
fibtortuosity.load_results(fname)[source]

Loads the results that have been previously saved with save_results()

Parameters:fname (str) – filename to load
Returns:
  • geo_d (numpy array) – Geodesic distance array
  • euc_d (numpy array) – Euclidean distance array
  • tort (numpy array) – Tortuosity array
  • desc (str) – Image description string
fibtortuosity.run_full_analysis_lsm_ysz(electrolyte_file, electrolyte_and_pore_file, electrolyte_and_lsm_file, electrolyte_and_ysz_file, date, phase, direction, npzfile=None, units='nm', delay=0, calculate_all=False, load_from_prev_run=True, create_hspy_sigs=True, save_avizo_tiff=True, tort_profile=True, save_tort_prof=True, in_ipython=True, send_text=False, text_email=None, text_number=None, text_carrier=None)[source]

Run full tortuosity analysis for LSM/YSZ, calling other functions as necessary.

Parameters:
  • electrolyte_file (str) – Name of bulk electrolyte LabelField
  • electrolyte_and_pore_file (str) – Name of LabelField containing bulk electrolyte and pore
  • electrolyte_and_lsm_file (str) – Name of LabelField containing bulk electrolyte and LSM
  • electrolyte_and_ysz_file (str) – Name of LabelField containing bulk electrolyte and YSZ
  • date (str) – date string to be used in output filenames
  • phase (str) – phase label to be used in output filenames
  • direction (str) – direction of analysis (‘x’, ‘y’, or ‘z’)
  • npzfile (str or None) – filename of previously saved data to use (if loading from disk)
  • units (str) – units for labeling purpose
  • delay (int) – delay to wait before running analysis (useful if running more than one at a time)
  • calculate_all (bool) – flag to indicate that geodesic distance etc. should be calculated from scratch (takes a while)
  • load_from_prev_run (bool) – flag to indicate that data should be loaded from disk, using the file specified in npzfile
  • create_hspy_sigs (bool) – flag to indicate if hyperspy signals should be created (to help visualize the results)
  • save_avizo_tiff (bool) –
  • tort_profile (bool) –
  • save_tort_prof (bool) –
  • in_ipython (bool) – flag to control if notifications from ipython will be shown. Requires the “Notifyme!” extension
  • send_text (bool) – flag to control if text should be sent (requires texting and keyring packages)
  • text_email (string) – email address to send text from (see texting.TextServer)
  • text_number (string) – number to send text to (see texting.TextServer)
  • text_carrier (string) – carrier of number to send to (see texting.TextServer)
Returns:

results – results is a dictionary containing all the various parameters that were calculated during the analysis
Return type:

dict

Notes

To authenticate your email server and store the password in your local keyring, run the following before trying to send texts:

>>> import keyring
... keyring.set_password('python_TextServer', emailaddress, password)

Examples

>>> res = run_full_analysis_lsm_ysz(electrolyte_file="bulkYSZ.tif",
...                                 electrolyte_and_pore_file="bulkYSZandPRE.tif",
...                                 electrolyte_and_lsm_file="bulkYSZandLSM.tif",
...                                 electrolyte_and_ysz_file="bulkYSZandYSZ.tif",
...                                 date='2015-05-06',
...                                 phase='Pore',
...                                 direction='x',
...                                 npzfile=None,
...                                 units='nm',
...                                 delay=0,
...                                 calculate_all=True,
...                                 load_from_prev_run=False,
...                                 create_hspy_sigs=True,
...                                 save_avizo_tiff=True,
...                                 tort_profile=True,
...                                 save_tort_prof=True,
...                                 in_ipython=False,
...                                 send_text=True,
...                                 text_email="email@server.com",
...                                 text_number="8008675309",
...                                 text_carrier="verizon")
fibtortuosity.save_as_tiff(fname, data, dtype, desc)[source]

Save a numpy array as tiff (useful for transferring data back to Avizo)

Parameters:
  • fname (str) – Filename to save to
  • data (np.array) – Data array to be written to image file
  • dtype (str) – data type to save as. For some reason, euclidean distance works best as ‘uint32’, while the others are fine as ‘float32’.
  • desc (str) – Image description that includes bounding box info
fibtortuosity.tortuosity_profile(tort, euc, axis='x')[source]

Calculate the average tortuosity along an axis

Parameters:
  • tort (Numpy array (output of tortuosity_from_labels_x()...)) – Contains the tortuosity data, with 0 values in the masked areas
  • euc (Numpy array (output of tortuosity_from_labels_x()...)) – Contains the euclidean distance at each point
  • axis (str) – Axis along which to calculate profile. Should be ‘x’, ‘y’, or ‘z’
Returns:

  • tort_prof (1D Numpy array) – 1D profile of average tortuosity at each point in the array (ignoring the masked areas)
  • euc_prof (1D Numpy array) – 1D profile of the average euclidean distance at each point
fibtortuosity.plot_tort_prof(tort_prof, euc_prof, direction, units='nm', figsize=None, sns_style='white', sns_context='paper', sns_fontscale=1.5, sns_cmap=None, sns_color_num=0, sns_kw=None)[source]

Plot a profile of the average tortuosity.

Parameters:
  • tort_prof (np.array) – tortuosity profile (output of tortuosity_profile())
  • euc_prof (np.array) – euclidean profile (output of tortuosity_profile())
  • direction (str) – direction for labeling
  • units (str) – units of distance for labeling
  • figsize (tuple of integers, optional, default: None) – width, height in inches. If not provided, defaults to rc figure.figsize.
  • sns_style (str) – default style for seaborn (‘white’, ‘dark’, ‘darkgrid’, etc.)
  • sns_context (str) – context for plotting with seaborn
  • sns_fontscale (float) – font scale to pass to seaborn
  • sns_cmap (list, str, tuple) – colormap for use with seaborn default is [light blue, dark teal, blue, red, green, orange] If str or tuple, then these parameters are passed to the seaborn.color_palette() function
  • sns_color_num (int) – index of color (in sns_cmap) to use
  • sns_kw (dict) – additional arguments to be passed to seaborn.set_style (see http://goo.gl/WvLdc6 for details)
Returns:

Handle to figure that is plotted (and axes array if subplots)
Return type:

matplotlib figure, <matplotlib axes>
fibtortuosity.save_profile_to_csv(fname, x, y, direction, phase, x_name='Euc_d', y_name='tort', fmt='%10.5f', delimiter=', ')[source]

Saves two profiles (x and y) into a text file.

Parameters:
  • fname (str) – filename to save to (no checks are done before overwriting)
  • x (1D np.array) – X-profile that will be used as first column should be a one dimensional numpy row vector
  • y (np.array or list of np.arrays) – can be 1D np.array, or a list of them, with data in rows. Each row will be transformed to a column in the text files
  • direction (str) – direction for labeling
  • phase (str) – phase for labeling
  • x_name (str) – Name of header in x-column
  • y_name (str) – Name of header in y-column
  • fmt (str) – Format for decimals to use
  • delimiter (str) – Delimiter to use in the csv file
fibtortuosity.load_profile_from_csv(fname, delimiter=', ', skiprows=2)[source]

Loads columns of a text file into 1D numpy arrays.

Parameters:
  • fname (str) – filename to load from
  • delimiter (str) – character to use as delimiter
  • skiprows (int) – number of header rows to skip at beginning of file
Returns:
Return type:

list of 1D np.array objects, 1 for each column in the data
fibtortuosity._geo_dist(data, vox_x, vox_y, vox_z)[source]

Internal helper method to call scikit-fmm distance method

Parameters:
  • data (masked data array to calculate on) –
  • vox_x (x voxel size) –
  • vox_y (y voxel size) –
  • vox_z (z voxel size) –
Returns:

d
Return type:

distance transform as calculated by scikit-fmm
fibtortuosity._calc_interface(electrolyte_data)[source]

Calculates interface between bulk electrolyte and the cathode

Parameters:electrolyte_data (label data for bulk electrolyte) –
Returns:x_interface – x values of interface at each y and z locations
Return type:2D numpy array
fibtortuosity._calc_tort(geo_d, euc_d, electrolyte_data)[source]

Calculates tortuosity from geodesic and euclidean distances

Parameters:
  • geo_d (Geodesic distance (Masked Array)) –
  • euc_d (Euclidean distance (Numpy array)) –
  • electrolyte_data (label data for bulk electrolyte) –
Returns:

tort
Return type:

tortuosity numpy array
fibtortuosity._calc_euc_x(x_interface, electrolyte_data, vox_x)[source]

Calculates euclidean distance from electrolyte interface

Parameters:
  • x_interface (Numpy array containing x value of boundary for electrolyte) – for all y and z coordinates
  • electrolyte_data (label data for bulk electrolyte) –
  • vox_x (float) – voxel x-size
Returns:

euc_d
Return type:

euclidean distance numpy array