io

Modules:

Name	Description
ascii	Helpers for loading numeric data from ASCII files.
cif
results_sidecar	Bayesian fit sidecar read/write helpers.

Functions

Modules

ascii

Helpers for loading numeric data from ASCII files.

Functions:

Name	Description
extract_project_from_zip	Extract a project directory from a ZIP archive.
extract_data_paths_from_zip	Extract all files from a ZIP archive and return their paths.
extract_data_paths_from_dir	List data files in a directory and return their sorted paths.
extract_metadata	Extract a single numeric value from a file using a regex pattern.
load_numeric_block	Load a numeric block from an ASCII file, skipping non-numeric lines.

Functions

extract_project_from_zip(zip_path, destination=None)

Extract a project directory from a ZIP archive.

The archive must contain exactly one directory with a project.cif file. Files are extracted into destination when provided, or into a temporary directory that persists for the lifetime of the process.

Parameters:

Name	Type	Description	Default
zip_path	str | Path	Path to the ZIP archive containing the project.	required
destination	str | Path | None	Directory to extract into. When None, a temporary directory is created. Relative destinations are resolved against the configured artifact root when EASYDIFFRACTION_ARTIFACT_ROOT is set.	None

Returns:

Type	Description
str	Absolute path to the extracted project directory (the directory that contains project.cif).

Raises:

Type	Description
FileNotFoundError	If zip_path does not exist.
ValueError	If the archive does not contain a project.cif file.

extract_data_paths_from_zip(zip_path, destination=None)

Extract all files from a ZIP archive and return their paths.

Files are extracted into destination when provided, or into a temporary directory that persists for the lifetime of the process. The returned paths are sorted lexicographically by file name so that numbered data files (e.g. scan_001.dat, scan_002.dat) appear in natural order. Hidden files and directories (names starting with '.' or '__') are excluded.

Parameters:

Name	Type	Description	Default
zip_path	str | Path	Path to the ZIP archive.	required
destination	str | Path | None	Directory to extract files into. When None, a temporary directory is created. Relative destinations are resolved against the current working directory, or against the configured artifact root when EASYDIFFRACTION_ARTIFACT_ROOT is set.	None

Returns:

Type	Description
list[str]	Sorted absolute paths to the extracted data files.

Raises:

Type	Description
FileNotFoundError	If zip_path does not exist.
ValueError	If the archive contains no usable data files.

extract_data_paths_from_dir(dir_path, file_pattern='*')

List data files in a directory and return their sorted paths.

Hidden files (names starting with '.' or '__') are excluded. The returned paths are sorted lexicographically by file name.

Parameters:

Name	Type	Description	Default
dir_path	str | Path	Path to the directory containing data files.	required
file_pattern	str	Glob pattern to filter files (e.g. '*.dat', '*.xye').	'*'

Returns:

Type	Description
list[str]	Sorted absolute paths to the matching data files.

Raises:

Type	Description
FileNotFoundError	If dir_path does not exist or is not a directory.
ValueError	If no matching data files are found.

extract_metadata(file_path, pattern)

Extract a single numeric value from a file using a regex pattern.

The entire file content is searched (not just the header). The first match is used. The regex must contain exactly one capture group whose match is convertible to float.

Parameters:

Name	Type	Description	Default
file_path	str | Path	Path to the input file.	required
pattern	str	Regex with one capture group that matches the numeric value.	required

Returns:

Type	Description
float | None	The extracted value, or None if the pattern did not match or the captured text could not be converted to float.

load_numeric_block(data_path)

Load a numeric block from an ASCII file, skipping non-numeric lines.

Each line is tested individually: lines whose whitespace-separated tokens are all valid floats are kept; everything else (headers, footers, comment lines) is silently discarded.

Parameters:

Name	Type	Description	Default
data_path	str | Path	Path to the ASCII data file.	required

Returns:

Type	Description
np.ndarray	2-D array of the parsed numeric data.

Raises:

Type	Description
OSError	If no numeric lines can be found in the file.

cif

Modules:

Name	Description
handler	Minimal CIF tag handler used by descriptors/parameters.
iucr_transformers	IUCr category transformers for structurally reshaped CIF output.
iucr_writer	IUCr journal-submission CIF writer.
parse
serialize

Modules

handler

Minimal CIF tag handler used by descriptors/parameters.

Classes:

Name	Description
CifHandler	Canonical CIF handler used by descriptors/parameters.

Classes

CifHandler(*, names, iucr_name=None)

Canonical CIF handler used by descriptors/parameters.

Holds CIF tags (names) and attaches to an owning descriptor so it can derive a stable uid if needed.

Methods:

Name	Description
attach	Attach to a descriptor or parameter instance.

Attributes:

Name	Type	Description
names	list[str]	List of CIF tag names associated with the owner.
iucr_name	str	IUCr-side CIF tag name for export writers.
uid	str | None	Unique identifier taken from the owner, if attached.

Attributes

names property

List of CIF tag names associated with the owner.

iucr_name property

IUCr-side CIF tag name for export writers.

uid property

Unique identifier taken from the owner, if attached.

Functions

attach(owner)

Attach to a descriptor or parameter instance.

iucr_transformers

IUCr category transformers for structurally reshaped CIF output.

Classes:

Name	Description
IucrItem	Single transformed IUCr item.
IucrLoop	Transformed IUCr loop.
IucrCategoryTransformer	Base class for registered IUCr category transformers.
WavelengthTransformer	Transform wavelength parameters into IUCr wavelength rows.
TofCalibrationTransformer	Transform TOF calibration scalars into pdCIF calibration rows.
ExcludedRegionsTransformer	Transform excluded x ranges into pdCIF free text.
SymmetryOperationsTransformer	Transform a space group into explicit symmetry operation rows.
ExtinctionTransformer	Transform project extinction metadata into coreCIF fields.

Classes

IucrItem(tag, value) dataclass

Single transformed IUCr item.

IucrLoop(tags, rows) dataclass

Transformed IUCr loop.

IucrCategoryTransformer

Base class for registered IUCr category transformers.

Methods:

Name	Description
register	Register an IUCr category transformer class.
create	Create a registered transformer by tag.

Functions

register(transformer_cls) classmethod

Register an IUCr category transformer class.

Parameters:

Name	Type	Description	Default
transformer_cls	type[IucrCategoryTransformer]	Transformer subclass to register.	required

Returns:

Type	Description
type[IucrCategoryTransformer]	The registered class, unchanged.

create(tag) classmethod

Create a registered transformer by tag.

Parameters:

Name	Type	Description	Default
tag	str	Registered transformer tag.	required

Returns:

Type	Description
IucrCategoryTransformer	Transformer instance.

WavelengthTransformer

Transform wavelength parameters into IUCr wavelength rows.

Methods:

Name	Description
items	Return wavelength items for a monochromatic experiment.
loop	Return a wavelength loop for multi-wavelength experiments.
register	Register an IUCr category transformer class.
create	Create a registered transformer by tag.

Functions

items(experiment) staticmethod

Return wavelength items for a monochromatic experiment.

Parameters:

Name	Type	Description	Default
experiment	object	Experiment whose instrument may expose setup_wavelength.	required

Returns:

Type	Description
tuple[IucrItem, ...] | None	Wavelength items, or None when no wavelength exists.

loop(experiment) staticmethod

Return a wavelength loop for multi-wavelength experiments.

Parameters:

Name	Type	Description	Default
experiment	object	Experiment whose instrument may expose multiple wavelengths.	required

Returns:

Type	Description
IucrLoop | None	Wavelength loop, or None for monochromatic experiments.

register(transformer_cls) classmethod

Register an IUCr category transformer class.

Parameters:

Name	Type	Description	Default
transformer_cls	type[IucrCategoryTransformer]	Transformer subclass to register.	required

Returns:

Type	Description
type[IucrCategoryTransformer]	The registered class, unchanged.

create(tag) classmethod

Create a registered transformer by tag.

Parameters:

Name	Type	Description	Default
tag	str	Registered transformer tag.	required

Returns:

Type	Description
IucrCategoryTransformer	Transformer instance.

TofCalibrationTransformer

Transform TOF calibration scalars into pdCIF calibration rows.

Methods:

Name	Description
loop	Return a d-to-TOF calibration loop.
register	Register an IUCr category transformer class.
create	Create a registered transformer by tag.

Functions

loop(experiment) staticmethod

Return a d-to-TOF calibration loop.

Parameters:

Name	Type	Description	Default
experiment	object	TOF powder experiment.	required

Returns:

Type	Description
IucrLoop | None	Calibration loop, or None when all coefficients are zero.

register(transformer_cls) classmethod

Register an IUCr category transformer class.

Parameters:

Name	Type	Description	Default
transformer_cls	type[IucrCategoryTransformer]	Transformer subclass to register.	required

Returns:

Type	Description
type[IucrCategoryTransformer]	The registered class, unchanged.

create(tag) classmethod

Create a registered transformer by tag.

Parameters:

Name	Type	Description	Default
tag	str	Registered transformer tag.	required

Returns:

Type	Description
IucrCategoryTransformer	Transformer instance.

ExcludedRegionsTransformer

Transform excluded x ranges into pdCIF free text.

Methods:

Name	Description
items	Return the excluded-region free-text item.
register	Register an IUCr category transformer class.
create	Create a registered transformer by tag.

Functions

items(experiment) staticmethod

Return the excluded-region free-text item.

Parameters:

Name	Type	Description	Default
experiment	object	Powder experiment.	required

Returns:

Type	Description
tuple[IucrItem, ...]	One _pd_proc.info_excluded_regions item.

register(transformer_cls) classmethod

Register an IUCr category transformer class.

Parameters:

Name	Type	Description	Default
transformer_cls	type[IucrCategoryTransformer]	Transformer subclass to register.	required

Returns:

Type	Description
type[IucrCategoryTransformer]	The registered class, unchanged.

create(tag) classmethod

Create a registered transformer by tag.

Parameters:

Name	Type	Description	Default
tag	str	Registered transformer tag.	required

Returns:

Type	Description
IucrCategoryTransformer	Transformer instance.

SymmetryOperationsTransformer

Transform a space group into explicit symmetry operation rows.

Methods:

Name	Description
loop	Return symmetry operations for a structure.
register	Register an IUCr category transformer class.
create	Create a registered transformer by tag.

Functions

loop(structure) staticmethod

Return symmetry operations for a structure.

Parameters:

Name	Type	Description	Default
structure	object	Structure whose space group defines the operations.	required

Returns:

Type	Description
IucrLoop	Symmetry-operation loop.

register(transformer_cls) classmethod

Register an IUCr category transformer class.

Parameters:

Name	Type	Description	Default
transformer_cls	type[IucrCategoryTransformer]	Transformer subclass to register.	required

Returns:

Type	Description
type[IucrCategoryTransformer]	The registered class, unchanged.

create(tag) classmethod

Create a registered transformer by tag.

Parameters:

Name	Type	Description	Default
tag	str	Registered transformer tag.	required

Returns:

Type	Description
IucrCategoryTransformer	Transformer instance.

ExtinctionTransformer

Transform project extinction metadata into coreCIF fields.

Methods:

Name	Description
items	Return standard and extension extinction items.
register	Register an IUCr category transformer class.
create	Create a registered transformer by tag.

Functions

items(experiment) staticmethod

Return standard and extension extinction items.

Parameters:

Name	Type	Description	Default
experiment	object	Single-crystal experiment.	required

Returns:

Type	Description
tuple[IucrItem, ...]	Extinction items for the IUCr report.

register(transformer_cls) classmethod

Register an IUCr category transformer class.

Parameters:

Name	Type	Description	Default
transformer_cls	type[IucrCategoryTransformer]	Transformer subclass to register.	required

Returns:

Type	Description
type[IucrCategoryTransformer]	The registered class, unchanged.

create(tag) classmethod

Create a registered transformer by tag.

Parameters:

Name	Type	Description	Default
tag	str	Registered transformer tag.	required

Returns:

Type	Description
IucrCategoryTransformer	Transformer instance.

iucr_writer

IUCr journal-submission CIF writer.

Functions:

Name	Description
write_iucr_cif	Write the project as an IUCr journal-submission CIF.
iucr_report_path	Return the target IUCr report path for a project.

Classes

Functions

write_iucr_cif(project, path=None)

Write the project as an IUCr journal-submission CIF.

Parameters:

Name	Type	Description	Default
project	object	Project instance to export.	required
path	str | pathlib.Path | None	Target CIF path. When omitted, the report is written to <project.info.path>/reports/<project.name>.cif.	None

Returns:

Type	Description
pathlib.Path	Path of the written report CIF.

iucr_report_path(project, path=None)

Return the target IUCr report path for a project.

Parameters:

Name	Type	Description	Default
project	object	Project instance.	required
path	str | pathlib.Path | None	Explicit report path.	None

Returns:

Type	Description
pathlib.Path	Resolved report path.

parse

Functions:

Name	Description
document_from_path	Read a CIF document from a file path.
document_from_string	Read a CIF document from a raw text string.
pick_sole_block	Pick the sole data block from a CIF document.
name_from_block	Extract a model name from the CIF block name.
read_cif_str	Read a single string value from a CIF block by tag.

Functions

document_from_path(path)

Read a CIF document from a file path.

document_from_string(text)

Read a CIF document from a raw text string.

pick_sole_block(doc)

Pick the sole data block from a CIF document.

name_from_block(block)

Extract a model name from the CIF block name.

read_cif_str(block, tag)

Read a single string value from a CIF block by tag.

Strips surrounding single or double quotes when present, and returns None for absent tags or CIF unknown/inapplicable markers (? / .).

Parameters:

Name	Type	Description	Default
block	gemmi.cif.Block	Parsed CIF data block to read from.	required
tag	str	CIF tag to look up (e.g. '_peak.type').	required

Returns:

Type	Description
str | None	Unquoted string value, or None if not found.

serialize

Functions:

Name	Description
format_value	Format a single CIF value for output.
format_param_value	Format a parameter value for CIF output, encoding the free flag.
param_to_cif	Render a single descriptor/parameter to a CIF line.
category_item_to_cif	Render a CategoryItem-like object to CIF text.
category_collection_to_cif	Render a CategoryCollection-like object to CIF text.
category_owner_to_cif	Render a category-owning object without a data_ header.
datablock_item_to_cif	Render a DatablockItem-like object to CIF text.
datablock_collection_to_cif	Render a collection of datablocks by joining their CIF blocks.
project_info_to_cif	Render ProjectInfo to CIF text (id, title, description).
project_config_to_cif	Render project-level configuration to project.cif text.
project_to_cif	Render a whole project by concatenating sections when present.
experiment_to_cif	Render an experiment: datablock part plus measured data.
analysis_to_cif	Render analysis metadata, aliases, and constraints to CIF.
project_info_from_cif	Populate a ProjectInfo instance from CIF text.
project_config_from_cif	Populate project-level configuration from project.cif text.
analysis_from_cif	Populate an Analysis instance from CIF text.
param_from_cif	Populate a single descriptor from a CIF block.
category_item_from_cif	Populate each parameter from CIF block at given loop index.
category_collection_from_cif	Populate a CategoryCollection from a CIF loop.

Classes

Functions

format_value(value)

Format a single CIF value for output.

.. note:: The precision must be high enough so that the minimizer's finite-difference Jacobian probes (typically ~1e-8 relative) survive the float→string→float round-trip through CIF. Trailing zeros after the decimal point are stripped for readability (e.g. 54902.18695000 → 54902.18695, 0.0 → 0.).

format_param_value(param)

Format a parameter value for CIF output, encoding the free flag.

CIF convention for numeric parameters:

• Fixed or constrained parameter: plain value, e.g. 3.8909
• Free parameter without uncertainty: value with empty brackets, e.g. 3.8909()
• Free parameter with uncertainty: value with esd in brackets, e.g. 3.89(20)

User-constrained (dependent) parameters are always written without brackets, even if their free flag is True, because they are not independently varied by the minimizer.

Non-numeric parameters and descriptors without a free attribute are formatted with :func:format_value.

Parameters:

Name	Type	Description	Default
param	object	A descriptor or parameter exposing .value and optionally .free, .user_constrained, and .uncertainty.	required

Returns:

Type	Description
str	Formatted CIF value string.

param_to_cif(param)

Render a single descriptor/parameter to a CIF line.

Expects param to expose _cif_handler.names and value. Free parameters are written with uncertainty brackets (see :func:format_param_value).

category_item_to_cif(item)

Render a CategoryItem-like object to CIF text.

Expects item.parameters iterable of params with _cif_handler.names and value.

category_collection_to_cif(collection, max_display=None)

Render a CategoryCollection-like object to CIF text.

Uses first item to build loop header, then emits rows for each item.

Parameters:

Name	Type	Description	Default
collection	object	A CategoryCollection-like object.	required
max_display	int | None	When set to a positive integer, truncate the output to at most this many rows (half from the start, half from the end) with an ... separator. None emits all rows.	None

Returns:

Type	Description
str	CIF text representing the collection as a loop.

category_owner_to_cif(owner, max_loop_display=None)

Render a category-owning object without a data_ header.

datablock_item_to_cif(datablock, max_loop_display=None)

Render a DatablockItem-like object to CIF text.

Emits a data_ header and then concatenates category CIF sections.

Parameters:

Name	Type	Description	Default
datablock	object	A DatablockItem-like object.	required
max_loop_display	int | None	When set, truncate loop categories to this many rows. None emits all rows (used for serialisation).	None

Returns:

Type	Description
str	CIF text representing the datablock as a loop.

datablock_collection_to_cif(collection)

Render a collection of datablocks by joining their CIF blocks.

project_info_to_cif(info)

Render ProjectInfo to CIF text (id, title, description).

project_config_to_cif(project)

Render project-level configuration to project.cif text.

project_to_cif(project)

Render a whole project by concatenating sections when present.

experiment_to_cif(experiment)

Render an experiment: datablock part plus measured data.

analysis_to_cif(analysis)

Render analysis metadata, aliases, and constraints to CIF.

project_info_from_cif(info, cif_text)

Populate a ProjectInfo instance from CIF text.

Reads the core project metadata fields from CIF text.

Parameters:

Name	Type	Description	Default
info	object	The ProjectInfo instance to populate.	required
cif_text	str	CIF text content of project.cif.	required

project_config_from_cif(project, cif_text)

Populate project-level configuration from project.cif text.

analysis_from_cif(analysis, cif_text)

Populate an Analysis instance from CIF text.

Reads the fit configuration, aliases, constraints, and joint-fit experiment weights from the given CIF string.

Parameters:

Name	Type	Description	Default
analysis	object	The Analysis instance to populate.	required
cif_text	str	CIF text content of analysis.cif.	required

param_from_cif(self, block, idx=0)

Populate a single descriptor from a CIF block.

Parameters:

Name	Type	Description	Default
self	GenericDescriptorBase	The descriptor instance to populate.	required
block	gemmi.cif.Block	Parsed CIF block to read values from.	required
idx	int	Row index used when the tag belongs to a loop.	0

category_item_from_cif(self, block, idx=0)

Populate each parameter from CIF block at given loop index.

category_collection_from_cif(self, block)

Populate a CategoryCollection from a CIF loop.

Parameters:

Name	Type	Description	Default
self	CategoryCollection	The collection instance to populate.	required
block	gemmi.cif.Block	Parsed CIF block to read the loop from.	required

Raises:

Type	Description
ValueError	If the collection has no _item_type defined.

results_sidecar

Bayesian fit sidecar read/write helpers.

Functions:

Name	Description
prepare_analysis_results_sidecar_for_new_fit	Warn and remove the results sidecar before a fresh fit starts.
write_analysis_results_sidecar	Write persisted Bayesian arrays to analysis/results.h5.
read_analysis_results_sidecar	Read persisted Bayesian arrays from analysis/results.h5.

Classes

Functions

prepare_analysis_results_sidecar_for_new_fit(*, analysis_dir)

Warn and remove the results sidecar before a fresh fit starts.

write_analysis_results_sidecar(*, analysis, analysis_dir)

Write persisted Bayesian arrays to analysis/results.h5.

Parameters:

Name	Type	Description	Default
analysis	object	Analysis instance that owns fit-state categories and runtime fit results.	required
analysis_dir	Path	The project analysis/ directory.	required

read_analysis_results_sidecar(*, analysis, analysis_dir)

Read persisted Bayesian arrays from analysis/results.h5.

Parameters:

Name	Type	Description	Default
analysis	object	Analysis instance that owns fit-state categories.	required
analysis_dir	Path	The project analysis/ directory.	required