# 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)

  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)

  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)

  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)

  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)

  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)

  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=', ')

  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)

  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)

  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)

  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)

  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')

  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