`io`

Input/output helpers for data files, CIF, and projects.

Modules:

Name	Description
`ascii`	Helpers for loading numeric data from ASCII files.
`cif`	CIF parsing, serialisation, and IUCr export support.
`edi`	Edi project persistence helpers.
`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 a project directory with project.edi. 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.

Raises:

Type	Description
`FileNotFoundError`	If zip_path does not exist.
`ValueError`	If the archive does not contain a project marker 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`

CIF parsing, serialisation, and IUCr export support.

Modules:

Name	Description
`handler`	Tag specification used by descriptors/parameters.
`iucr_transformers`	IUCr category transformers for structurally reshaped CIF output.
`iucr_writer`	IUCr journal-submission CIF writer.
`parse`	Read CIF documents and tag values via gemmi.
`serialize`	Serialize and deserialize datablocks to and from CIF text.

Modules

`handler`

Tag specification used by descriptors/parameters.

A :class:TagSpec records the names a single descriptor/parameter uses across the two persistence/exchange formats, plus its documentation location:

edi_names — names searched and written for the Edi project format (.edi files). edi_name (edi_names[0]) is the canonical name used when writing.
cif_names — names searched and written for strict CIF import/export (.cif files, including the report). cif_name (cif_names[0]) is the canonical name used when exporting; it is an IUCr/pdCIF dictionary name where one exists and an _easydiffraction_* extension otherwise. Remaining entries are additional spellings accepted on CIF import. Defaults to edi_names when not given.

Both lists are ordered by priority: the first entry is canonical for writing, and the whole list is accepted on read.

Classes:

Name	Description
`TagSpec`	Per-descriptor tag specification across Edi and CIF formats.

Classes

TagSpec(*, edi_names, edi_name=None, cif_names=None, docs_page=None, docs_anchor=None)

Per-descriptor tag specification across Edi and CIF formats.

Methods:

Name	Description
`attach`	Attach to a descriptor or parameter instance.

Attributes:

Name	Type	Description
`edi_names`	`list[str]`	Edi tag names accepted on read; first is canonical.
`edi_name`	`str`	Canonical Edi tag used when writing `.edi` files.
`edi_read_names`	`list[str]`	Accepted `.edi` load names, in lookup order.
`cif_names`	`list[str]`	CIF tag names; first is canonical for export.
`cif_name`	`str`	Canonical CIF tag used by report/strict-CIF export.
`cif_read_names`	`list[str]`	Accepted `.cif` import names, in lookup order.
`read_names`	`list[str]`	Names accepted on read across both formats (union).
`category_name`	`str`	Project data category name derived from the Edi tag.
`category_entry_name`	`str`	Project data item name derived from the Edi tag.
`docs_page`	`str`	Parameter documentation page name.
`docs_anchor`	`str`	Parameter documentation anchor.
`url`	`str`	Versioned online documentation URL for this descriptor.
`uid`	`str \| None`	Unique identifier taken from the owner, if attached.

Attributes

edi_names property

Edi tag names accepted on read; first is canonical.

edi_name property

Canonical Edi tag used when writing .edi files.

edi_read_names property

Accepted .edi load names, in lookup order.

cif_names property

CIF tag names; first is canonical for export.

cif_name property

Canonical CIF tag used by report/strict-CIF export.

cif_read_names property

Accepted .cif import names, in lookup order.

read_names property

Names accepted on read across both formats (union).

category_name property

Project data category name derived from the Edi tag.

category_entry_name property

Project data item name derived from the Edi tag.

docs_page property

Parameter documentation page name.

docs_anchor property

Parameter documentation anchor.

url property

Versioned online documentation URL for this descriptor.

uid property

Unique identifier taken from the owner, if attached.

Methods:

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.

Methods:

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 single-row wavelength items for a monochromatic beam.
`loop`	Return a two-row wavelength loop for an active doublet.
`register`	Register an IUCr category transformer class.
`create`	Create a registered transformer by tag.

Methods:

items(experiment) staticmethod

Return single-row wavelength items for a monochromatic beam.

Emits the single _diffrn_radiation_wavelength row when the beam is monochromatic, or when a second wavelength is recorded but disabled (setup_wavelength_2_to_1_ratio == 0). Returns None when no wavelength exists, or when an active doublet is present so the writer falls through to :meth:loop.

Parameters:

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

Returns:

Type	Description
`tuple[IucrItem, ...] \| None`	Single-row wavelength items, or `None`.

loop(experiment) staticmethod

Return a two-row wavelength loop for an active doublet.

Emits the _diffrn_radiation_wavelength loop with the primary wavelength (wt 1.0) and the second component (wt = setup_wavelength_2_to_1_ratio) when the doublet is active; None otherwise. The incomplete pair (a positive ratio with no second wavelength) is rejected by :func:_wavelength_doublet_active.

Parameters:

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

Returns:

Type	Description
`IucrLoop \| None`	Wavelength loop, or `None` when not an active doublet.

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.

Methods:

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.

Methods:

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.

Methods:

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.

Methods:

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.metadata.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`

Read CIF documents and tag values via gemmi.

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`

Serialize and deserialize datablocks to and from CIF text.

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_metadata_to_cif`	Render project metadata to Edi text.
`project_config_to_cif`	Render project-level configuration to Edi body text.
`project_to_cif`	Render a whole project Edi body from available sections.
`experiment_to_cif`	Render an experiment: datablock part plus measured data.
`analysis_to_cif`	Render analysis metadata, aliases, and constraints as STAR text.
`project_metadata_from_cif`	Populate a ProjectMetadata instance from Edi or CIF text.
`project_config_from_cif`	Populate project-level configuration from Edi or 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 _tags.edi_name 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 _tags.edi_name 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_metadata_to_cif(metadata)

Render project metadata to Edi text.

project_config_to_cif(project)

Render project-level configuration to Edi body text.

project_to_cif(project)

Render a whole project Edi body from available sections.

experiment_to_cif(experiment)

Render an experiment: datablock part plus measured data.

analysis_to_cif(analysis)

Render analysis metadata, aliases, and constraints as STAR text.

project_metadata_from_cif(metadata, cif_text)

Populate a ProjectMetadata instance from Edi or CIF text.

Reads the core project metadata fields from CIF text.

Parameters:

Name	Type	Description	Default
`metadata`	`object`	The `ProjectMetadata` instance to populate.	required
`cif_text`	`str`	Edi or CIF text content of the project metadata section.	required

project_config_from_cif(project, cif_text)

Populate project-level configuration from Edi or 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`	Analysis Edi body text or explicit CIF import text.	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.

`edi`

Edi project persistence helpers.

Modules:

Name	Description
`serialize`	Serialize and validate Edi project sections.

Functions:

Modules

`serialize`

Serialize and validate Edi project sections.

Functions:

Name	Description
`section_to_edi`	Add the Edi schema marker to a serialized section body.
`edi_body_from_text`	Validate Edi text and return its section body.

Functions:

section_to_edi(body)

Add the Edi schema marker to a serialized section body.

Parameters:

Name	Type	Description	Default
`body`	`str`	STAR/CIF section body, optionally with a `data_` block header.	required

Returns:

Type	Description
`str`	Edi text with schema marker lines.

edi_body_from_text(text)

Validate Edi text and return its section body.

An invalid schema marker or inconsistent selector/body content raises ValueError via the validation helpers.

Parameters:

Name	Type	Description	Default
`text`	`str`	Edi section text containing schema marker lines.	required

Returns:

Type	Description
`str`	Section body with schema marker lines removed.

`results_sidecar`

Bayesian fit sidecar read/write helpers.

Functions:

Name	Description
`carry_over_raw_sampler_state`	Copy raw sampler-state groups into a relocated project's sidecar.
`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/mcmc.h5`.
`read_analysis_results_sidecar`	Read persisted Bayesian arrays from `analysis/mcmc.h5`.

Classes

Functions:

`carry_over_raw_sampler_state(*, source_analysis_dir, destination_analysis_dir)`

Copy raw sampler-state groups into a relocated project's sidecar.

A project save_as rebuilds the derived sidecar arrays from memory but cannot reconstruct the raw, resumable sampler state (emcee_chain / dream_state). This copies those groups from the source sidecar into the destination so a resume after load + save_as still finds the chain to extend. No-op when the source sidecar or its raw-state groups are absent.

Parameters:

Name	Type	Description	Default
`source_analysis_dir`	`Path`	The `analysis/` directory of the previously saved project.	required
`destination_analysis_dir`	`Path`	The `analysis/` directory of the relocated project.	required

`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/mcmc.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/mcmc.h5.

Parameters:

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