Introduction

This module is used to calculate the geometric tortuosity of a three-dimensional structure, based on J. Taillon’s 2016 paper. Useful for FIB/SEM reconstructions of SOFCs, but probably useful in other situations as well.

The expected inputs are binary (0 and 1) or ternary (0, 1, or 2) 3D tif files representing the phases to calculate. Because the module is focused on SOFC calculations primarily, it is expected that 1 index represents the bulk electrolyte phase. If present, the 2 index is the phase for which to calculate the tortuosity. The 0 index are the areas that cannot be traversed (i.e. the hard boundaries that create the tortuosity).

Installation

>>> s.set_signal_type("EELS")

General Instructions (for SOFCs)

  1. Using Avizo (or some other software),

Module API Documentation

fibtortuosity.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.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.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.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.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.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.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.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.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 .npy 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 (for proper reading into Avizo)

fibtortuosity.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 .npy 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 (for proper reading into Avizo)

fibtortuosity.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 .npy 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 (for proper reading into Avizo)

fibtortuosity.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