hikari.dataframes package

Submodules

hikari.dataframes.base module

class hikari.dataframes.base.BaseFrame

Bases: object

This class stores and manipulates basic information present in majority of crystallographic information files such as unit cell parameters stored in scalars and vectors.

BaseFrame utilises the following notation for stored attributes:

• The name begins from a unit cell property we are interested in:

• “a”, “b”, “c” describe unit cell lengths/vectors a, b, c,

• “al”, “be”, “ga” describe unit cell angles alpha, beta, gamma,

• “v” describes unit cell volume,

• “x”, “y”, “z” describe directions - normalised unit cell vectors.

• “A”, “G” describe stacked vector and metric matrix, respectively.

• The unit cell parameter symbol is then followed by an underscore “_”.

• The name ends with a single letter denoting type of space and variable:

• “d” (from Direct) denotes direct space scalars/matrices,

• “r” (from Reciprocal) denotes reciprocal space scalars/matrices,

• “v” (from Vector) denotes direct space vectors,

• ‘w” (similar to “v”) denotes reciprocal space vectors.

The values can be accessed by referencing a given attribute in the object, for example BaseFrame. a_d stores information about the lattice constant a in direct space as a floating point, but BaseFrame. a_v is a direct space vector. Available attributes have been once again presented in a table below:

	Available constants	in direct space	in reciprocal space	Unit (^-1 in reciprocal)
Scalars	a, b, c	a_d, b_d, c_d	a_r, b_r, c_r	Angstrom
	al, be, ga	al_d, be_d, ga_d	al_r, be_r, ga_r	Radian
	v	v_d	v_r	Angstrom^3
Vectors	a, b, c	a_v, b_v, c_v	a_w, b_w, c_w	Angstrom
	x, y, z	x_v, y_v, z_v	x_w, y_w, z_w	Angstrom
Matrices	A	A_d	A_r	Angstrom^2
	G	G_d	G_r	Angstrom^2

property A_d

Returns

Basis matrix A with vertically stacked direct space vectors.

Return type

np.array

property A_r

Returns

Basis matrix A* with vertically stacked reciprocal space vectors.

Return type

np.array

property G_d

Returns

Direct space metric matrix [ai . aj]ij.

Return type

np.array

property G_r

Returns

Reciprocal space metric matrix [ai* . aj*]ij.

Return type

np.array

IMPORTED_FROM_CIF = {'a': ['_cell_length_a', <function cfloat>, 1.0], 'al': ['_cell_length_alpha', <function cfloat>, 90], 'b': ['_cell_length_b', <function cfloat>, 1.0], 'be': ['_cell_length_beta', <function cfloat>, 90], 'c': ['_cell_length_c', <function cfloat>, 1.0], 'ga': ['_cell_length_gamma', <function cfloat>, 90], 'ub11': ['_diffrn_orient_matrix_UB_11', <class 'float'>, 1.0], 'ub12': ['_diffrn_orient_matrix_UB_12', <class 'float'>, 0.0], 'ub13': ['_diffrn_orient_matrix_UB_13', <class 'float'>, 0.0], 'ub21': ['_diffrn_orient_matrix_UB_21', <class 'float'>, 0.0], 'ub22': ['_diffrn_orient_matrix_UB_22', <class 'float'>, 1.0], 'ub23': ['_diffrn_orient_matrix_UB_23', <class 'float'>, 0.0], 'ub31': ['_diffrn_orient_matrix_UB_31', <class 'float'>, 0.0], 'ub32': ['_diffrn_orient_matrix_UB_32', <class 'float'>, 0.0], 'ub33': ['_diffrn_orient_matrix_UB_33', <class 'float'>, 1.0]}

SELLING_E3_TRANSFORMATIONS = [array([[ 1,  1,  0],        [ 0, -1,  0],        [ 0,  0,  1]], dtype=int8), array([[-1,  0,  0],        [ 1,  1,  0],        [ 0,  0,  1]], dtype=int8), array([[-1,  0,  0],        [ 0,  1,  0],        [ 1,  0,  1]], dtype=int8), array([[-1,  0,  0],        [ 1,  1,  0],        [ 1,  0,  1]], dtype=int8), array([[ 1,  1,  0],        [ 0, -1,  0],        [ 0,  1,  1]], dtype=int8), array([[ 1,  0,  1],        [ 0,  1,  1],        [ 0,  0, -1]], dtype=int8)]

SELLING_S6_TRANSFORMATIONS = [array([[-1,  0,  0,  0,  0,  0],        [ 1,  1,  0,  0,  0,  0],        [ 1,  0,  0,  0,  1,  0],        [-1,  0,  0,  1,  0,  0],        [ 1,  0,  1,  0,  0,  0],        [ 1,  0,  0,  0,  0,  1]], dtype=int8), array([[ 1,  1,  0,  0,  0,  0],        [ 0, -1,  0,  0,  0,  0],        [ 0,  1,  0,  1,  0,  0],        [ 0,  1,  1,  0,  0,  0],        [ 0, -1,  0,  0,  1,  0],        [ 0,  1,  0,  0,  0,  1]], dtype=int8), array([[ 1,  0,  1,  0,  0,  0],        [ 0,  0,  1,  1,  0,  0],        [ 0,  0, -1,  0,  0,  0],        [ 0,  1,  1,  0,  0,  0],        [ 0,  0,  1,  0,  1,  0],        [ 0,  0, -1,  0,  0,  1]], dtype=int8), array([[ 1,  0,  0, -1,  0,  0],        [ 0,  0,  1,  1,  0,  0],        [ 0,  1,  0,  1,  0,  0],        [ 0,  0,  0, -1,  0,  0],        [ 0,  0,  0,  1,  1,  0],        [ 0,  0,  0,  1,  0,  1]], dtype=int8), array([[ 0,  0,  1,  0,  1,  0],        [ 0,  1,  0,  0, -1,  0],        [ 1,  0,  0,  0,  1,  0],        [ 0,  0,  0,  1,  1,  0],        [ 0,  0,  0,  0, -1,  0],        [ 0,  0,  0,  0,  1,  1]], dtype=int8), array([[ 0,  1,  0,  0,  0,  1],        [ 1,  0,  0,  0,  0,  1],        [ 0,  0,  1,  0,  0, -1],        [ 0,  0,  0,  1,  0,  1],        [ 0,  0,  0,  0,  1,  1],        [ 0,  0,  0,  0,  0, -1]], dtype=int8)]

property a_d

Returns

Length of unit cell vector a in direct space.

Return type

float

property a_r

Returns

Length of unit cell vector a* in reciprocal space.

Return type

float

property a_v

Returns

Unit cell vector a in direct space.

Return type

numpy.array

property a_w

Returns

Unit cell vector a* in reciprocal space.

Return type

numpy.array

property al_d

Returns

Angle between vectors b and c in degrees.

Return type

float

property al_r

Returns

Angle between vectors b* and c* in degrees.

Return type

float

property b_d

Returns

Length of unit cell vector b in direct space.

Return type

float

property b_r

Returns

Length of unit cell vector b* in reciprocal space.

Return type

float

property b_v

Returns

Unit cell vector b in direct space.

Return type

numpy.array

property b_w

Returns

Unit cell vector b* in reciprocal space.

Return type

numpy.array

property be_d

Returns

Angle between vectors c and a in degrees.

Return type

float

property be_r

Returns

Angle between vectors c* and a* in degrees.

Return type

float

property c_d

Returns

Length of unit cell vector c in direct space.

Return type

float

property c_r

Returns

Length of unit cell vector c* in reciprocal space.

Return type

float

property c_v

Returns

Unit cell vector c in direct space.

Return type

numpy.array

property c_w

Returns

Unit cell vector c* in reciprocal space.

Return type

numpy.array

edit_cell(**parameters)

Edit direct space unit cell using a dictionary with the following keys:

• “a” - for unit cell parameter a given in Angstrom,

• “b” - for unit cell parameter b given in Angstrom,

• “c” - for unit cell parameter c given in Angstrom,

• “al” - for unit cell parameter alpha given in degrees or radians,

• “be” - for unit cell parameter beta given in degrees or radians,

• “ga” - for unit cell parameter gamma given in degrees or radians.

This method is equivalent to manually setting all six unit cell parameters in direct space, a_d, b_d, c_d, al_d, be_d, ga_d, and then running a private method _refresh_cell() to update other values.

Please mind that the while the “a”, “b” and “c” are always given in Angstrom, the angles might be given either in degrees or in radians. For details see function hikari.utility.math_tools.angle2rad().

It is not required for all previously stated keys to be present at each method call. If a key has not been given, previously provided and stored value is being used. If no value has been given, the default length values of 1.0 for a, b, c and default angle values of pi/2 for al, be, ga are used instead.

Parameters

parameters (float) – Values of unit cell parameters to be changed

fill_from_cif_block(block, fragile=False)

Import all data specified in IMPORTED_FROM_CIF such as unit cell parameters and orientation matrix from provided instance of hikari.dataframes.cif.CifBlock called block. Unless fragile is True, use defaults instead of rising KeyError.

Parameters

• block (hikari.dataframes.CifBlock) – CifBlock containing imported information.

• fragile (bool) – If True, raise Error when any imported info is missing

property ga_d

Returns

Angle between vectors a and b in degrees.

Return type

float

property ga_r

Returns

Angle between vectors a* and b* in degrees.

Return type

float

orientation

3x3 matrix describing orientation of crystal during experiment.

property v_d

Returns

Unit cell volume in direct space.

Return type

float

property v_r

Returns

Unit cell volume in reciprocal space.

Return type

float

hikari.dataframes.cif module

class hikari.dataframes.cif.CifBlock(*args)

Bases: OrderedDict

CifBlock object handles all data inside an individual block of Cif file. It is a subclass of an OrderedDict and, as such, features a lot of similarities with python dictionary while preserving item order. Individual Cif items can be accessed or assigned using a dict-like syntax.

get_as_type(key, typ, default=None)

Get value of self[key] converted to typ. If value is a list, convert its contents element-wise.

Parameters

• key (str) – key associated with accessed element

• typ (Callable) – type/function applied to a value or its every element

• default (Any) – if given, return it on KeyError

Returns

converted value of self[key] or default

Return type

Union[List, str]

read(path, block)

Read the contents of .cif file specified by the path parameter, but access and store only the block data block in self.

Parameters

• path (str) – Absolute or relative path to the .cif file.

• block (str) – Name of the cif data block to be accessed

Return type

None

write(path)

Write the contents of CifBlock to the .cif file specified by the path parameter, using ‘hikari’ as block name.

Parameters

path (str) – Absolute or relative path to the .cif file.

Return type

None

class hikari.dataframes.cif.CifFrame

Bases: OrderedDict

A master object which manages cif files. It utilises other Cif* classes to manage multiple CifBlock`s with crystallographic information. It is a subclass of an `OrderedDict and, as such, features a lot of similarities with python dictionary while preserving item order. Individual Cif blocks and items within them can be accessed or assigned using a single- or nested- dict-like syntax.

Similarly to other Frame`s, `CifFrame is designed to work in-place, meaning it should be first created, and only then accessed using methods such as read() or write(), but not chain assignments.

Unlike OrderedDict, CifBlock always initiates empty and does not accept any parameters at creation.

read(path)

Read the contents of .cif file specified by the path parameter. Store each found block as a {block_name: CifBlock} pair.

Parameters

path (str) – Absolute or relative path to the .cif file.

Return type

None

write(path)

Write the contents of CifFrame to the .cif file specified by the path parameter.

Parameters

path (str) – Absolute or relative path to the .cif file.

Return type

None

class hikari.dataframes.cif.CifIO(cif_file_path, validate=True)

Bases: ABC

A base class for CifRead and CifWrite. This class and its inheritors base on the IUCr File Syntax version 1.1 Working specification available [here](https://www.iucr.org/resources/cif/spec/version1.1/cifsyntax)

COMMENT_REGEX = re.compile('(?<=\\s)(#.*)(?=$)|(?<=^)(#.*)(?=$)', re.MULTILINE)

MATCHING_OUTER_DELIMITERS_REGEX = re.compile('(?<=^)([\\"\';])([\\S\\s]*)(\\1)(?=$)')

MATCHING_QUOTES_REGEX = re.compile('(\\B[\\"\'])((?:\\\\\\1|(?!\\1\\s).)*.)(\\1\\B)')

MULTILINE_QUOTE_REGEX = re.compile('(^;)([\\S\\s]*?)(\\n;)', re.MULTILINE)

WHITESPACE_SUBSTITUTES = {'\t': '▄', '\n': '▀', ' ': '█'}

class hikari.dataframes.cif.CifIOBuffer(target)

Bases: ABC

abstract add(data)

abstract flush()

class hikari.dataframes.cif.CifReader(cif_file_path, validate=True)

Bases: CifIO

A helper class managing reading cif files into CifFrame or CifBlock.

class State(value)

Bases: Enum

This class stores current cif reading state (eg. inside loop etc.)

default = 0

loop_keys = 1

loop_values = 2

property blocks

A dictionary of all blocks names and their positions in cif file.

format_dictionary(parsed_dict_)

Reformat a dictionary of parsed data so that the format of every name and value agrees with the cif core dictionary stored in CifValidator.

Parameters

• parsed_dict – Dictionary with data pairs

• parsed_dict_ (Dict[str, List[str]]) –

Returns

Data dictionary with correctly formatted data names and values

Return type

Dict[str, Union[str, List[str]]]

parse_lines(start, end)

Read the data from lines numbered start to end, interpret it, and return it as an instance of an OrderedDict.

Parameters

• start (int) – number of the first line which data should be read from

• end (int) – number of the first line which should not be read anymore

Returns

ordered dictionary with name: value pairs for all parsed lines

Return type

OrderedDict

protect_multilines()

Replace whitespace between every pair of “n;” sequences with substitutes and remove the outer semicolons in self.file_contents.

Return type

None

protect_quotes()

Replace whitespace between every pair of matching quotation marks (single or double) with substitutes and remove the outer quotation marks in self.contents. See stack overflow /q/46967465/ for details.

Return type

None

read()

Read the contents of cif currently pointed by file_path and block data_block_header and return them to a dict.

Returns

A dictionary containing information read from .cif file.

Return type

OrderedDict

remove_comments()

Replace all comment blocks (whitespace or start-of-file followed by “#”) within self.file_contents with empty strings.

Return type

None

classmethod revert_delimiters_and_whitespace(string)

If present, remove outer delimiters (matching quotes or semicolons) from supplied string, remove self.WHITESPACE_SUBSTITUTES and return string.

Returns

string without outer delimiters nor whitespace substitutes.

Parameters

string (str) –

Return type

str

class hikari.dataframes.cif.CifReaderBuffer(target)

Bases: CifIOBuffer

Buffer for reading data from cif file into CifReader

add(word)

Append the word to names or values based on its first char

flush()

Update the target dict with names and values stored hitherto

class hikari.dataframes.cif.CifValidator

Bases: OrderedDict

This object reads an appropriate cif core dictionary and uses it in order to format or validate all entries passing through it.

The CifValidator contains all keys from core cif dictionary. In order to access individual values, use .get() instead of bracket notation.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

get__category(key, default=None)

get__list(key, default=None)

class hikari.dataframes.cif.CifWriter(cif_file_path, validate=True)

Bases: CifIO

A helper class managing writing CifFrame or CifBlock into cif files

write(cif_frame)

class hikari.dataframes.cif.CifWriterBuffer(target)

Bases: CifIOBuffer

Buffer for writing data from CifReader into cif file

MAX_LINE_LENGTH = 80

MAX_NAME_LENGTH = 33

MIN_STEP_LENGTH = 2

WHITESPACE = {'\t', '\n', ' '}

add(data)

Parameters

data (tuple) –

enquote(text, force=False)

flush()

format_line(k, v)

format_table()

hikari.dataframes.hkl module

class hikari.dataframes.hkl.HklFrame

Bases: BaseFrame

A master object which manages single-crystal diffraction files. It utilises other Hkl* classes to import, store, manipulate and output information about single-crystal diffraction patterns.

HklFrame acts as an container which stores the diffraction data (Pandas dataframe, table) and elementary crystal cell data (hikari.dataframes.Base). Demanding methods belonging to this class are vectorized, providing relatively satisfactory performance and high memory capacity. HklFrame methods are designed to work in-place, so the work strategy is to create a new instance of HklFrame for each reflection dataset, manipulate it using methods, eg. merge() or trim(), and copy() to other object or output using write() if needed.

The HklFrame always initiates empty and does not accept any arguments. Some of the magic methods, such as __len__() and __add__() are defined and describe/operate on the frame.

HKL_LIMIT = 127

Highest absolute value of h, k or l index, which can be interpreted correctly by current version of the software.

calculate_fcf_statistics()

Calculate values of zeta (I - Ic) / si on other stats based on contents of fcf files. Save new key and its values into the dataframe.

copy()

Returns

An exact deep copy of this HklFrame.

Return type

HklFrame

dac_trim(opening_angle=35.0, vector=None)

Remove reflections outside the opening_angle DAC-accessible volume. Sample/DAC orientation can be supplied either via specifying crystal orientation in hikari.dataframes.BaseFrame, in orientation or providing a xyz* vector perpendicular to the dac-accessible disc. For further details refer to *Tchoń & Makal, IUCrJ 8, 1006-1017 (2021)*.

Parameters

• opening_angle (float) – DAC single opening angle in degrees, default 35.0.

• vector (Tuple[float]) – Provides information about orientation of crystal relative to DAC. If None, current orientation is used instead.

Returns

HklFrame containing only reflections in dac-accessible region.

Return type

HklFrame

dacs_count(opening_angle=35.0, vectors=array([1, 0, 0]))

Count unique dac-accessible reflections for n crystals placed such that vector n is perpendicular to diamond. For details see dac_trim().

Parameters

• opening_angle (float) – DAC single opening angle in degrees, default 35.0.

• vectors (np.array) – Array containing rotational axes of available DAC-discs.

Returns

Array with numbers of unique reflns in DAC-accessible region.

Return type

np.array

extinct(space_group=Group(SymmOp(np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]), np.array([0.0, 0.0, 0.0]))))

Removes from dataframe reflections which should be extinct based on space hikari.symmetry.group.Group. For ref. see ITC-A12.3.5.

Parameters

space_group (hikari.symmetry.group.Group) – Space group used to extinct the reflections.

fill(radius=2.0)

Fill dataframe with all reflections within radius from space origin.

Parameters

radius (float) – Maximum distance from the reciprocal space origin to placed reflection (in reciprocal Angstrom).

Return type

None

find_equivalents(point_group=Group(SymmOp(np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]), np.array([0.0, 0.0, 0.0]))))

Assign each reflection its symmetry equivalence identifier and store it in the hikari.dataframes.HklFrame.data[‘equiv’] column. The ID is an integer unique for each set of equivalent reflections.

In order to provide an information about equivalence, a point_group of reciprocal space must be provided (default PG[‘1’]). Point groups and their notation can be found in hikari.symmetry sub-package.

Parameters

point_group (hikari.symmetry.Group) – Point group used to determine symmetry equivalence

from_dict(dictionary)

Construct the self.data using information stored in dictionary. The dictionary keys must be valid strings, see HklKeys for a list of valid keys. The dictionary values must be iterable of equal size, preferably numpy.ndarray.

Parameters

dictionary (Dict[str, numpy.ndarray]) – Dictionary with “key - iterable of values” pairs.

keys

Object managing keys (column names) of table.

property la

Wavelength of radiation used in the diffraction experiment. Can be set using popular abbreviations such as “MoKa” or “CuKb”, where a and b stand for alpha and beta. Implemented cathode materials include: “Ag”, “Co”, “Cr”, “Cu”, “Fe”, “Mn”, “Mo”, “Ni”, “Pd”, “Rh”, “Ti”, “Zn” and have been imported from International Tables of Crystallography, Volume C, Table 4.2.4.1, 3rd Edition.

Returns

wavelength of radiation used in experiment

Return type

float

merge(point_group=Group(SymmOp(np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]), np.array([0.0, 0.0, 0.0]))))

Average down each set of redundant reflections present in the table, to one reflection. The redundancy is determined using the find_equivalents() method with appropriate point group. Therefore, the merging can be used in different ways depending on point group:

• For PG[‘1’], only reflections with exactly the same h, k and l indices will be merged. Resulting dataframe will not contain any duplicates.

• For PG[‘-1’] reflections with the same h, k and l as well as their Friedel pairs will be merged together to one reflection.

• For PG[‘mmm’] all equivalent reflections of “mmm” point group will be merged. Since “mmm” is centrosymmetric, Friedel pairs will be merged.

• For PG[‘mm2’] symmetry-equivalent reflections within the “mmm” point group will be merged, but the Friedel pairs will be preserved.

The procedure will have a different effect on different dataframe keys, depending on their “reduce_behaviour” specified in HklKeys. Fixed parameters h, k, l, x, y, z, r and equiv will be preserved; Floating points such as intensity I, structure factor F and their uncertainties si and sf will be averaged using arithmetic mean; Multiplicity m will be summed; Other parameters which would lose their meaning such as batch number b will be discarded.

The merging inevitably removes some information from the dataframe, but it can be necessary for some operations. For example, the drawing procedures work much better and provide clearer image if multiple points occupying the same position in space are reduced to one instance.

Parameters

point_group (hikari.symmetry.Group) – Point Group used to determine symmetry equivalence

place()

Assign reflections their positions in reciprocal space (“x”, “y”, “z”) and calculate their distance from origin (“r”) in reciprocal Angstrom. Save four new keys and their values into the dataframe.

property r_lim

Returns

Radius of limiting sphere calculated in A-1 based on la

Return type

float

read(hkl_path, hkl_format='shelx_4')

Read the contents of .hkl file as specified by path and format, and store them in the pandas dataframe in self.data. For a list of all available .hkl formats, please refer to hikari.dataframes.HklIo.format.

Parameters

• hkl_path (str) – Absolute or relative path to the .hkl file.

• hkl_format (union[int, str, OrderedDict]) – Format of provided .hkl file.

stats(bins=10, space_group=Group(SymmOp(np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]), np.array([0.0, 0.0, 0.0]))))

Returns completeness, redundancy, number of all, unique & theoretically possible reflections within equal-volume bins in given space group.

Parameters

• bins (int) – Number of equal-volume bins to divide the data into.

• space_group (hikari.symmetry.Group) – Group used to calculate equivalence and extinctions.

Returns

String containing table with stats as a function of resolution

Return type

str

table

Pandas dataframe containing diffraction data information. Each row represents one reflection observation, while each column has one piece of information about the reflections. For a list of available keys, see HklKeys, whose instance is used to menage the keys of this table.

thin_out(target_cplt=1.0)

Randomly remove reflections from dataframe in order to decrease the completeness to target_cplt (relatively to initial completeness).

Parameters

target_cplt (float) – Percentage of data not removed from dataframe

to_res(path='hkl.res', colored='m')

Export the reflection information from table to .res file, so that a software used to visualize .res files can be used to visualise a diffraction data in three dimensions.

Parameters

• colored (str) – Which key of dataframe should be visualised using color.

• path (str) – Absolute or relative path where the file should be saved

transform(operations)

Apply a symmetry operation or list of symmetry operations to transform the diffraction pattern.

If one symmetry operation (3x3 or 4x4 numpy array / matrix) is provided, it effectively multiplies the hkl matrix by the operation matrix and accordingly alters the self.data dataframe. As a result, the length of self.data before and after transformation is the same.

However, the function behaves slightly counter-intuitively if two or more operation matrices are provided. In such case the method applies the transformation procedure independently for each operation, and then concatenates resulting matrices. Resulting self.data is len(operations) times longer than the initial.

The function can use 3x3 or larger (eg. 4x4) matrices, as it selects only the upper-left 3x3 segment for the sake of calculations. Also, while reconstructing the symmetry of merged reflection file it is important to use all symmetry operations, not only generators.

Single symmetry operations or their lists belonging to certain point groups can be imported from hikari.symmetry module.

Parameters

operations (Union[Tuple[np.ndarray, np.ndarray], np.ndarray]) – Iterable of operation matrices to be applied

trim(limit)

Remove reflections further than limit from reciprocal space origin.

Parameters

limit (float) – Radius of the trimming sphere in reciprocal Angstrom

write(hkl_path, hkl_format='shelx_4')

Write the contents of dataframe to a .hkl file using specified path and format. For a list of all available .hkl formats, please refer to hikari.dataframes.HklIo.format.

Parameters

• hkl_path (str) – Absolute or relative path to the .hkl file.

• hkl_format (union[int, str, OrderedDict]) – Desired format of .hkl file.

class hikari.dataframes.hkl.HklIo(hkl_file_path, hkl_file_format)

Bases: object

A helper class supporting HklFrame. Menages reading and writing hkl files into and out of HklFrame’s dataframe

property format

Return a name of currently used hkl file format. Available file formats and their aliases are defined internally in .json files and have been presented in a table below:

Name	Aliases	Contents (format string)	Prefix	Suffix	Free format
free_2		h -4 k -4 l -4 I -8 si -8 b -4 la -8	NO	YES (a)	YES
free_3		h -4 k -4 l -4 F -8 sf -8 b -4	NO	YES (a)	YES
free_4		h -4 k -4 l -4 I -8 si -8 b -4	NO	YES (a)	YES
free_40	free	h -4 k -4 l -4 I -8 si -8	NO	YES (a)	YES
free_5		h -4 k -4 l -4 I -8 si -8 c -4	NO	YES (a)	YES
free_6		h -4 k -4 l -4 I -8 si -8 m -4	NO	YES (a)	YES
m80		h 4 k 4 l 4 b 4 F 12 None 132	YES (b)	YES (b)	NO
shelx_2	2	h 4 k 4 l 4 I 8 si 8 b 4 la 8	NO	YES (a)	NO
shelx_3	3	h 4 k 4 l 4 F 8 sf 8 b 4	NO	YES (a)	NO
shelx_4	4	h 4 k 4 l 4 I 8 si 8	NO	YES (a)	NO
shelx_40	40	h 4 k 4 l 4 I 8 si 8	NO	YES (a)	NO
shelx_5	5	h 4 k 4 l 4 I 8 si 8 c 4	NO	YES (a)	NO
shelx_6	6	h 4 k 4 l 4 I 8 si 8 m 4	NO	YES (a)	NO
shelx_fcf	fcf	h 4 k 4 l 4 Ic 14 I 14 si 13	YES (*)	NO	NO
tonto_F		h -4 k -4 l -4 F -8 sf -8	YES (c)	YES (c)	YES
tonto_I	tonto	h -4 k -4 l -4 I -8 si -8	YES (c)	YES (c)	YES
xd_F6		h -4 k -4 l -4 b -3 F -13 sf -13	YES (d)	NO	YES
xd_F7		h -4 k -4 l -4 b -3 F -13 sf -13 t -10	YES (d)	NO	YES
xd_F-7		h -4 k -4 l -4 b -3 F -13 sf -13 ph -10	YES (d)	NO	YES
xd_F13		h -4 k -4 l -4 b -3 F -13 sf -13 t -10 u1 -10 u2 -10 u3 -10 v1 -10 v2 -10 v3 -10	YES (d)	NO	YES
xd_I6	xd	h -4 k -4 l -4 b -3 I -13 si -13	YES (d)	NO	YES
xd_I7		h -4 k -4 l -4 b -3 I -13 si -13 t -10	YES (d)	NO	YES
xd_I-7		h -4 k -4 l -4 b -3 I -13 si -13 ph -10	YES (d)	NO	YES
xd_I13		h -4 k -4 l -4 b -3 I -13 si -13 t -10 u1 -10 u2 -10 u3 -10 v1 -10 v2 -10 v3 -10	YES (d)	NO	YES
custom		custom string as above with keys and widths	NO	NO	if all widths in format are <0

Three different types of prefix / suffix are supported at the moment:

• Suffix (a) is a zero-line: a shelx ending line with h = k = l = 0,

• Prefix and suffix (b) express a superflip-style block/start end,

• Prefix and suffix (c) are tonto-characteristic beginning/end of file,

• Prefix (d) is an xd-characteristic line with info about file content.

Pre/suffixes denoted with (*) are not supported in terms of writing. A custom hkl file format can be defined by providing a format string instead of ‘Name’. The string should look like the ones in column “contents”. For the meaning of keys (‘I’, ‘b’, ‘c’ etc.), please refer to HklKeys.

Returns

Returns a name of currently used format.

Return type

str

property is_current_format_free

Return true if currently defined format is free, i.e. the columns are separated by whitespace.

Returns

True if all format widths are negative; False otherwise.

Return type

bool

class hikari.dataframes.hkl.HklKeys(keys=())

Bases: object

A helper class supporting HklFrame. Menages properties and presence of keys present in HklFrame’s dataframe

add(keys)

Add keys from a keys list to the HklKeys handler

defined_keys = {'F', 'I', 'Icsi', 'Iosi', 'None', 'b', 'equiv', 'h', 'k', 'l', 'la', 'm', 'ph', 'r', 'sf', 'si', 't', 'u', 'u1', 'u2', 'u3', 'v1', 'v2', 'v3', 'x', 'y', 'z', 'ze', 'ze2'}

get_property(key, prop)

Get desired key property imported from defined dictionary

remove(keys)

Remove keys from a keys list in the HklKeys handler

set(keys)

Set keys from a keys list in the HklKeys handler

class hikari.dataframes.hkl.HklReader(hkl_file_path, hkl_file_format)

Bases: HklIo

A helper class for HklFrame, Menages reading hkl files and importing data and keys from them

read()

Read the contents of file currently pointed by hkl_file_path and format hkl_file_format and return them to a dictionary.

Returns

A dictionary containing information read from .hkl file.

Return type

dict

class hikari.dataframes.hkl.HklToResConverter(hkl_dataframe)

Bases: object

A class responsible for representing hkl data using using .res format

ELEMENTS = ('H', 'He', 'Li', 'Be', 'B', 'C', 'N', 'O', 'F', 'Ne', 'Na', 'Mg', 'Al', 'Si', 'P', 'S', 'Cl', 'Ar', 'K', 'Ca', 'Sc', 'Ti', 'V', 'Cr', 'Mn', 'Fe', 'Co', 'Ni', 'Cu', 'Zn', 'Ga', 'Ge', 'As', 'Se', 'Br', 'Kr', 'Rb', 'Sr', 'Y', 'Zr', 'Nb', 'Mo', 'Tc', 'Ru', 'Rh', 'Pd', 'Ag', 'Cd', 'In', 'Sn', 'Sb', 'Te', 'I', 'Xe', 'Cs', 'Ba', 'La', 'Ce', 'Pr', 'Nd', 'Pm', 'Sm', 'Eu', 'Gd', 'Tb', 'Dy', 'Ho', 'Er', 'Tm', 'Yb', 'Lu', 'Hf', 'Ta', 'W', 'Re', 'Os', 'Ir', 'Pt', 'Au', 'Hg', 'Tl', 'Pb', 'Bi', 'Po', 'At', 'Rn', 'Fr', 'Ra', 'Ac', 'Th', 'Pa', 'U', 'Np', 'Pu', 'Am', 'Cm', 'Bk', 'Cf', 'Es', 'Fm')

MAX_U = 4.99999

MIN_DISTANCE = 10.0

MIN_U = 1e-05

property abc_scale_factor

property atom_list

property c

convert(path='~')

property largest_absolute_hkl

property res_header

static res_line(_c, _h, _k, _l, _x, _y, _z, _u)

Returns

res line filled based on input element, hkl, xyz and u.

Return type

str

property u

property x

property y

property z

class hikari.dataframes.hkl.HklWriter(hkl_file_path, hkl_file_format)

Bases: HklIo

A helper class for HklFrame, Menages writing hkl files and exporting data to them

write(hkl_data)

Write data from pandas dataframe hkl_data to the file specified at hkl_file_path of format hkl_file_format.

Parameters

hkl_data (pandas.dataframe) – Dataframe containing reflection information.

hikari.dataframes.lst module

class hikari.dataframes.lst.LstFrame

Bases: object

static read_r1(path)

Read and return the final value of R1 from lst file

hikari.dataframes.res module

class hikari.dataframes.res.ResFrame

Bases: BaseFrame

atomic_form_factor(atom, hkl)

Calculate X-ray atomic form factors for a single atom and a hkl array

Parameters

• atom (str) – Atom/ion name/identifier interpreted by form factor table

• hkl (np.array) – A 2D array listing all hkls to consider

Returns

A 1D array listing atomic form factors for desired hkls

Return type

np.array

form_factor(hkl, space_group)

Calculate form factors based on current structure, hkls, and space group

Parameters

• hkl (np.array) – A 2D array listing all hkls to consider

• space_group (hikari.symmetry.Group) – Space group describing the internal crystal symmetry

Returns

A 1D array listing total form factors for desired hkls

Return type

np.array

read(path)

Read data from specified ins/res file and return an OrderedDict

Parameters

path (str) – Relative or absolute path to the res file to be read

Returns

None

Return type

None

temperature_factor(hkl, u)

Calculate temperature factor for single u matrix and a hkl array

Parameters

• hkl (np.array) – A 2D array listing all hkls to consider

• u (np.array) – A classical anisotropic displacement parameters matrix

Returns

A 1D array listing temperature factors for desired hkls

Return type

np.array

class hikari.dataframes.res.ResInstructionType(value)

Bases: Enum

An enumeration.

REPEATING_SINGLET = -1

UNIQUE_INT = 1

UNIQUE_LIST = 2

UNIQUE_MULTILINE = 3

hikari.dataframes.ubase module

class hikari.dataframes.ubase.UBaseFrame

Bases: BaseFrame

A sub-class of hikari.dataframes.BaseFrame capable of the same operation as its parent, but using uncertainty.ufloats instead of floats. As a result, types specified in docstring might be wrong due to inheritance.

IMPORTED_FROM_CIF = {'a': ['_cell_length_a', uncertainties.ufloat_fromstr, 1.0], 'al': ['_cell_length_alpha', uncertainties.ufloat_fromstr, 90], 'b': ['_cell_length_b', uncertainties.ufloat_fromstr, 1.0], 'be': ['_cell_length_beta', uncertainties.ufloat_fromstr, 90], 'c': ['_cell_length_c', uncertainties.ufloat_fromstr, 1.0], 'ga': ['_cell_length_gamma', uncertainties.ufloat_fromstr, 90], 'ub11': ['_diffrn_orient_matrix_UB_11', <class 'float'>, 1.0], 'ub12': ['_diffrn_orient_matrix_UB_12', <class 'float'>, 0.0], 'ub13': ['_diffrn_orient_matrix_UB_13', <class 'float'>, 0.0], 'ub21': ['_diffrn_orient_matrix_UB_21', <class 'float'>, 0.0], 'ub22': ['_diffrn_orient_matrix_UB_22', <class 'float'>, 1.0], 'ub23': ['_diffrn_orient_matrix_UB_23', <class 'float'>, 0.0], 'ub31': ['_diffrn_orient_matrix_UB_31', <class 'float'>, 0.0], 'ub32': ['_diffrn_orient_matrix_UB_32', <class 'float'>, 0.0], 'ub33': ['_diffrn_orient_matrix_UB_33', <class 'float'>, 1.0]}

orientation

3x3 matrix describing orientation of crystal during experiment.

Module contents

This module contains all dataframes utilised in hikari. A dataframe is a low-level object, which stores and manipulates certain crystallographic information. At the moment, the following dataframes are implemented:

• hkl - for single crystal reflection data

• cif - for crystallographic open format data (partially)

• res - for shelx crystal structure data (partially)

Please mind that the hkl frame, HklFrame is the most developed. Other frames are in an early stage of development.