diffpy.pdfmorph package

Tools for manipulating and comparing PDF profiles

Subpackages

Submodules

diffpy.pdfmorph.pdfplot module

Collection of plotting functions for PDFs.

diffpy.pdfmorph.pdfplot.comparePDFs(pairlist, labels=None, rmin=None, rmax=None, show=True, maglim=None, mag=5, rw=None, legend=True, l_width=1.5)[source]

Plot two PDFs on top of each other and difference curve.

The second PDF will be shown as blue circles below and the first as a red line. The difference curve will be in green and offset for clarity.

Parameters:

  • pairlist – Iterable of (r, gr) pairs to plot

  • labels – Iterable of names for the pairs. If this is not the same length as the pairlist, a legend will not be shown (default []).

  • rmin – The minimum r-value to plot. If this is None (default), the lower bound of the PDF is not altered.

  • rmax – The maximum r-value to plot. If this is None (default), the upper bound of the PDF is not altered.

  • show – Show the plot (default True)

  • maglim – Point after which to magnify the signal by mag. If None (default), no magnification will take place.

  • mag – Magnification factor (default 5)

  • rw – Rw value to display on the plot, if any.

  • legend – Display the legend (default True).

diffpy.pdfmorph.pdfplot.plotPDFs(pairlist, labels=None, offset='auto', rmin=None, rmax=None)[source]

Plots several PDFs on top of one another.

Parameters:

  • pairlist – Iterable of (r, gr) pairs to plot.

  • labels – Iterable of names for the pairs. If this is not the same length as the pairlist, a legend will not be shown (default []).

  • offset – Offset to place between plots. PDFs will be sequentially shifted in the y-direction by the offset. If offset is ‘auto’ (default), the optimal offset will be determined automatically.

  • rmin – The minimum r-value to plot. If this is None (default), the lower bound of the PDF is not altered.

  • rmax – The maximum r-value to plot. If this is None (default), the upper bound of the PDF is not altered.

diffpy.pdfmorph.pdfplot.plot_param(target_labels, param_list, param_name=None, field=None)[source]

Plot Rw values for multiple morphs.

Parameters:

  • target_labels (list) – Names (or field if –sort-by given) of each file acting as target for the morph.

  • param_list (list) – Contains the values of some parameter corresponding to each file.

  • param_name (str) – Name of the parameter.

  • field (list or None) – When not None and entries in field are numerical, a line chart of Rw versus field is made. When None (default) or values are non-numerical, it plots a bar chart of Rw values per file.

diffpy.pdfmorph.pdfplot.truncatePDFs(r, gr, rmin=None, rmax=None)[source]

Truncate a PDF to specified bounds.

Parameters:

  • r – r-values of the PDF.

  • gr – PDF g(r) values.

  • rmin – The minimum r-value. If this is None (default), the lower bound of the PDF is not altered.

  • rmax – The maximum r-value. If this is None (default), the upper bound of the PDF is not altered.

Returns:

Returns the truncated r, gr.

Return type:

r, gr

diffpy.pdfmorph.pdfmorph_api module

diffpy.pdfmorph.pdfmorph_api.morph_default_config(**kwargs)[source]

function to generate default morph configuration

Parameters:

kwargs – extra keyword arguments passed to the default morph config

Returns:

morph_default_config – A dictionary of morph configuration

Return type:

dict

Examples

morph_cfg = morph_default_config(scale=1.01)

diffpy.pdfmorph.pdfmorph_api.pdfmorph(x_morph, y_morph, x_target, y_target, rmin=None, rmax=None, rstep=None, pearson=False, add_pearson=False, fixed_operations=None, refine=True, verbose=False, **kwargs)[source]

function to perfom PDF morphing.

Parameters:

  • x_morph (numpy.array) – An array of morphed x values, i.e., those will be manipulated by morphing.

  • y_morph (numpy.array) – An array of morphed y values, i.e., those will be manipulated by morphing.

  • x_target (numpy.array) – An array of target x values, i.e., those will be kept constant by morphing.

  • y_morph – An array of target y values, i.e., those will be kept constant by morphing.

  • rmin (float, optional) – A value to specify lower r-limit of morph operations.

  • rmax (float, optional) – A value to specify upper r-limit of morph operations.

  • rstep (float, optional) – A value to specify rstep of morph operations.

  • pearson (Bool, optional) –

    Option to include Pearson coefficient as a minimizing target

    during morphing. Default to False.

  • add_pearson (Bool, optional) – Option to include both Pearson coefficient and Rw as minimizing targets during morphing. Default to False.

  • fixed_operations (list, optional) – A list of string specifying operations will be keep fixed during morphing. Default is None.

  • refine (bool, optional) – Option to execute the minimization step in morphing. If False, the morphing will be applied with parameter values specified in morph_config. Default to True.

  • verbose (bool, optional) – Option to print full result after morph. Default to False.

  • kwargs (dict, optional) –

    A dictionary with morph parameters as keys and initial values of morph parameters as values. Currently supported morph parparameters are:

    • ’scale’

    • ’stretch’

    • ’smear’

    • ’baselineslope’

    • ’qdamp’

Returns:

morph_rv_dict – A dictionary contains following key-value pairs:

  • morph_chain: diffpy.pdfmorph.morphs.morphchain.MorphChain

    The instance of processed morph chain. Calling x_morph, y_morph, x_target, y_target = morph_chain.xyallout will conviniently retrun morphed data and reference data

  • morphed_cfg: dict

    A dictionary of refined morphing parameters

  • rw: float

    The agreement factor between morphed data and reference data

  • pcc: float
    The pearson correlation coefficient between morphed

    data and referenced data

Return type:

dict

Examples

# morphing (x_morph, y_morph) pair to (x_target, y_target) pair with scaling from diffpy.pdfmorph.pdfmorph_api import pdfmorph, morph_default_config, plot_morph

morph_cfg = morph_default_config(scale=1.01) morph_rv_dict = pdfmorph(x_morph, y_morph, x_target, y_target, **morph_cfg)

# plot morhing result plot_morph(morph_rv_dict[‘morph_chain’])

# print morphing parameters, pearson correlation coefficient, Rw print(morph_rv_dict[‘morphed_cfg’]) print(morph_rv_dict[‘pcc’]) print(morph_rv_dict[‘rw’])

diffpy.pdfmorph.pdfmorph_api.plot_morph(chain, ax=None, **kwargs)[source]

Plot the morphed PDF and the target PDF of a morphing operation.

Open a new figure unless a specific axis is provided for plotting.

Parameters:

  • chain (diffpy.pdfmorph.morphs.morphchain.MorphChain) – An instance of processed morph chain.

  • ax (matplotlib.axes.Axes, optinal) – An instance of Axes class to plot the morphing result. If ax is None, instances of new Figure and Axes will be created. Default to None.

  • kwargs – Additional keyword arguements will be passed to ax.plot(...**kwargs)

Returns:

l_list – A list of matplotlib.lines.Line2D objects representing the plotted data.

Return type:

list

diffpy.pdfmorph.refine module

refine – Refine a morph or morph chain

class diffpy.pdfmorph.refine.Refiner(chain, x_morph, y_morph, x_target, y_target)[source]

Bases: object

Class for refining a Morph or MorphChain.

This is provided to allow for custom residuals and refinement algorithms.

chain

The Morph or MorphChain to refine.

x_morph, y_morph

Morphed arrays.

x_target, y_target

Target arrays.

pars

List of names of parameters to be refined.

residual

The residual function to optimize. Default _residual. Can be assigned to other functions.

refine(*args, **kw)[source]

Refine the chain.

Additional arguments are used to specify which parameters are to be refined. If no arguments are passed, then all parameters will be refined. Keywords pass initial values to the parameters, whether or not they are refined.

This uses the leastsq algorithm from scipy.optimize.

This returns the final scalar residual value. The parameters from the fit can be retrieved from the config dictionary of the morph or morph chain.

Raises:

ValueError – Exception raised if a minimum cannot be found.

diffpy.pdfmorph.tools module

Tools used in morphs and morph chains.

Search for key in dictionary ignoring case.

Parameters:

  • key (str)

  • dictionary (dict)

Returns:

Corresponding value if key is in dictionary. None otherwise.

Return type:

value or None

diffpy.pdfmorph.tools.deserialize(serial_file)[source]

Call deserialize_data from diffpy.utils.

Parameters:

serial_file – Name of file to deserialize.

Returns:

Data read from serial file.

Return type:

dict

diffpy.pdfmorph.tools.estimateBaselineSlope(r, gr, rmin=None, rmax=None)[source]

Estimate the slope of the linear baseline of a PDF.

This fits a slope into the equation slope*r through the bottom of the PDF.

Parameters:

  • r – The r-grid used for the PDF.

  • gr – The PDF over the r-grid.

  • rmin – The minimum r-value to consider. If this is None (default) is None, then the minimum of r is used.

  • rmax – The maximum r-value to consider. If this is None (default) is None, then the maximum of r is used.

Returns:

slope – The slope of baseline. If the PDF is scaled properly, this is equal to -4*pi*rho0.

Return type:

float

diffpy.pdfmorph.tools.estimateScale(y_morph_in, y_target_in)[source]

Set the scale that best matches the morph to the target.

diffpy.pdfmorph.tools.field_sort(filepaths: list, field, reverse=False, serfile=None, get_field_values=False)[source]

Sort a list of files by a field stored in header information. All files must contain this header information.

Parameters:

  • filepaths – List of paths to files that we want to sort.

  • field – The field we want to sort by. Not case-sensitive.

  • reverse – Sort in reverse alphabetical/numerical order.

  • serfile – Path to a serial file with field information for each file.

  • get_field_values (bool) – Boolean indicating whether to also return a List of field values (default False). This List of field values is parallel to the sorted list of filepaths with items in the same position corresponding to each other.

Returns:

Sorted list of paths. When get_fv is true, also return an associated field list.

Return type:

list

diffpy.pdfmorph.tools.getRw(chain)[source]

Get Rw from the outputs of a morph or chain.

diffpy.pdfmorph.tools.get_pearson(chain)[source]
diffpy.pdfmorph.tools.get_values_from_dictionary_collection(dictionary_collection: iter, target_key)[source]

In an (iterable) collection of dictionaries, search for a target key in each dictionary. Return a list of all found values corresponding to that key.

Parameters:

  • dictionary_collection (iter) – The collection of dictionaries to search through.

  • target_key – The key to search for in each dictionary. For each dictionary in dictionary_collection that has that key, the corresponding value is appended to a List called values.

Returns:

The found values.

Return type:

list

diffpy.pdfmorph.tools.nn_value(val, name)[source]

Convenience function for ensuring certain non-negative inputs.

diffpy.pdfmorph.tools.readPDF(fname)[source]

Reads an .gr file, loads r and G(r) vectors.

Parameters:

fname – Name of the file we want to read.

Returns:

Arrays read from data.

Return type:

r,gr

diffpy.pdfmorph.pdfmorph_io module

diffpy.pdfmorph.pdfmorph_io.create_morphs_directory(save_directory)[source]

Create a directory for saving multiple morphed PDFs.

Takes in a user-given path to a directory save_directory and create a subdirectory named Morphs. PDFmorph will save all morphs into the Morphs subdirectory while metadata about the morphs will be stored in save_directory outside Morphs.

Parameters:

save_directory – Path to a directory. PDFmorph will save all generated files within this directory.

Returns:

The absolute path to the Morph subdirectory.

Return type:

str

diffpy.pdfmorph.pdfmorph_io.get_multisave_names(target_list: list, save_names_file=None)[source]

Create or import a dictionary that specifies names to save morphs as. First attempt to import names from a specified file. If names for certain morphs not found, use default naming scheme: ‘Morph_with_Target_<target file name>.cgr’.

Used when saving multiple morphs.

Parameters:

  • target_list (list) – Target PDFs used for each morph.

  • save_names_file – Name of file to import save names dictionary from (default None).

Returns:

The names to save each morph as. Keys are the target PDF file names used to produce that morph.

Return type:

dict

diffpy.pdfmorph.pdfmorph_io.multiple_morph_output(morph_inputs, morph_results, target_files, field=None, field_list=None, save_directory=None, morph_file=None, target_directory=None, verbose=False, stdout_flag=False)[source]

Helper function for printing details about a series of multiple morphs. Handles both printing to terminal and printing to a file.

Parameters:

  • morph_inputs (dict) – Input parameters given by the user.

  • morph_results (dict) – Resulting data after morphing.

  • target_files (list) – PDF files that acted as targets to morphs.

  • save_directory – Name of directory to save morphs in.

  • field – Name of field if data was sorted by a particular field. Otherwise, leave blank.

  • field_list (list) – List of field values for each target PDF. Generated by diffpy.pdfmorph.tools.field_sort().

  • morph_file – Name of the morphed PDF file. Required to give summary data after saving to a directory.

  • target_directory – Name of the directory containing the target PDF files. Required to give summary data after saving to a directory.

  • verbose (bool) – Print additional summary details when True (default False).

  • stdout_flag (bool) – Print to terminal when True (default False).

diffpy.pdfmorph.pdfmorph_io.single_morph_output(morph_inputs, morph_results, save_file=None, morph_file=None, xy_out=None, verbose=False, stdout_flag=False)[source]

Helper function for printing details about a single morph. Handles both printing to terminal and printing to a file.

Parameters:

  • morph_inputs (dict) – Parameters given by the user.

  • morph_results (dict) – Resulting data after morphing.

  • save_file – Name of file to print to. If None (defualt) print to terminal.

  • morph_file – Name of the morphed PDF file. Required when printing to a non-terminal file.

  • xy_out (param) –

    List of the form [x_morph_out, y_morph_out]. x_morph_out is a List of r values and

    y_morph_out is a List of gr values.

  • verbose (bool) – Print additional details about the morph when True (default False).

  • stdout_flag (bool) – Print to terminal when True (default False).

diffpy.pdfmorph.pdfmorph_io.tabulate_results(multiple_morph_results)[source]

Helper function to make a data table summarizing details about the results of multiple morphs.

Parameters:

multiple_morph_results – A collection of Dictionaries. Each Dictionary summarizes the resultsof a single morph.

Returns:

tabulated_results – Keys in tabulated_results are the table’s column names and each corresponding value is a list of data for that column.

Return type:

dict

diffpy.pdfmorph.log module

Configuration of loggers used in this package.

Logger instances:

plog – logger instance for normal operation

diffpy.pdfmorph.log.set_verbosity(vb)[source]

Set verbosity of the pdfmorph logger.

Parameters:

vb – Integer or one of (‘debug’, ‘info’, ‘warning’, ‘error’) strings.

Return type:

No return value.

diffpy.pdfmorph.pdfmorphapp module

diffpy.pdfmorph.pdfmorphapp.create_option_parser()[source]
diffpy.pdfmorph.pdfmorphapp.getPDFFromFile(fn)[source]
diffpy.pdfmorph.pdfmorphapp.main()[source]
diffpy.pdfmorph.pdfmorphapp.multiple_morphs(parser, opts, pargs, stdout_flag=True)[source]
diffpy.pdfmorph.pdfmorphapp.single_morph(parser, opts, pargs, stdout_flag=True)[source]