diffpy.morph package
Tools for manipulating and comparing PDF profiles
Subpackages
Submodules
diffpy.morph.pdfplot module
Collection of plotting functions for PDFs.
- diffpy.morph.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.morph.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.morph.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.morph.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.morph.morph_api module
- diffpy.morph.morph_api.morph(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 perform 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.morph.morphs.morphchain.MorphChain
The instance of processed morph chain. Calling
x_morph, y_morph, x_target, y_target = morph_chain.xyallout
will conveniently return 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.morph.morph_api import morph, morph_default_config, plot_morph
morph_cfg = morph_default_config(scale=1.01) morph_rv_dict = morph(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.morph.morph_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.morph.morph_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.morph.morphs.morphchain.MorphChain) – An instance of processed morph chain.
ax (matplotlib.axes.Axes, optional) – 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 arguments 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.morph.refine module
refine – Refine a morph or morph chain
- class diffpy.morph.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.morph.tools module
Tools used in morphs and morph chains.
- diffpy.morph.tools.case_insensitive_dictionary_search(key: str, dictionary: dict)[source]
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.morph.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.morph.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.morph.tools.estimateScale(y_morph_in, y_target_in)[source]
Set the scale that best matches the morph to the target.
- diffpy.morph.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.morph.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.morph.morph_io module
- diffpy.morph.morph_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. diffpy.morph 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. diffpy.morph will save all generated files within this directory.
- Returns:
The absolute path to the Morph subdirectory.
- Return type:
str
- diffpy.morph.morph_io.get_multisave_names(target_list: list, save_names_file=None, mm=False)[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 (or Morph if mm enabled) PDFs used for each morph.
save_names_file – Name of file to import save names dictionary from (default None).
mm (bool) – Rather than multiple targets, multiple morphs are being done.
- Returns:
The names to save each morph as. Keys are the target PDF file names used to produce that morph.
- Return type:
dict
- diffpy.morph.morph_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, mm=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.morph.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).
mm (bool) – Multiple morphs done with a single target rather than multiple targets for a single morphed file. Swaps morph and target in the code.
- diffpy.morph.morph_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 (default) 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.morph.morph_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.morph.log module
Configuration of loggers used in this package.
Logger instances:
plog – logger instance for normal operation