diffpy.utils package

Shared utilities for diffpy packages.

Subpackages

Submodules

diffpy.utils.transforms module

diffpy.utils.transforms.d_to_q(d)[source]

Helper function to convert q to d using \(d = \frac{2 \pi}{q}\).

Parameters:: d (nsarray) – The 1D array of \(d\) values np.array([ds]).
Returns:: q – The 1D array of \(q\) values np.array([qs]). The units of q must be reciprocal of the units of wavelength.
Return type:: nsarray

diffpy.utils.transforms.d_to_tth(d, wavelength)[source]

Helper function to convert d to two-theta on independent variable axis.

The formula is .. math:: 2theta = 2 arcsinleft(frac{lambda}{2d}right).

Here we convert d to q first, then to tth.

Parameters:

d (nsarray) – The 1D array of \(d\) values np.array([ds]).
wavelength (float) – The wavelength of the incoming x-rays/neutrons/electrons.

Returns:

tth – The 1D array of \(2\theta\) values np.array([tths]). The units of tth are expected in degrees.

Return type:

nsarray

diffpy.utils.transforms.q_to_d(q)[source]

Helper function to convert q to d on independent variable axis, using \(d = \frac{2 \pi}{q}\).

Parameters:: q (ndarray) – The 1D array of \(q\) values np.array([qs]). The units of q must be reciprocal of the units of wavelength.
Returns:: d – The 1D array of \(d\) values np.array([ds]).
Return type:: ndarray

diffpy.utils.transforms.q_to_tth(q, wavelength)[source]

Helper function to convert q to two-theta.

If wavelength is missing, returns x-values that are integer indexes

By definition the relationship is:

\[\sin\left(\frac{2\theta}{2}\right) = \frac{\lambda q}{4 \pi}\]

thus

\[2\theta_n = 2 \arcsin\left(\frac{\lambda q}{4 \pi}\right)\]

Parameters:

q (ndarray) – The 1D array of \(q\) values numpy.array([qs]). The units of q must be reciprocal of the units of wavelength.
wavelength (float) – Wavelength of the incoming x-rays/neutrons/electrons

Returns:

tth – The 1D array of \(2\theta\) values in degrees numpy.array([tths]).

Return type:

ndarray

diffpy.utils.transforms.tth_to_d(tth, wavelength)[source]

Helper function to convert two-theta to d on independent variable axis.

The formula is .. math:: d = frac{lambda}{2 sinleft(frac{2theta}{2}right)}.

Here we convert tth to q first, then to d.

Parameters:

tth (nsarray) – The 1D array of \(2\theta\) values np.array([tths]). The units of tth are expected in degrees.
wavelength (float) – The wavelength of the incoming x-rays/neutrons/electrons.

Returns:

d – The 1D array of \(d\) values np.array([ds]).

Return type:

nsarray

diffpy.utils.transforms.tth_to_q(tth, wavelength)[source]

Helper function to convert two-theta to q on independent variable axis.

If wavelength is missing, returns independent variable axis as integer indexes.

By definition the relationship is:

\[\sin\left(\frac{2\theta}{2}\right) = \frac{\lambda q}{4 \pi}\]

thus

\[q = \frac{4 \pi \sin\left(\frac{2\theta}{2}\right)}{\lambda}\]

Parameters:

tth (ndarray) – The 1D array of \(2\theta\) values np.array([tths]). The units of tth are expected in degrees.
wavelength (float) – The wavelength of the incoming x-rays/neutrons/electrons.

Returns:

q – The 1D array of \(q\) values np.array([qs]). The units for the q-values are the inverse of the units of the provided wavelength.

Return type:

ndarray

diffpy.utils.validators module

diffpy.utils.validators.is_number(string)[source]

Check if the provided string can be converted to a float.

Since integers can be converted to floats, this function will return True for integers as well. Hence, we can use this function to check if a string is a number.

Parameters:: string (str) – The string to evaluate for numeric conversion.
Returns:: The boolean whether string can be successfully converted to float.
Return type:: bool

Examples

>>> is_number("3.14")
True

>>> is_number("-1.23")
True

>>> is_number("007")
True

>>> is_number("five")
False

>>> is_number("3.14.15")
False

>>> is_number("NaN")
True

>>> is_number("Infinity")
True

>>> is_number("Inf")
True

diffpy.utils.tools module

diffpy.utils.tools.check_and_build_global_config(skip_config_creation=False)[source]

Check for a global diffpu config file in user’s home directory and creates one if it is missing.

The file it looks for is called diffpyconfig.json. This can contain anything in json format, but minimally contains information about the computer owner. The information is used when diffpy objects are created and saved to files or databases to retain ownership information of datasets. For example, it is used by diffpy.utils.tools.get_user_info().

If the function finds no config file in the user’s home directory it interrupts execution and prompts the user for name, email, and orcid information. It then creates the config file with this information inside it.

The function returns True if the file exists and False otherwise.

If you would like to check for a file but not run the file creation workflow you can set the optional argument skip_config_creation to True.

Parameters:: skip_config_creation (bool, optional, default is False.) – The boolean that will override the creation workflow even if no config file exists.
Returns:: config_exists – The boolean indicating whether the config file exists.
Return type:: bool

diffpy.utils.tools.compute_mu_using_xraydb(sample_composition, energy, sample_mass_density=None, packing_fraction=None)[source]

Compute the attenuation coefficient (mu) using the XrayDB database.

Computes mu based on the sample composition and energy. User should provide a sample mass density or a packing fraction. If neither density nor packing fraction is specified, or if both are specified, a ValueError will be raised. Reference: https://xraypy.github.io/XrayDB/python.html#xraydb.material_mu.

Parameters:

sample_composition (str) – The chemical formula of the material.
energy (float) – The energy of the incident x-rays in keV.
sample_mass_density (float, optional, Default is None) – The mass density of the packed powder/sample in g/cm*3.
packing_fraction (float, optional, Default is None) – The fraction of sample in the capillary (between 0 and 1). Specify either sample_mass_density or packing_fraction but not both.

Returns:

mu – The attenuation coefficient mu in mm^{-1}.

Return type:

float

diffpy.utils.tools.compute_mud(filepath)[source]

Compute the best-fit mu*D value from a z-scan file, removing the sample holder effect.

This function loads z-scan data and fits it to a model that convolves a top-hat function with I = I0 * e^{-mu * l}. The fitting procedure is run multiple times, and we return the best-fit parameters based on the lowest rmse.

The full mathematical details are described in the paper: An ad hoc Absorption Correction for Reliable Pair-Distribution Functions from Low Energy x-ray Sources, Yucong Chen, Till Schertenleib, Andrew Yang, Pascal Schouwink, Wendy L. Queen and Simon J. L. Billinge, in preparation.

Parameters:: filepath (str) – The path to the z-scan file.
Returns:: mu*D – The best-fit mu*D value.
Return type:: float

diffpy.utils.tools.get_density_from_cloud(sample_composition, mp_token='')[source]

Function to get material density from the MP or COD database.

It is not implemented yet.

diffpy.utils.tools.get_package_info(package_names, metadata=None)[source]

Fetch package version and updates it into (given) metadata.

Package info stored in metadata as {‘package_info’: {‘package_name’: ‘version_number’}}.

metadatadict: The dictionary to store the package info. If not provided, a new dictionary will be created.

Returns:: metadata – The updated metadata dict with package info inserted.
Return type:: dict

diffpy.utils.tools.get_user_info(owner_name=None, owner_email=None, owner_orcid=None)[source]

Get name, email, and orcid of the owner/user from various sources and return it as a metadata dictionary.

The function looks for the information in json format configuration files with the name ‘diffpyconfig.json’. These can be in the user’s home directory and in the current working directory. The information in the config files are combined, with the local config overriding the home-directory one. Values for owner_name, owner_email, and owner_orcid may be passed in to the function and these override the values in the config files.

A template for the config file is below. Create a text file called ‘diffpyconfig.json’ in your home directory and copy-paste the template into it, editing it with your real information. {

“owner_name”: “<your name as you would like it stored with your data>>”, “owner_email”: “<your_associated_email>>@email.com”, “owner_orcid”: “<your_associated_orcid if you would like this stored with your data>>”

} You may also store any other global-level information that you would like associated with your diffraction data in this file

Parameters:

owner_name (str, optional, default is the value stored in the global or local config file.) – The name of the user who will show as owner in the metadata that is stored with the data
owner_email (str, optional, default is the value stored in the global or local config file.) – The email of the user/owner
owner_orcid (str, optional, default is the value stored in the global or local config file.) – The ORCID id of the user/owner

Returns:

user_info – The dictionary containing username, email and orcid of the user/owner, and any other information stored in the global or local config files.

Return type:

dict

diffpy.utils.user_config module

diffpy.utils.diffraction_objects module

class diffpy.utils.diffraction_objects.DiffractionObject(xarray, yarray, xtype, wavelength=None, scat_quantity='', name='', metadata={})[source]

Bases: object

Class for storing and manipulating diffraction data.

DiffractionObject stores data produced from X-ray, neutron, and electron scattering experiments. The object can transform between different scattering quantities such as q (scattering vector), 2θ (two-theta angle), and d (interplanar spacing), and perform various operations like scaling, addition, subtraction, and comparison for equality between diffraction objects.

scat_quantity

The type of scattering experiment (e.g., “x-ray”, “neutron”). Default is an empty string “”.

Type:: str

wavelength

The wavelength of the incoming beam, specified in angstroms (Å). Default is none.

Type:: float

name

The name or label for the scattering data. Default is an empty string “”.

Type:: str

qmin

The minimum q value.

Type:: float

qmax

The maximum q value.

Type:: float

tthmin

The minimum two-theta value.

Type:: float

tthmax

The maximum two-theta value.

Type:: float

dmin

The minimum d-spacing value.

Type:: float

dmax

The maximum d-spacing value.

Type:: float

property all_arrays

The 2D array containing xarray and yarray values.

Returns:: The shape (len(data), 4) 2D array with columns containing the yarray (intensity) and the xarray values in q, tth, and d.
Return type:: ndarray

Examples

To access specific arrays individually, use these slices:

>>> my_do.all_arrays[:, 0]  # yarray
>>> my_do.all_arrays[:, 1]  # xarray in q
>>> my_do.all_arrays[:, 2]  # xarray in tth
>>> my_do.all_arrays[:, 3]  # xarray in d

copy()[source]

Create a deep copy of the DiffractionObject instance.

Returns:: The new instance of DiffractionObject, which is a deep copy of the current instance.
Return type:: DiffractionObject

dump(filepath, xtype=None)[source]

Dump the xarray and yarray of the diffraction object to a two-column file, with the associated information included in the header.

Parameters:

filepath (str) – The filepath where the diffraction object will be dumped
xtype (str, optional, default is q) – The type of quantity for the independent variable chosen from {*XQUANTITIES, }

Examples

To save a diffraction object to a file named “diffraction_data.chi” in the current directory with the independent variable ‘q’:

>>> file = "diffraction_data.chi"
>>> do.dump(file, xtype="q")

To save the diffraction data to a file in a subfolder output:

>>> file = "./output/diffraction_data.chi"
>>> do.dump(file, xtype="q")

To save the diffraction data with a different independent variable, such as ‘tth’:

>>> file = "diffraction_data_tth.chi"
>>> do.dump(file, xtype="tth")

get_array_index(xtype, xvalue)[source]

Return the index of the closest value in the array associated with the specified xtype and the value provided.

Parameters:

xtype (str) – The type of the independent variable in xarray. Must be one of {*XQUANTITIES}.
xvalue (float) – The value of the xtype to find the closest index for.

Returns:

index – The index of the closest value in the array associated with the specified xtype and the value provided.

Return type:

int

property input_xtype

The type of the independent variable in xarray.

Returns:: input_xtype – The type of xarray, which must be one of {*XQUANTITIES}.
Return type:: str

on_d()[source]

Return the tuple of two 1D numpy arrays containing d and y data.

Returns:: (d-array, y-array) – The tuple containing two 1D numpy arrays with d and y data
Return type:: tuple of ndarray

on_q()[source]

Return the tuple of two 1D numpy arrays containing q and y data.

Returns:: (q-array, y-array) – The tuple containing two 1D numpy arrays with q and y data
Return type:: tuple of ndarray

on_tth()[source]

Return the tuple of two 1D numpy arrays containing tth and y data.

Returns:: (tth-array, y-array) – The tuple containing two 1D numpy arrays with tth and y data
Return type:: tuple of ndarray

on_xtype(xtype)[source]

Return a tuple of two 1D numpy arrays containing x and y data.

Parameters:: xtype (str) – The type of quantity for the independent variable chosen from {*XQUANTITIES, }
Raises:: ValueError – Raised when the specified xtype is not among {*XQUANTITIES, }
Returns:: (xarray, yarray) – The tuple containing two 1D numpy arrays with x and y data for the specified xtype.
Return type:: tuple of ndarray

scale_to(target_diff_object, q=None, tth=None, d=None, offset=None)[source]

Return a new diffraction object which is the current object but rescaled in y to the target.

By default, if q, tth, or d are not provided, scaling is based on the max intensity from each object. Otherwise, y-value in the target at the closest specified x-value will be used as the factor to scale to. The entire array is scaled by this factor so that one object places on top of the other at that point. If multiple values of q, tth, or d are provided, an error will be raised.

Parameters:

target_diff_object (DiffractionObject) – The diffraction object you want to scale the current one onto.
q (float, optional, default is None) – The value of the x-array where you want the curves to line up vertically. Specify a value on one of the allowed grids, q, tth, or d), e.g., q=10.
tth (float, optional, default is None) – The value of the x-array where you want the curves to line up vertically. Specify a value on one of the allowed grids, q, tth, or d), e.g., q=10.
d (float, optional, default is None) – The value of the x-array where you want the curves to line up vertically. Specify a value on one of the allowed grids, q, tth, or d), e.g., q=10.
offset (float, optional, default is None) – The offset to add to the scaled y-values.

Returns:

scaled_do – The rescaled DiffractionObject as a new object.

Return type:

DiffractionObject

property uuid

The unique identifier for the DiffractionObject instance.

Returns:: uuid – The unique identifier of the DiffractionObject instance.
Return type:: UUID

diffpy.utils.resampler module

Various utilities related to data parsing and manipulation.

diffpy.utils.resampler.nsinterp(xp, fp, qmin=0, qmax=25, left=None, right=None)[source]

One-dimensional Whittaker-Shannon interpolation onto the Nyquist-Shannon grid.

Takes a band-limited function fp and original grid xp and resamples fp on the NS grid. Uses the minimum number of points N required by the Nyquist sampling theorem. N = (qmax-qmin)(rmax-rmin)/pi, where rmin and rmax are the ends of the real-space ranges. fp must be finite, and the user inputs qmin and qmax of the frequency-domain.

Parameters:

xp (ndarray) – The array of known x values.
fp (ndarray) – The array of y values associated with xp.
qmin (float) – The lower band limit in the frequency domain.
qmax (float) – The upper band limit in the frequency domain.

Returns:

x (ndarray) – The Nyquist-Shannon grid computed for the given qmin and qmax.
fp_at_x (ndarray) – The interpolated values at points x. Returns a single float if x is a scalar, otherwise returns a numpy.ndarray.

diffpy.utils.resampler.resample(r, s, dr)[source]

Resample a PDF on a new grid.

This uses the Whittaker-Shannon interpolation formula to put s1 on a new grid if dr is less than the sampling interval of r1, or linear interpolation if dr is greater than the sampling interval of r1.

Parameters:

r – The r-grid used for s1.
s – The signal to be resampled.
dr – The new sampling interval.

Return type:

Returns resampled (r, s).

diffpy.utils.resampler.wsinterp(x, xp, fp, left=None, right=None)[source]

One-dimensional Whittaker-Shannon interpolation.

Reconstruct a continuous signal from discrete data points by utilizing sinc functions as interpolation kernels. This function interpolates the values of fp (array), which are defined over xp (array), at new points x (array or float). The implementation is based on E. T. Whittaker’s 1915 paper (https://doi.org/10.1017/S0370164600017806).

Parameters:

x (ndarray) – The x values at which interpolation is computed.
xp (ndarray) – The array of known x values.
fp (ndarray) – The array of y values associated with xp.
left (float) – If given, set fp for x < xp[0] to left. Otherwise, if left is None (default) or not given, set fp for x < xp[0] to fp evaluated at xp[-1].
right (float) – If given, set fp for x > xp[-1] to right. Otherwise, if right is None (default) or not given, set fp for x > xp[-1] to fp evaluated at xp[-1].

Returns:

The interpolated values at points x. Returns a single float if x is a scalar, otherwise returns a numpy.ndarray.

Return type:

ndarray or float