# meerkat
A python library for performing reciprocal space reconstruction from single crystal x-ray measurements.
## Installation
The package can be installed using pip:
pip install meerkat
On Windows we recommend to use virtual environments like [anaconda](https://store.continuum.io/cshop/anaconda/) which simplify python installation.
#### Note for anaconda users
Some anaconda distributions fail on `pip install meerkat` while trying to compile `h5py`. In this case the following commands work:
```
pip install meerkat --no-deps
pip install fabio
```
Since anaconda comes with preinstalled `h5py` it is not required to reinstall it with pip, and the following command resolves all dependencies.
## Usage
The reciprocal space reconstruction is based on the orientation matrix determined by [XDS](“xds.mpimf-heidelberg.mpg.de”). Thus, in order to run the reconstruction, in addition to the diffraction frames, `meerkat` requires either `XPARM.XDS` or `GXPARM.XDS`.
The reconstruction can be run using the following python script:
```
from meerkat import reconstruct_data
#reconstruct dataset
reconstruct_data(filename_template='../frames/PdCPTN01002_%05i.cbf',
first_image=1,
last_image=3600,
reconstruct_in_orthonormal_basis=False,
maxind=[4,5,16], #the reconstruction will be made for h=-4...4, k=-5...5, l=-16...16
number_of_pixels=[801, 801, 801], #The resulting size of the array. Controls the step size
polarization_factor=0.5,
path_to_XPARM='/home/arkadiy/work/data/PdCPTN01002/xds',
output_filename='reconstruction.h5',
all_in_memory=False,
size_of_cache=100,
override=True,
scale=None) #Here you can provide a list of coefficients to scale each frame during reconstruction, for instance in a crystal which was unevenly illuminated during experiment, or the primary beam intensity was varying.
```
## Output
The result is saved as an [hdf5](“http://www.hdfgroup.org/HDF5/”) file. The reconstruction is held in two datasets: `rebinned_data` and `number_of_pixels_rebinned`, the former is a corrected sum of intensities of reconstructed pixels, while the latter counts how many pixels were reconstructed. The scattering intensity can be obtained by dividing the two: `rebinned_data[i,j,k]/number_of_pixels_rebinned[i,j,k]`.
In addition to the two datasets, the reconstruction file contains parameters of the reconstruction `maxind`, `number_of_pixels`, calculated `step_size`, and information from XDS files: `unit_cell`, `space_group_nr` and `metric_tensor`.
## Reconstruction coordinates
By default the reconstruction is performed in crystallographic coordinates. Such reconstructions can be easily symmetry-averaged. Also the numerical analysis of diffuse scattering is more straightforwardly performed in crystallographic coordinates (for example the program [Yell](“https://github.com/YellProgram/Yell/”) uses such coordinates).
The downside of the crystallographic coordinates is that they are in general not orthorombic, which makes the reconstructions in such coordinates slightly more complicated to plot. If the reconstructions are required in orthonormal coordinates, this can be achieved by setting:
reconstruct_in_orthonormal_basis=True
If the reconstruction is performed in orthonormal basis, the new basis a\*',b\*',c\*' is calculated from the crystal a\*,b\*,c\* vectors. In the new basis a'\* is parallel to a\*, the b'\* is in the plane spawned by a\* and b\*, and c'\* is orthogonal to a'\* and b'\*.
## Memory usage
The three dimensional arrays containing the reconstructed reciprocal space are typically large (~10Gb). We appreciate that not all computers might have enough operating memory to hold this datasets. Thanks to the `hdf5`, it is possible to use large arrays hosted on hard drive. In such case, only a small portion of the array will be cached in the operating memory. In order to turn on caching set parameter `all_in_memory` to `False` and define the size of the memory for cache.
all_in_memory = False
Such scheme is approximately three times slower, than holding all datasets in memory.
Raw data
{
"_id": null,
"home_page": null,
"name": "meerkat",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "crystallography, single crystal, reciprocal space reconstruction",
"author": "Dmitry Logvinovich",
"author_email": "Arkadiy Simonov <aglietto@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c8/0f/686e574a01ded0183475c64634ba9f802c948bc39fabfbdea791d7054d84/meerkat-0.3.9.tar.gz",
"platform": null,
"description": "# meerkat\nA python library for performing reciprocal space reconstruction from single crystal x-ray measurements. \n\n## Installation\nThe package can be installed using pip:\n\n pip install meerkat\n \nOn Windows we recommend to use virtual environments like [anaconda](https://store.continuum.io/cshop/anaconda/) which simplify python installation. \n\n#### Note for anaconda users\n\nSome anaconda distributions fail on `pip install meerkat` while trying to compile `h5py`. In this case the following commands work:\n\n```\npip install meerkat --no-deps\npip install fabio\n```\n\nSince anaconda comes with preinstalled `h5py` it is not required to reinstall it with pip, and the following command resolves all dependencies.\n\n## Usage\n\nThe reciprocal space reconstruction is based on the orientation matrix determined by [XDS](\u201cxds.mpimf-heidelberg.mpg.de\u201d). Thus, in order to run the reconstruction, in addition to the diffraction frames, `meerkat` requires either `XPARM.XDS` or `GXPARM.XDS`.\n\nThe reconstruction can be run using the following python script:\n\n```\nfrom meerkat import reconstruct_data\n\n#reconstruct dataset\nreconstruct_data(filename_template='../frames/PdCPTN01002_%05i.cbf',\n first_image=1,\n last_image=3600,\n reconstruct_in_orthonormal_basis=False,\n maxind=[4,5,16], #the reconstruction will be made for h=-4...4, k=-5...5, l=-16...16\n number_of_pixels=[801, 801, 801], #The resulting size of the array. Controls the step size\n polarization_factor=0.5,\n path_to_XPARM='/home/arkadiy/work/data/PdCPTN01002/xds',\n output_filename='reconstruction.h5',\n all_in_memory=False,\n size_of_cache=100,\n override=True,\n scale=None) #Here you can provide a list of coefficients to scale each frame during reconstruction, for instance in a crystal which was unevenly illuminated during experiment, or the primary beam intensity was varying.\n```\n\n## Output\nThe result is saved as an [hdf5](\u201chttp://www.hdfgroup.org/HDF5/\u201d) file. The reconstruction is held in two datasets: `rebinned_data` and `number_of_pixels_rebinned`, the former is a corrected sum of intensities of reconstructed pixels, while the latter counts how many pixels were reconstructed. The scattering intensity can be obtained by dividing the two: `rebinned_data[i,j,k]/number_of_pixels_rebinned[i,j,k]`.\n\nIn addition to the two datasets, the reconstruction file contains parameters of the reconstruction `maxind`, `number_of_pixels`, calculated `step_size`, and information from XDS files: `unit_cell`, `space_group_nr` and `metric_tensor`.\n\n## Reconstruction coordinates\n\nBy default the reconstruction is performed in crystallographic coordinates. Such reconstructions can be easily symmetry-averaged. Also the numerical analysis of diffuse scattering is more straightforwardly performed in crystallographic coordinates (for example the program [Yell](\u201chttps://github.com/YellProgram/Yell/\u201d) uses such coordinates).\n\nThe downside of the crystallographic coordinates is that they are in general not orthorombic, which makes the reconstructions in such coordinates slightly more complicated to plot. If the reconstructions are required in orthonormal coordinates, this can be achieved by setting: \n\n reconstruct_in_orthonormal_basis=True\n\nIf the reconstruction is performed in orthonormal basis, the new basis a\\*',b\\*',c\\*' is calculated from the crystal a\\*,b\\*,c\\* vectors. In the new basis a'\\* is parallel to a\\*, the b'\\* is in the plane spawned by a\\* and b\\*, and c'\\* is orthogonal to a'\\* and b'\\*.\n\n## Memory usage\nThe three dimensional arrays containing the reconstructed reciprocal space are typically large (~10Gb). We appreciate that not all computers might have enough operating memory to hold this datasets. Thanks to the `hdf5`, it is possible to use large arrays hosted on hard drive. In such case, only a small portion of the array will be cached in the operating memory. In order to turn on caching set parameter `all_in_memory` to `False` and define the size of the memory for cache.\n\n all_in_memory = False\n\nSuch scheme is approximately three times slower, than holding all datasets in memory.\n",
"bugtrack_url": null,
"license": null,
"summary": "A program for reciprocal space reconstruction",
"version": "0.3.9",
"project_urls": {
"Homepage": "https://github.com/aglie/meerkat.git"
},
"split_keywords": [
"crystallography",
" single crystal",
" reciprocal space reconstruction"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "913a736fcaf9cce3dfef32279a122f4377e5d1533c7d2209106e3ee297061d5f",
"md5": "62de64980e99179c687e310faf88a34b",
"sha256": "f3bec5faf857f1bd41cb41d09f33faac3e9b31d23a8088c5431c2b881f73d357"
},
"downloads": -1,
"filename": "meerkat-0.3.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62de64980e99179c687e310faf88a34b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12830,
"upload_time": "2024-08-30T15:08:02",
"upload_time_iso_8601": "2024-08-30T15:08:02.464304Z",
"url": "https://files.pythonhosted.org/packages/91/3a/736fcaf9cce3dfef32279a122f4377e5d1533c7d2209106e3ee297061d5f/meerkat-0.3.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c80f686e574a01ded0183475c64634ba9f802c948bc39fabfbdea791d7054d84",
"md5": "c793259e14e4e5622d49fcdae4344025",
"sha256": "b66f7be5b8dc4d52d79c5295b52775e7f2233aa75adfe3ab33fd57a0f197c5f2"
},
"downloads": -1,
"filename": "meerkat-0.3.9.tar.gz",
"has_sig": false,
"md5_digest": "c793259e14e4e5622d49fcdae4344025",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14015,
"upload_time": "2024-08-30T15:08:03",
"upload_time_iso_8601": "2024-08-30T15:08:03.666430Z",
"url": "https://files.pythonhosted.org/packages/c8/0f/686e574a01ded0183475c64634ba9f802c948bc39fabfbdea791d7054d84/meerkat-0.3.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-30 15:08:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aglie",
"github_project": "meerkat",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "meerkat"
}
JSON
