Metadata-Version: 2.3
Name: bblib
Version: 3.0.0
Summary: beambusters library to refine the detector center for crystallography data processing.
License: GNU
Author: Ana Rodrigues
Author-email: ana.rodrigues@desy.de
Requires-Python: >=3.10,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: abstract (==2022.7.10)
Requires-Dist: base32hex (==1.0.2)
Requires-Dist: black (==24.1.1)
Requires-Dist: build (==1.0.3)
Requires-Dist: cachecontrol (==0.14.0)
Requires-Dist: certifi (==2024.2.2)
Requires-Dist: cffi (==1.16.0)
Requires-Dist: charset-normalizer (==3.3.2)
Requires-Dist: cleo (==2.1.0)
Requires-Dist: click (==8.1.7)
Requires-Dist: colouration (==2020.7.26)
Requires-Dist: contourpy (==1.2.0)
Requires-Dist: crashtest (==0.4.1)
Requires-Dist: cryptography (==42.0.5)
Requires-Dist: cycler (==0.12.1)
Requires-Dist: cython (==3.0.8)
Requires-Dist: distlib (==0.3.8)
Requires-Dist: dulwich (==0.21.7)
Requires-Dist: fabio (==2023.10.0)
Requires-Dist: fastjsonschema (==2.19.1)
Requires-Dist: filelock (==3.13.1)
Requires-Dist: fonttools (==4.48.1)
Requires-Dist: graphviz (==0.20.1)
Requires-Dist: h5py (==3.10.0)
Requires-Dist: hdf5plugin (==4.4.0)
Requires-Dist: idna (==3.6)
Requires-Dist: imageio (==2.33.1)
Requires-Dist: importlib-metadata (==7.0.1)
Requires-Dist: installer (==0.7.0)
Requires-Dist: jaraco-classes (==3.3.1)
Requires-Dist: jeepney (==0.8.0)
Requires-Dist: keyring (==24.3.0)
Requires-Dist: kiwisolver (==1.4.5)
Requires-Dist: lazy-loader (==0.3)
Requires-Dist: llvmlite (==0.44.0)
Requires-Dist: lxml (==5.1.0)
Requires-Dist: markdown-it-py (==3.0.0)
Requires-Dist: matplotlib (==3.8.2)
Requires-Dist: mdurl (==0.1.2)
Requires-Dist: more-itertools (==10.2.0)
Requires-Dist: msgpack-numpy (==0.4.8)
Requires-Dist: mypy-extensions (==1.0.0)
Requires-Dist: networkx (==3.2.1)
Requires-Dist: numba (>=0.61.2,<0.62.0)
Requires-Dist: numpy (==1.26.4)
Requires-Dist: ondamonitor (==23.8.3)
Requires-Dist: packaging (==23.2)
Requires-Dist: pandas (==2.2.0)
Requires-Dist: pathspec (==0.12.1)
Requires-Dist: pexpect (==4.9.0)
Requires-Dist: pillow (==10.2.0)
Requires-Dist: pkginfo (==1.9.6)
Requires-Dist: platformdirs (==4.2.0)
Requires-Dist: poetry (==1.8.0)
Requires-Dist: poetry-core (==1.9.0)
Requires-Dist: poetry-plugin-export (==1.6.0)
Requires-Dist: ptyprocess (==0.7.0)
Requires-Dist: pycparser (==2.21)
Requires-Dist: pygments (==2.17.2)
Requires-Dist: pyparsing (==3.1.1)
Requires-Dist: pyproject-hooks (==1.0.0)
Requires-Dist: python-dateutil (==2.8.2)
Requires-Dist: pytz (==2024.1)
Requires-Dist: pyyaml (==6.0.1)
Requires-Dist: pyzmq (==25.1.2)
Requires-Dist: rapidfuzz (==3.6.1)
Requires-Dist: requests (==2.31.0)
Requires-Dist: requests-toolbelt (==1.0.0)
Requires-Dist: rich (==13.7.0)
Requires-Dist: ruamel-yaml (==0.18.6)
Requires-Dist: ruamel-yaml-clib (==0.2.8)
Requires-Dist: scikit-image (==0.22.0)
Requires-Dist: scipy (==1.12.0)
Requires-Dist: secretstorage (==3.3.3)
Requires-Dist: shellingham (==1.5.4)
Requires-Dist: six (==1.16.0)
Requires-Dist: tifffile (==2024.2.12)
Requires-Dist: tomli (==2.0.1)
Requires-Dist: tomlkit (==0.12.3)
Requires-Dist: trove-classifiers (==2024.2.23)
Requires-Dist: typing-extensions (==4.10.0)
Requires-Dist: tzdata (==2024.1)
Requires-Dist: urllib3 (==2.2.1)
Requires-Dist: virtualenv (==20.25.1)
Requires-Dist: zipp (==3.17.0)
Description-Content-Type: text/markdown

# beambusters library

[![PyPI pyversions](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/release/python-3100/)

The beambusters library (bblib) is a library that contains methods to determine the detector center directly from still diffraction patterns collected in serial crystallography experiments.

## Installation

To install bblib, run the following command in a terminal:

```bash
pip install bblib
```

## Usage

### Configuration dictionaries

To utilize the methods `CenterOfMass`,  `FriedelPairs`, `MinimizePeakFWHM`  and `CircleDetection` it is required to have two configuration dictionaries, one for PeakFinder8 and another one for this library itself. The following snippet shows the general structure for both (parameters not used in your case can be omitted):

```python
config = {
    "plots_flag": ...,
	"search_radius": ...,
	"pf8": {
		"max_num_peaks": ...,
		"adc_threshold": ...,
		"minimum_snr": ...,
		"min_pixel_count": ...,
		"max_pixel_count": ...,
		"local_bg_radius": ...,
		"min_res": ...,
		"max_res": ...
		},
	"peak_region":{
		"min": ...,
		"max": ...
		},
	"grid_search_radius": ...,
	"canny":{
		"sigma": ...,
		"low_threshold": ...,
		"high_threshold": ...
		},
	"hough_rank": ...,
	"bragg_peaks_for_center_of_mass_calculation": ...,
	"pixels_for_mask_of_bragg_peaks": ...,
	"polarization": {
		"apply_polarization_correction": ...,
		"axis": ...,
		"value": ...
		}
}

PF8Info = {
	"max_num_peaks":
	"adc_threshold":
	"minimum_snr": ...,
	"min_pixel_count": ...,
	"max_pixel_count": ...,
	"local_bg_radius": ...,
	"min_res": ...,
	"max_res": ...,
	"pf8_detector_info": ...,
	"bad_pixel_map_filename": ...,
	"bad_pixel_map_hdf5_path": ...,
	"pixel_maps": ...,
	"pixel_resolution": ...,
	"_shifted_pixel_maps":...
}
```

The `pf8_detector_info` parameter is a dictionary containing the detector layout information:
```python
pf8_detector_info =  {
	"asic_nx": ...,
	"asic_ny": ...,
	"nasics_x": ...,
	"nasics_y": ...
}
```

The `pixel_maps` parameter is a dictionary containing the pixel maps numpy array:
```python
pixel_maps =  {
	"x": ...,
	"y": ...,
	"z": ...,
	"radius": ...,
	"phi": ...
}
```

The methods `FriedelPairs`, `MinimizePeakFWHM` and  `CircleDetection ` need a `plots_info` parameter if you want to save plots:
```python
plots_info =  {
	"filename": ...,
	"folder_name": ...,
	"root_path": ...,
	"value_auto": ...,
	"value_max": ...,
	"value_min": ...,
	"axis_lim_auto": ...,
	"xlim_min": ...,
	"xlim_max": ...,
	"ylim_min": ...,
	"ylim_max": ...,
	"color_map": ...,
	"marker_size": ...
}
```

### Calling the methods

To calculate the refined detector center of raw data frame as a numpy array using the following methods:

```python
from bblib.methods import CenterOfMass
center_of_mass_method = CenterOfMass(config=config, PF8Config=PF8Config, plots_info=plots_info)
center_coordinates_from_center_of_mass = center_of_mass_method(
                        data = ...
                    )

from bblib.methods import CircleDetection
circle_detection_method = CircleDetection(config=config, PF8Config=PF8Config, plots_info=plots_info)
center_coordinates_from_circle_detection = circle_detection_method(
                        data = ...
                    )
```

The `FriedelPairs` and `MinimizePeakFWHMmethod` need an initial guess for the refined detector center coordinates ` initial_guess = [x_0, y_0]`

```python
from bblib.methods import MinimizePeakFWHM
minimize_peak_fwhm_method = MinimizePeakFWHM(
                        config=config, PF8Config=PF8Config, plots_info=plots_info
                    )
center_coordinates_from_minimize_peak_fwhm = minimize_peak_fwhm_method(
                        data = ..., initial_guess = ...
                    )


from bblib.methods import FriedelPairs
friedel_pairs_method = FriedelPairs(
                        config=config, PF8Config=PF8Config, plots_info=plots_info
                    )
center_coordinates_from_friedel_pairs = friedel_pairs_method(
                        data = ..., initial_guess= ...
                    )
```

## Contact

Ana Carolina Rodrigues led the development of bblib from 2021 to 2025 at the Deutsches Elektronen-Synchrotron (DESY) in Hamburg, Germany.

For questions, please contact:

**Email**: sc.anarodrigues@gmail.com

