Utilities

Overview of utilities offered by diffpy.utils. Check the examples provided for how to use these.

Parsers Utility

The diffpy.utils.parsers module allows users to easily and robustly load file data into a Python project.

  • loaddata.loadData(): Find and load a data table/block from a text file. This seems to work for most datafiles including those generated by diffpy programs. Running only numpy.loadtxt will result in errors for most these files as there is often excess data or parameters stored above the data block. Users can instead choose to load all the parameters of the form <param_name> = <param_value> into a dictionary with this function by setting the header parameter to True.

    The program identifies data blocks as the first matrix block with a constant number of columns. A user can tune the minimum number of rows this matrix block must have.

  • serialization.deserialize_data(): Load data from a serial file format into a Python dictionary. Currently, the only supported serial format is .json.

  • serialization.serialize_data(): Serialize the data generated by loadData() into a serial file format. Currently, the only supported serial format is .json.

For a more in-depth tutorial for how to use these parser utilities, click here.

Resample Utility

  • wsinterp(): Allows users easily resample a PDF onto another grid. This makes use of the Whittaker-Shannon interpolation formula. To see the theory behind how this interpolation works and how to use it in practice, click here.

Tools Utility

The diffpy.utils.tools module provides tool functions for use with diffpy apps.

  • get_user_info(): This function is designed for managing and tracking user information (name, email, orcid). Developers can use this function to simplify the process of loading, merging, and saving information consistently and easily. Additionally, it saves the effort of re-entering information, and allows overriding current information by passing parameters.

  • check_and_build_global_config(): This function helps create a global configuration file that can be used by, for example, get_user_info(). If no existing configuration file is found, this function prompts for information. The provided inputs are then saved to a global configuration file. This file can be reused later by get_user_info() to ensure that the work credits and user information are consistently stored.

  • get_package_info(): This function loads package name and version information into a dictionary. It updates the package information under the key “package_info” in the format {“package_name”: “version_number”}, resulting in an entry in the passed metadata dictionary that looks like {"package_info": {"package1": "version_number1", "package2": "version_number2"} if the function is called more than once.

    Users can use these functions to track and manage versions of packages that can later be stored, for example, in an output file header.

For a more in-depth tutorial for how to use these tools, click here.

Transforms Utility

The diffpy.utils.transforms module provides a set of functions for managing and analyzing diffraction data, including angle-space transformations between q, 2theta, and d-spacing.

These functions allow developers to standardize diffraction data and convert it between different spacings, simplifying analysis, visualization, and processing. They are also internally used by the DiffractionObject class for efficient data manipulation. For more information about this, click here.

For a more in-depth tutorial for how to use these functions, click here.

Diffraction Objects Utility

The diffpy.utils.diffraction_objects module provides a set of powerful functions for analyzing diffraction data.

  • DiffractionObject(): This function creates a diffraction object that stores your diffraction data and associated information. If a wavelength is specified, it can automatically populate data across different independent axes (e.g., q, tth, and d).

  • on_xtype(): This function allows developers to access diffraction data on different independent axes (q, tth, and d). It is useful when you need to convert or view the data between axes, working with the axis that best fits your analysis.

  • get_array_index(): This function finds the closest index in the independent variable axis (xarray) to a targeted value. It simplifies the process of working with different spacing.

  • scale_to(): This function rescales one diffraction object to align with another at a specific value. This is helpful for comparing diffraction data with different intensity values or lengths, ensuring they are directly comparable and visually aligned.

  • copy(): This function creates a deep copy of a diffraction object, allowing you to preserve the original data while making modifications to a separate copy.

  • dump(): This function saves both diffraction data and all associated information to a file. It also automatically tracks the analysis time and software version you used.

For a more in-depth tutorial for how to use these tools, click here.