Utility Functions

rs.utils contains symmetry/spacegroup-related operations that serve as the foundation for much of the crystallographic support provided by reciprocalspaceship. These methods are not considered to be user-facing, but they are documented here because they may be useful for composing new methods or algorithms.

Note

In most cases, these functions are written to operate on and return NumPy arrays. This was chosen to ensure that these methods are performant, and can be largely independent of any interface decisions related to rs.DataSet or pandas.

Functions:

add_rfree(dataset[, fraction, ...])	Add an r-free flag to the dataset object for refinement.
apply_to_hkl(H, op)	Apply symmetry operator to hkls.
canonicalize_phases(phases[, deg])	Place phases in the interval between -180 and 180.
compute_dHKL(H, cell)	Compute the real space lattice plane spacing, d, associated with miller indices and cell.
compute_redundancy(hobs, cell, spacegroup[, ...])	Compute the multiplicity of all valid reflections in the reciprocal ASU.
compute_structurefactor_multiplicity(H, sg)	Compute the multiplicity of each reflection in H.
copy_rfree(dataset, dataset_with_rfree[, ...])	Copy the rfree flag from one dataset object to another.
from_structurefactor(sfs)	Convert complex structure factors into structure factor amplitudes and phases
generate_reciprocal_asu(cell, spacegroup, dmin)	Generate the Miller indices of the reflections in the reciprocal ASU.
generate_reciprocal_cell(cell, dmin[, dtype])	Generate the miller indices of the full P1 reciprocal cell.
get_phase_restrictions(H, spacegroup)	Return phase restrictions for Miller indices in a given space group.
get_reciprocal_grid_size(cell, dmin[, ...])	Determine an appropriate 3D grid size for the provided cell and spacegroup to represent data with the given sample_rate and dmin.
hkl_to_asu(H, spacegroup[, return_phase_shifts])	Map hkls to the asymmetric unit and optionally return shifts for the associated phases.
hkl_to_observed(H, isym, sg[, ...])	Apply symmetry operations to move miller indices in the reciprocal asymmetric unit to their originally observed locations.
in_asu(H, spacegroup)	Check to see if Miller indices are in the asymmetric unit of a space group.
is_absent(H, spacegroup)	Determine if Miller indices are systematically absent in a given spacegroup.
is_centric(H, spacegroup)	Determine if Miller indices are centric in a given spacegroup
is_polar(spacegroup)	Classify whether spacegroup is polar
phase_shift(H, op)	Calculate phase shift for symmetry operator.
polar_axes(spacegroup)	Classify which cell axes are polar in given spacegroup
to_structurefactor(sfamps, phases)	Convert structure factor amplitude and phase to complex structure factors

reciprocalspaceship.utils.add_rfree(dataset, fraction=0.05, ccp4_convention=False, inplace=False, seed=None)

Add an r-free flag to the dataset object for refinement. R-free flags are used to identify reflections which are not used in automated refinement routines. This is the crystallographic refinement version of cross validation.

Parameters:

• dataset (rs.DataSet) – Dataset object for which to compute a random fraction.

• fraction (float, optional) – Fraction of reflections to be added to the r-free. (the default is 0.05)

• ccp4_conventiion (bool, optional) – Whether to use the CCP4 convention for R-free flags (Default: False). If True, use CCP4 convention: 0 is test set, 1 is working set, and the key is “FreeR_flag”. If False, use Phenix(CNS/XPOLAR) convention: 1 is test set, 0 is working set, and key is “R-free-flags”. See https://www.ccp4.ac.uk/html/freerflag.html#description for convention details.

• inplace (bool, optional)

• seed (int, optional) – Seed to be passed to numpy.random.default_rng random number generator for reproducible r-free flags. If None (default), r-free flags will different each time.

Returns:

result (rs.DataSet)

reciprocalspaceship.utils.apply_to_hkl(H, op)

Apply symmetry operator to hkls.

Parameters:

• H (array) – n x 3 array of Miller indices

• op (gemmi.Op) – gemmi symmetry operator to be applied

Returns:

result (np.ndarray(int32)) – n x 3 array of Miller indices after operator application

Raises:

RuntimeError – If op generates fractional Miller indices when applied to H

reciprocalspaceship.utils.canonicalize_phases(phases, deg=True)

Place phases in the interval between -180 and 180. deg == True implies degrees; False implies radians.

reciprocalspaceship.utils.compute_dHKL(H, cell)

Compute the real space lattice plane spacing, d, associated with miller indices and cell.

Parameters:

• H (array) – An nx3 array of numerical miller indices.

• cell (tuple, list, np.ndarray of cell parameters, or gemmi.UnitCell) – Unit cell parameters

Returns:

dHKL (array) – Array of floating point d spacings in Å.

reciprocalspaceship.utils.compute_redundancy(hobs, cell, spacegroup, full_asu=True, anomalous=False, dmin=None)

Compute the multiplicity of all valid reflections in the reciprocal ASU.

Parameters:

• hobs (np.array(int)) – An n by 3 array of observed miller indices which are not necessarily in the reciprocal asymmetric unit

• cell (tuple, list, np.ndarray of cell parameters, or gemmi.UnitCell) – Unit cell parameters

• spacegroup (str, int, or gemmi.SpaceGroup) – The space group of the dataset

• full_asu (bool (optional)) – Include all the reflections in the calculation irrespective of whether they were observed.

• anomalous (bool (optional)) – Whether or not the data are anomalous.

• dmin (float (optional)) – If no dmin is supplied, the maximum resolution reflection will be used.

Returns:

• hunique (np.array (int32)) – An n by 3 array of unique miller indices from hobs.

• counts (np.array (int32)) – A length n array of counts for each miller index in hunique.

reciprocalspaceship.utils.compute_structurefactor_multiplicity(H, sg, include_centering=True)

Compute the multiplicity of each reflection in H.

Parameters:

• H (array) – n x 3 array of Miller indices

• spacegroup (str, int, gemmi.SpaceGroup) – The space group to identify the asymmetric unit

• include_centering (bool) – Whether or not to include the multiplicity inherent in the lattice centering. The default is True. If False, the minimum value of epsilon will be 1 irrespective of space group.

Returns:

epsilon (array) – an array of length n containing the multiplicity of each hkl.

reciprocalspaceship.utils.copy_rfree(dataset, dataset_with_rfree, inplace=False, rfree_key=None)

Copy the rfree flag from one dataset object to another.

Parameters:

• dataset (rs.DataSet) – A dataset without an r-free flag or with an undesired one.

• dataset_with_rfree (rs.DataSet) – A dataset with desired r-free flags.

• inplace (bool, optional) – Whether to operate in place or return a copy

• rfree_key (str, optional) – Name of the column containing rfree flags in dataset_with_rfree. If None, dataset_with_rfree will be checked for column “R-free-flags” (phenix convention) then column “FreeR_flag” (ccp4 convention)

Returns:

result (rs.DataSet)

reciprocalspaceship.utils.from_structurefactor(sfs)

Convert complex structure factors into structure factor amplitudes and phases

Parameters:

sfs (np.ndarray) – array of complex structure factors to be converted

Returns:

(sf, phase) (tuple of DataSeries) – Tuple of DataSeries for the structure factor amplitudes and phases corresponding to the provided complex structure factors

reciprocalspaceship.utils.generate_reciprocal_asu(cell, spacegroup, dmin, anomalous=False)

Generate the Miller indices of the reflections in the reciprocal ASU.

If anomalous=True the Miller indices of acentric reflections will be included in both the Friedel-plus and Friedel-minus halves of reciprocal space. Centric Miller indices will only be included in the Friedel-plus reciprocal ASU.

Parameters:

• cell (tuple, list, np.ndarray of paramaters, or gemmi.UnitCell) – Unit cell parameters or UnitCell object

• spacegroup (str, int, gemmi.SpaceGroup) – Space group to identify asymmetric unit

• dmin (float) – Maximum resolution of the data in Å

• anomalous (bool) – Whether to include Friedel-minus Miller indices to represent anomalous data

Returns:

hasu (np.array (np.int32)) – n by 3 array of miller indices in the reciprocal ASU.

reciprocalspaceship.utils.generate_reciprocal_cell(cell, dmin, dtype=<class 'numpy.int32'>)

Generate the miller indices of the full P1 reciprocal cell.

Parameters:

• cell (tuple, list, np.ndarray of cell parameters, or gemmi.UnitCell) – Unit cell parameters

• dmin (float) – Maximum resolution of the data in Å

• dtype (np.dtype (optional)) – The data type of the returned array. The default is np.int32.

Returns:

hkl (np.array(int32))

reciprocalspaceship.utils.get_phase_restrictions(H, spacegroup)

Return phase restrictions for Miller indices in a given space group.

If there are no phase restrictions, an empty list is returned for that Miller index. If a given Miller index is systematically absent an empty list is also returned.

Parameters:

• H (array) – n x 3 array of Miller indices

• spacegroup (str, int, gemmi.SpaceGroup) – Space group for determining phase restrictions

Returns:

restrictions (list of lists) – List of lists of phase restrictions for each Miller index. An empty list is returned for Miller indices without phase restrictions

reciprocalspaceship.utils.get_reciprocal_grid_size(cell, dmin, sample_rate=3.0, spacegroup=None)

Determine an appropriate 3D grid size for the provided cell and spacegroup to represent data with the given sample_rate and dmin.

This function will return the smallest grid that yields a real-space grid spacing of at most dmin/sample_rate (in Å) that is ‘FFT-friendly’, meaning that each dimension has 2, 3, or 5 as the largest prime factors. The grid will also obey any symmetry relations for the spacegroup.

Parameters:

• cell (tuple, list, np.ndarray of cell parameters, or gemmi.UnitCell) – Unit cell parameters

• dmin (float) – Highest-resolution reflection to consider for grid size

• sample_rate (float) – Sets the minimal grid spacing relative to dmin. For example, sample_rate=3 corresponds to a real-space sampling of dmin/3. Value must be >= 1.0 (default: 3.0)

• spacegroup (int, str, gemmi.SpaceGroup, or None) – Spacegroup for imposing symmetry constraints on grid dimensions. (default: None)

Returns:

list(int, int, int) – Grid size with desired spacing (list of 3 integers)

Raises:

ValueError – If sample_rate < 1.0

reciprocalspaceship.utils.hkl_to_asu(H, spacegroup, return_phase_shifts=False)

Map hkls to the asymmetric unit and optionally return shifts for the associated phases.

Examples

>>> H_asu, phi_coeff, phi_shift = hkl_to_asu(H, spacegroup, return_phase_shifts=True)
>>> phase_asu = phi_coeff * (phase + phi_shift)

Parameters:

• H (array) – n x 3 array of Miller indices

• spacegroup (str, int, or gemmi.SpaceGroup) – The space group to identify the asymmetric unit

• return_phase_shifts (bool (optional)) – If True, return the phase shift and phase multiplier to apply to each miller index

Returns:

• H_asu (array) – n x 3 array with the equivalent indices in the asu

• isymm (array) – Length n array of the symmetry operation index for each miller index. This is needed to output an unmerged mtz file.

• phi_coeff (array (optional)) – an array length n containing -1. or 1. for each H

• phi_shift (array (optional)) – an array length n containing phase shifts in degrees

reciprocalspaceship.utils.hkl_to_observed(H, isym, sg, return_phase_shifts=False)

Apply symmetry operations to move miller indices in the reciprocal asymmetric unit to their originally observed locations. Optionally, return the corresponding phase shifts.

Examples

>>> H_obs, phi_coeff, phi_shift = hkl_to_observed(H, isym, spacegroup, return_phase_shifts=True)
>>> phase_obs = phi_coeff * (phase + phi_shift)

Parameters:

• H (array) – n x 3 array of Miller indices

• isym (array) – integer array of isym values corresponding to the symmetry operator used to map the original miller index into the asu. see mtz spec for an explanation of this.

• sg (str, int, or gemmi.SpaceGroup) – The space group to identify the asymmetric unit

• return_phase_shifts (bool (optional)) – If True, return the phase shift and phase multiplier to apply to each miller index

Returns:

• observed_H (array) – n x 3 array of the original Miller indices before they were mapped to the ASU through isym.

• phi_coeff (array (optional)) – an array length n containing -1. or 1. for each H

• phi_shift (array (optional)) – an array length n containing phase shifts in degrees

reciprocalspaceship.utils.in_asu(H, spacegroup)

Check to see if Miller indices are in the asymmetric unit of a space group.

Notes

This function only returns True for the +ASU, and does not consider Miller indices for Friedel pairs to be in the ASU. As such, anomalous data should be provided in two-column anomalous format.

Parameters:

• H (array) – n x 3 array of Miller indices

• spacegroup (str, int, or gemmi.SpaceGroup) – The space group to identify the asymmetric unit

Returns:

result (array) – Array of bools with length n.

reciprocalspaceship.utils.is_absent(H, spacegroup)

Determine if Miller indices are systematically absent in a given spacegroup.

Parameters:

• H (array) – n x 3 array of Miller indices

• spacegroup (str, int, gemmi.SpaceGroup) – The space group in which to classify systematic absences

Returns:

absent (array) – Boolean array of length n. absent[i] == True if H[i] is systematically absent in sg.

reciprocalspaceship.utils.is_centric(H, spacegroup)

Determine if Miller indices are centric in a given spacegroup

Parameters:

• H (array) – n x 3 array of Miller indices

• spacegroup (str, int, gemmi.SpaceGroup) – The space group in which to classify centrics

Returns:

centric (array) – Boolean arreay with len(centric) == np.shape(H)[0] == n

reciprocalspaceship.utils.is_polar(spacegroup)

Classify whether spacegroup is polar

Parameters:

spacegroup (str, int, gemmi.SpaceGroup) – Spacegroup to classify as polar

Returns:

bool – Whether the spacegroup is polar

reciprocalspaceship.utils.phase_shift(H, op)

Calculate phase shift for symmetry operator.

Parameters:

• H (array) – n x 3 array of Miller indices

• op (gemmi.Op) – gemmi symmetry operator to be applied

Returns:

result (array) – array of phase shifts

reciprocalspaceship.utils.polar_axes(spacegroup)

Classify which cell axes are polar in given spacegroup

Notes

• This method assumes that the lattice basis vectors are a, b, and c. Specifically, trigonal spacegroups with rhombohedral centering are not supported.

Parameters:

spacegroup (str, int, gemmi.SpaceGroup) – Spacegroup to classify axes as polar

Returns:

List[bool] – Whether a-, b-, or c-axis is polar

Raises:

ValueError – If trigonal spacegroup is provided with rhombohedral Bravais lattice

reciprocalspaceship.utils.to_structurefactor(sfamps, phases)

Convert structure factor amplitude and phase to complex structure factors

Parameters:

• sfamps (DataSeries or array-like) – Structure factor amplitudes

• phases (DataSeries or array-like) – Phases corresponding to structure factors

Returns:

sfs (np.ndarray) – Array of complex-valued structure factors