hikari.scripts ============== .. py:module:: hikari.scripts .. autoapi-nested-parse:: This module contains all major scripts of hikari. A script is a high-level hikari function, which utilises a lot of low-level objects such as hikari :mod:`hikari.dataframe` or :mod:`hikari.symmetry` in order to provide more sophisticated functionality. Since HklFrame is the most developed :mod:`hikari.dataframe` of hikari, majority of existing scripts revolve about modification of the .hkl file. It should be mentioned that writing a hikari script does require elemental knowledge of other objects within the package, but should not be a problem after a short study of code. Users are cordially invited to propose their own scripts or script ideas. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/hikari/scripts/angular_explorer/index /autoapi/hikari/scripts/compare_adps/index /autoapi/hikari/scripts/fcf/index /autoapi/hikari/scripts/hkl_completeness/index /autoapi/hikari/scripts/hkl_potency/index /autoapi/hikari/scripts/r1_map/index Functions --------- .. autoapisummary:: hikari.scripts.potency_map hikari.scripts.potency_vs_dac_opening_angle hikari.scripts.potency_violin_plot hikari.scripts.dac_potency_around_axis hikari.scripts.completeness_statistics hikari.scripts.dac_statistics hikari.scripts.simulate_dac hikari.scripts.reformat_hkl hikari.scripts.animate_similarity_index hikari.scripts.calculate_similarity_indices hikari.scripts.r1_map Package Contents ---------------- .. py:function:: potency_map(a, b, c, al, be, ga, space_group='P1', axis='', fix_scale=False, histogram=True, opening_angle=35, orientation=None, path='~/sortav.lst', output_quality=3, resolution=1.2, wavelength='MoKa') Calculate and draw a potency map for a given crystal in diamond anvil cell (DAC) with a given opening angle, as a function of crystal orientation. For details see `this paper `_. The script accepts unit cell & space group information, and predicts max completeness of fully merged data for investigated crystal in said group. Results are logged into text files and drawn with gnuplot or matplotlib. Potency is calculated and visualised on a unit-sphere orientation heatmap. Each point **p** is associated with a certain crystal orientation in DAC, such that vector **v** from **0** to **p** acts as a symmetry axis for the dac-accessible volume traced in the reciprocal space up to `resolution`. Red / green / blue vectors represent crystallographic directions **X\***, **Y\*** and **Z\***, respectively. Since the distribution has some inherent symmetry, only a representative part of sphere (usually an octant) is shown. As an example, let's assume a orthorhombic cell with *a* = *b* = *c* = 10 and laue group "mmm". Running the script and generating the potency the map yields the lowest values close to **X\***, **Y\*** and **Z\*** vector, while the highest values are observed between those vectors. Placing the crystal on its [100] face inside the dac will cause the dac-accessible plane to be placed perpendicularly to (100) direction in reciprocal space. Since the values close to **X\*** ((100) direction) are low, such a placement will allow us to collect data with low coverage. On the other hand, placing the crystal on its [111] face will cause the dac-accessible plane to be placed perpendicularly to (100) direction in reciprocal space. As on the sphere the values tend to rise the further we are from of **X\***, **Y\*** and **Z\***, we expect this crystal orientation to warrant a high completeness of collected data. The potency is calculated as a ratio of the number of unique reflections inside the DAC-accessible space to the number of unique reflections inside a reference sphere of a radius equal to `resolution`. Visualisation is performed using an extended rainbow heatmap, which utilises a wide color range to emphasize even small differences. Dy default, the color scale is dynamic and adapts to the range of calculated potency, but it can be fixed to 0-100% range using `fix_scale=True`. Since the orientation is given in spherical coordinates, the exact positions of individual points is given using *theta* and *phi* angles instead of crystallographic coordinates. The *theta* and *phi* angles here follow the physical definition (ISO 80000-2:2019). For a given DAC-axis vector **v**: - *theta* is the azimuth angle found between vector **Z\*** and **v**. It can assume values between zero and *pi* (*pi/2* in one octant). - *phi* is the rotational angle denoting rotation of **v** around **Z\***. It can assume values between zero and *2 pi* (*pi/2* in one octant). Finally it must be noted that higher potency setting is not always better. For example, for opening angle below 45 degrees, most potent orientation in laue class mmm renders all 0kl, h0l, hk0 reflections inaccessible. Potency map should be consulted before a high-pressure experiment, but it should not be treated as an universal quality indicator of given set-up. :param a: Unit cell parameter *a* in Angstrom. :type a: float :param b: Unit cell parameter *b* in Angstrom. :type b: float :param c: Unit cell parameter *c* in Angstrom. :type c: float :param al: Unit cell parameter *alpha* in degrees. :type al: float :param be: Unit cell parameter *alpha* in degrees. :type be: float :param ga: Unit cell parameter *alpha* in degrees. :type ga: float :param space_group: Short Hermann-Mauguin name or index of space group. For details see :py:mod:`hikari.symmetry.space_groups`. :type space_group: str or int :param axis: domain to calculate potency in. Accepts 'x'/ 'y'/ 'z' for h00/ 0k0/ 00l, 'xy'/'xz'/'yz' for hk0/ h0l/ 0kl, or '' for all reflections. :type axis: string :param fix_scale: If true, the colour scheme will fix to 0 - 100% range. :type fix_scale: bool :param histogram: If true, potency distribution will be plotted as histogram :type histogram: bool :param opening_angle: Value of single opening angle as defined in :meth:`hikari.dataframes.HklFrame.dac`. :type opening_angle: float :param orientation: either a cif-style 3x3 matrix of crystal orientation or a 3-length array with a diamond-perpendicular face to be marked on a map :type orientation: np.ndarray :param path: Path to a file where script is to be run. Extension is ignored, but file name will and must be the same for all input and output files. :type path: str :param output_quality: Density of individual orientations to be considered. Should be in range from 1 (every 15 degrees) to 5 (every 1 degree). :type output_quality: int :param resolution: Upper limit of reflection resolution, given as a distance from zero to node in reciprocal space (one over plane spacing) in A-1. :type resolution: float :param wavelength: Wavelength of radiation to be simulated. :type wavelength: float or str :return: None :rtype: None .. py:function:: potency_vs_dac_opening_angle(output_path='~/output.txt', precision=91, resolution=1.2, wavelength='MoKa', theta=None) Calculate potency in P1 space group as a function of DAC opening angle, assuming certain resolution and wavelength used. :param output_path: Path of created file containing calculated data. :type output_path: str :param precision: Number of probed opening angles between 0 and 90 degrees. :type precision: int :param resolution: Maximum distance from the origin in reciprocal space to reflection (twice the resolution in reciprocal angstrom). Default 1.2. :type resolution: float :param wavelength: Wavelength of radiation to be simulated. :type wavelength: float or str :param theta: If given, use max theta in degrees (instead of radius in A-1). :type theta: float :return: None .. py:function:: potency_violin_plot(job_name='violin', directory='~', opening_angle=35, precision=1000, space_groups=laue_space_groups, labels=laue_class_names, resolution=None, wavelength='MoKa') Calculate potency distribution for selected space groups and multiple sample orientations in a DAC, log it, and (re)draw appropriate violin plot. :param job_name: Base name for created files, defaults to 'violin'. If a .csv file with this name already exists, redraw instead of calculating. :type job_name: str :param directory: Target directory for saving or reading, defaults to '~'. :type directory: str :param opening_angle: Value of single opening angle as defined in :meth:`hikari.dataframes.HklFrame.dac`. Defaults to 35. :type opening_angle: float :param precision: Number of orientations to investigate, defaults to 1000. :type precision: int :param space_groups: List of space groups to investigate, strings or ints (see :class:`hikari.symmetry.Group`). Defaults to 11 "Laue" groups. :type space_groups: tuple[int] or tuple[str] :param labels: List of tex-style labels to be used for logging and plotting. :type labels: tuple[str] :param resolution: If given, additionally limit data resolution to given value. Please provide the resolution as a distance from the origin in reciprocal space (twice the resolution in reciprocal angstrom). :type resolution: float :param wavelength: Wavelength of radiation to be simulated. :type wavelength: float or str :return: None :rtype: None .. py:function:: dac_potency_around_axis(a, b, c, al, be, ga, space_group='P1', opening_angle=35.0, wavelength='MoKa', vector=(1, 0, 0), topple_angle=5) For a given crystal, opening angle, and wavelength calculate average potency obtained by toppling the crystal by "topple_angle"° from the "vector" axis. :param a: Unit cell parameter *a* in Angstrom. :type a: float :param b: Unit cell parameter *b* in Angstrom. :type b: float :param c: Unit cell parameter *c* in Angstrom. :type c: float :param al: Unit cell parameter *alpha* in degrees. :type al: float :param be: Unit cell parameter *beta* in degrees. :type be: float :param ga: Unit cell parameter *gamma* in degrees. :type ga: float :param space_group: Short Hermann-Mauguin name or index of space group. For details see :py:mod:`hikari.symmetry.space_groups`. :type space_group: str or int :param wavelength: Wavelength of radiation utilised in experiment. :type wavelength: float or str :param opening_angle: Value of single opening angle as defined in :meth:`hikari.dataframes.HklFrame.dac`. :type opening_angle: float :param vector: Direction from which a theoretical crystal will be toppled. :type vector: tuple :param topple_angle: Angle by which theoretical crystal will be toppled. :type topple_angle: float :return: None .. py:function:: completeness_statistics(a, b, c, al, be, ga, space_group='P-1', input_path='shelx.hkl', input_format='shelx_4', input_wavelength='CuKa') For a given experimental .hkl file calculate basic completeness statistics in ten resolution shells of equal-volume. :param a: Unit cell parameter *a* in Angstrom. :type a: float :param b: Unit cell parameter *b* in Angstrom. :type b: float :param c: Unit cell parameter *c* in Angstrom. :type c: float :param al: Unit cell parameter *alpha* in degrees. :type al: float :param be: Unit cell parameter *alpha* in degrees. :type be: float :param ga: Unit cell parameter *alpha* in degrees. :type ga: float :param space_group: Short Hermann-Mauguin name or index of space group. For details see table in hikari.symmetry.space_groups. :type space_group: str or int :param input_path: Path to the input .hkl file. :type input_path: str :param input_format: Format of the .hkl file. For reference see :meth:`hikari.dataframes.HklFrame.interpret_hkl_format`. :type input_format: str or dict :param input_wavelength: Wavelength of radiation utilised in experiment. :type input_wavelength: float or str :return: None :rtype: None .. py:function:: dac_statistics(a, b, c, al, be, ga, space_group='P1', opening_angle=35.0, orientation=((1, 0, 0), (0, 1, 0), (0, 0, 1)), input_path='shelx.hkl', input_format=4, input_wavelength='CuKa', resolution=None) For a given experimental .hkl file calculate number of experimentally found and theoretically possible reflections up to a given resolution. :param a: Unit cell parameter *a* in Angstrom. :type a: float :param b: Unit cell parameter *b* in Angstrom. :type b: float :param c: Unit cell parameter *c* in Angstrom. :type c: float :param al: Unit cell parameter *alpha* in degrees. :type al: float :param be: Unit cell parameter *alpha* in degrees. :type be: float :param ga: Unit cell parameter *alpha* in degrees. :type ga: float :param space_group: Short Hermann-Mauguin name or index of space group. For details see table in hikari.symmetry.space_groups. :type space_group: str or int :param opening_angle: Value of single opening angle as defined in :py:meth:`hikari.dataframes.HklFrame.dac`. :type opening_angle: float :param orientation: Crystal orientation as defined in :py:class:`hikari.dataframes.BaseFrame` :type orientation: tuple or numpy.array :param input_path: Path to the input .hkl file. :type input_path: str :param input_format: Format of the .hkl file. For reference see :py:meth:`hikari.dataframes.HklFrame.interpret_hkl_format`. :type input_format: int or str or dict :param input_wavelength: Wavelength of radiation utilised in experiment. :type input_wavelength: float or str :param resolution: If given, calculate statistics only up to this value. Please provide it as a distance in rec. space (twice the resolution in A-1). :type resolution: float :return: None .. py:function:: simulate_dac(a, b, c, al, be, ga, opening_angle=35, orientation=((1, 0, 0), (0, 1, 0), (0, 0, 1)), vector=None, resolution=None, input_path='shelx.hkl', input_format=4, input_wavelength='CuKa', output_path='output.hkl', output_format=4) For a given experimental .hkl file simulate a lack of completeness caused by a presence of high-pressure diamond anvil cell. :param a: Unit cell parameter *a* in Angstrom. :type a: float :param b: Unit cell parameter *b* in Angstrom. :type b: float :param c: Unit cell parameter *c* in Angstrom. :type c: float :param al: Unit cell parameter *alpha* in degrees. :type al: float :param be: Unit cell parameter *alpha* in degrees. :type be: float :param ga: Unit cell parameter *alpha* in degrees. :type ga: float :param opening_angle: Value of single opening angle as defined in :meth:`hikari.dataframes.HklFrame.dac`. :type opening_angle: float :param orientation: Crystal orientation as defined in :class:`hikari.dataframes.BaseFrame` :type orientation: tuple or numpy.array :param vector: If given, overwrite orientation to provide information about crystal placement in dac, as defined in :meth:`hikari.dataframes.HklFrame.dac`. :type vector: tuple :param resolution: If given, additionally limit data resolution to given value. Please provide the resolution as a distance from the origin in reciprocal space (twice the resolution in reciprocal angstrom). :type resolution: float :param input_path: Path to the input .hkl file. :type input_path: str :param input_format: Format of the input .hkl file. For reference see :meth:`hikari.dataframes.HklFrame.interpret_hkl_format`. :type input_format: int or str or dict :param input_wavelength: Wavelength of radiation utilised in experiment. :type input_wavelength: float or str :param output_path: Path to the output .hkl file. :type output_path: str :param output_format: Format of the input .hkl file. For reference see :meth:`hikari.dataframes.HklFrame.interpret_hkl_format`. :type output_format: int or str or dict :return: None .. py:function:: reformat_hkl(input_path, input_format, output_path, output_format) :param input_path: Relative or absolute path to the input .hkl file. :param input_format: Format of the .hkl file. For reference see :attr:`hikari.dataframes.HklIo.format`. :param output_path: Relative or absolute path to the output .hkl file. :param output_format: Format of the .hkl file. For reference see :attr:`hikari.dataframes.HklIo.format`. :return: :rtype: .. py:function:: animate_similarity_index(u_diag, transformations, output_path) Make a gif presenting the change of similarity index against some arbitrary series of `transformations`. Initial displacement matrix must be diagonal, values given in `u_diag`, evaluated against a regular unit cell with a = 1. :param u_diag: triplet of u matrix diagonal elements :param transformations: list of transformations to be plotted every 0.1 sec :param output_path: path where resulting gif file will be saved .. py:function:: calculate_similarity_indices(cif1_path, cif2_path = None, cif1_block = None, cif2_block = None, output_path = None, normalize = False, uncertainties = True) Compare Anisotropic Displacement Parameters of all atoms in two cif blocks and return a Similarity Index (SI) for these pairs of atoms that exist and are defined anisotropic (via "_atom_site_aniso_U_**") in both files. This script requires two independent cif blocks to run, but the location of both blocks can be specified in multiple ways: - If only `cif1_path` is given, the first and second data block from cif1 file will be used in SI evaluation; - If `cif1_path` and `cif2_path` are given, the first data block from each cif file will be used instead; - If `cif1_path`, `cif2_path`, and `cif1_block` are given, `cif1_block` from each `cif1_path` and `cif2_path` cif files will be used. - If `cif1_path`, `cif2_path`, `cif1_block`, and `cif2_block` are given, `cif1_block` in `cif1_path` and `cif2_block` in `cif2_path` will be used. For a single cif file 'glycine.cif' with two data blocks named '100K' and 'RT', the three following commands will have the same effect: :Example: >>> calculate_similarity_indices('glycine.cif') >>> calculate_similarity_indices('glycine.cif', 'glycine.cif') >>> calculate_similarity_indices('glycine.cif', 'glycine.cif', '100K', 'RT') For two cif files 'X-rays.cif' and 'neutrons.cif' with data block named 'RT' and '100K' (one each), the two following commands will have the same effect: :Example: >>> calculate_similarity_indices('X-rays.cif', 'neutrons.cif') >>> calculate_similarity_indices('X-rays.cif', 'neutrons.cif', 'RT', '100K') The behaviour of script can be further altered via other parameters. If `output_file` is set True, the results will be written there instead of console. If `uncertainties` is set True, standard deviations of all ADPs as well as the unit cell parameters from 1st cif file will be assumed uncorrelated and used to estimate the uncertainty of every SI determination. For more information about Similarity Index (SI) itself, please consult Whitten and Spackman, Acta Cryst B **62**, 875 (2006) https://doi.org/10.1107/S0108768106020787. :param cif1_path: Absolute or relative path to the first cif file. :param cif2_path: Absolute or relative path to the second cif file. If not specified, it is assumed equal to `cif1_path`. :param cif1_block: Name of the first data block used in SI determination. It points to the data block inside the file specified by `cif1_path`. If not specified, the first block found in said file will be used. :param cif2_block: Name of the second data block used in SI determination. It points to the data block inside the file specified by `cif2_path`. If not specified, the first unused block in said file will be used. :param output_path: Path where the output of the program should be written. :param uncertainties: If True, propagate the standard deviations of individual ADPs' and cif1's unit cell to estimate SI's uncertainties. :param normalize: If True, equalize the volume of displacement ellipsoids by normalizing the determinants of ADP matrices expressed in cartesian coordinates. As a result, SI is a function of displacement "shape" only. .. py:function:: r1_map(a, b, c, al, be, ga, space_group='P1', axis='', fix_scale=False, histogram=True, opening_angle=35, orientation=None, path='~/sortav.lst', output_quality=3, resolution=1.2, wavelength='MoKa') Calculate and draw a r1 map for a given crystal in diamond anvil cell (DAC) with a given opening angle, as a function of crystal orientation. The script accepts unit cell & space group information, runs SHELXL, and reads value of R1 after single refinement. Results are logged into text files and drawn with gnuplot or matplotlib, depending on settings. For further detail concerning r1_map, its basis and uses, refer to :py:func:`hikari.scripts.potency_map`, as well as selected terminology described in `this paper `_.