PyPI: |  |
Help! |  |

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

  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)

  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)

  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)

  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)

  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)

  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)

  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)

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

  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)

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

  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)

  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)

  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)

  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)

  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)

  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