`pyFAI` Package¶

pyFAI.__init__.benchmarks(*arg, **kwarg)¶

Run the integrated benchmarks.

See the documentation of pyFAI.benchmark.run_benchmark

pyFAI.__init__.tests(deprecation=False)¶

Runs the test suite of the installed version

Parameters:	deprecation – enable/disables deprecation warning in the tests

`average` Module¶

Utilities, mainly for image treatment

exception pyFAI.average.AlgorithmCreationError¶

Bases: exceptions.RuntimeError

Exception returned if creation of an ImageReductionFilter is not possible

class pyFAI.average.Average¶

Bases: object

Process images to generate an average using different algorithms.

__init__()¶: Constructor

add_algorithm(algorithm)¶

Defines another algorithm which will be computed on the source.

Parameters:	algorithm (ImageReductionFilter) – An averaging algorithm.

get_counter_frames()¶

Returns the number of frames used for the process.

Return type:	int

get_fabio_images()¶

Returns source images as fabio images.

Return type:	list(fabio.fabioimage.FabioImage)

get_image_reduction(algorithm)¶

Returns the result of an algorithm. The process must be already done.

Parameters:	algorithm (ImageReductionFilter) – An averaging algorithm
Return type:	numpy.ndarray

process()¶: Process source images to all defined averaging algorithms defined using defined parameters. To access to the results you have to define a writer (AverageWriter). To follow the process forward you have to define an observer (AverageObserver).

set_correct_flat_from_dark(correct_flat_from_dark)¶

Defines if the dark must be applied on the flat.

Parameters:	correct_flat_from_dark (bool) – If true, the dark is applied.

set_dark(dark_list)¶

Defines images used as dark.

Parameters:	dark_list (list) – List of dark used

set_flat(flat_list)¶

Defines images used as flat.

Parameters:	flat_list (list) – List of dark used

set_images(image_list)¶

Defines the set set of source images to used to process an average.

Parameters:	image_list (list) – List of filename, numpy arrays, fabio images used as source for the computation.

set_monitor_name(monitor_name)¶

Defines the monitor name used to correct images before processing the average. This monitor must be part of the file header, else the image is skipped.

Parameters:	monitor_name (str) – Name of the monitor available on the header file

set_observer(observer)¶

Set an observer to the average process.

Parameters:	observer (AverageObserver) – An observer

set_pixel_filter(threshold, minimum, maximum)¶

Defines the filter applied on each pixels of the images before processing the average.

Parameters:	threshold – what is the upper limit? all pixel > max(1-threshold) are discareded. minimum* – minimum valid value or True maximum – maximum valid value

set_writer(writer)¶

Defines the object write which will be used to store the result.

Parameters:	writer (AverageWriter) – The writer to use.

class pyFAI.average.AverageDarkFilter(filter_name, cut_off, quantiles)¶

Bases: pyFAI.average.ImageStackFilter

Filter based on the algorithm of average_dark

TODO: Must be split according to each filter_name, and removed

__init__(filter_name, cut_off, quantiles)¶

get_parameters()¶: Return a dictionary containing filter parameters

name¶

class pyFAI.average.AverageObserver¶

Bases: object

algorithm_finished(algorithm)¶: Called when an algorithm is finished

algorithm_started(algorithm)¶: Called when an algorithm is started

frame_processed(algorithm, frame_index, frames_count)¶: Called after providing a frame to an algorithm

image_loaded(fabio_image, image_index, images_count)¶: Called when an input image is loaded

process_finished()¶: Called when the full process is finished

process_started()¶: Called when the full processing is started

result_processing(algorithm)¶: Called before the result of an algorithm is computed

class pyFAI.average.AverageWriter¶

Interface for using writer in Average process.

close()¶: Close the writer. Must not be used anymore.

write_header(merged_files, nb_frames, monitor_name)¶

Write the header of the average

Parameters:	merged_files (list) – List of files used to generate this output nb_frames (int) – Number of frames used monitor_name (str) – Name of the monitor used. Can be None.

write_reduction(algorithm, data)¶

Write one reduction

Parameters:	algorithm (ImageReductionFilter) – Algorithm used data (object) – Data of this reduction

class pyFAI.average.ImageAccumulatorFilter¶

Bases: pyFAI.average.ImageReductionFilter

Filter applied in a set of images in which it is possible to reduce data step by step into a single merged image.

add_image(image)¶

Add an image to the filter.

Parameters:	image (numpy.ndarray) – image to add

get_result()¶

Get the result of the filter.

Returns:	result filter
Return type:	numpy.ndarray

init(max_images=None)¶

class pyFAI.average.ImageReductionFilter¶

Bases: object

Generic filter applied in a set of images.

add_image(image)¶

Add an image to the filter.

Parameters:	image (numpy.ndarray) – image to add

get_parameters()¶

Return a dictionary containing filter parameters

Return type:	dict

get_result()¶

Get the result of the filter.

Returns:	result filter

init(max_images=None)¶

Initialize the filter before using it.

Parameters:	max_images (int) – Max images supported by the filter

class pyFAI.average.ImageStackFilter¶

Bases: pyFAI.average.ImageReductionFilter

Filter creating a stack from all images and computing everything at the end.

add_image(image)¶

Add an image to the filter.

Parameters:	image (numpy.ndarray) – image to add

get_result()¶

init(max_images=None)¶

class pyFAI.average.MaxAveraging¶

Bases: pyFAI.average.ImageAccumulatorFilter

name = 'max'¶

class pyFAI.average.MeanAveraging¶

Bases: pyFAI.average.SumAveraging

get_result()¶

name = 'mean'¶

class pyFAI.average.MinAveraging¶

Bases: pyFAI.average.ImageAccumulatorFilter

name = 'min'¶

exception pyFAI.average.MonitorNotFound¶

Bases: exceptions.Exception

Raised when monitor information in not found or is not valid.

class pyFAI.average.MultiFilesAverageWriter(file_name_pattern, file_format, dry_run=False)¶

Bases: pyFAI.average.AverageWriter

Write reductions into multi files. File headers are duplicated.

__init__(file_name_pattern, file_format, dry_run=False)¶

Parameters:	file_name_pattern (str) – File name pattern for the output files. If it contains “{method_name}”, it is updated for each reduction writing with the name of the reduction. file_format (str) – File format used. It is the default extension file. dry_run (bool) – If dry_run, the file is created on memory but not saved on the file system at the end

close()¶: Close the writer. Must not be used anymore.

get_fabio_image(algorithm)¶

Get the constructed fabio image

Return type:	fabio.fabioimage.FabioImage

write_header(merged_files, nb_frames, monitor_name)¶

write_reduction(algorithm, data)¶

class pyFAI.average.SumAveraging¶

Bases: pyFAI.average.ImageAccumulatorFilter

name = 'sum'¶

pyFAI.average.average_dark(lstimg, center_method='mean', cutoff=None, quantiles=(0.5, 0.5))¶

Averages a serie of dark (or flat) images. Centers the result on the mean or the median ... but averages all frames within cutoff*std

Parameters:	lstimg – list of 2D images or a 3D stack center_method (str) – is the center calculated by a “mean”, “median”, “quantile”, “std” cutoff (float or None) – keep all data where (I-center)/std < cutoff quantiles (tuple(float, float) or None) – 2-tuple of floats average out data between the two quantiles
Returns:	2D image averaged

pyFAI.average.average_images(listImages, output=None, threshold=0.1, minimum=None, maximum=None, darks=None, flats=None, filter_='mean', correct_flat_from_dark=False, cutoff=None, quantiles=None, fformat='edf', monitor_key=None)¶

Takes a list of filenames and create an average frame discarding all: saturated pixels.

Parameters:

listImages – list of string representing the filenames
output – name of the optional output file
threshold – what is the upper limit? all pixel > max*(1-threshold) are discareded.
minimum – minimum valid value or True
maximum – maximum valid value
darks – list of dark current images for subtraction
flats – list of flat field images for division
filter – can be “min”, “max”, “median”, “mean”, “sum”, “quantiles” (default=’mean’)
correct_flat_from_dark – shall the flat be re-corrected ?
cutoff – keep all data where (I-center)/std < cutoff
quantiles – 2-tuple containing the lower and upper quantile (0<q<1) to average out.
fformat – file format of the output image, default: edf
str (monitor_key) – Key containing the monitor. Can be none.

Returns:

filename with the data or the data ndarray in case format=None

pyFAI.average.bounding_box(img)¶

Tries to guess the bounding box around a valid massif

Parameters:	img – 2D array like
Returns:	4-typle (d0_min, d1_min, d0_max, d1_max)

pyFAI.average.common_prefix(string_list)¶

Return the common prefix of a list of strings

TODO: move it into utils package

Parameters:	string_list (list(str)) – List of strings
Return type:	str

pyFAI.average.create_algorithm(filter_name, cut_off=None, quantiles=None)¶

Factory to create algorithm according to parameters

Parameters:	cutoff (float or None) – keep all data where (I-center)/std < cutoff quantiles (tuple(float, float) or None) – 2-tuple of floats average out data between the two quantiles
Returns:	An algorithm
Return type:	ImageReductionFilter
Raises:	AlgorithmCreationError – If it is not possible to create the algorithm

pyFAI.average.f¶: alias of SumAveraging

pyFAI.average.get_monitor_value(image, monitor_key)¶

Return the monitor value from an image using an header key.

Parameters:	image (fabio.fabioimage.FabioImage) – Image containing the header monitor_key (str) – Key containing the monitor
Returns:	returns the monitor else raise an exception
Return type:	float
Raises:	MonitorNotFound – when the expected monitor is not found on the header

pyFAI.average.is_algorithm_name_exists(filter_name)¶: Return true if the name is a name of a filter algorithm

pyFAI.average.remove_saturated_pixel(ds, threshold=0.1, minimum=None, maximum=None)¶

Remove saturated fixes from an array inplace.

Parameters:	ds – a dataset as ndarray threshold (float) – what is the upper limit? all pixel > max(1-threshold) are discareded. minimum* (float) – minumum valid value (or True for auto-guess) maximum (float) – maximum valid value
Returns:	the input dataset

`azimuthalIntegrator` Module¶

class pyFAI.azimuthalIntegrator.AzimuthalIntegrator(dist=1, poni1=0, poni2=0, rot1=0, rot2=0, rot3=0, pixel1=None, pixel2=None, splineFile=None, detector=None, wavelength=None)¶

Bases: pyFAI.geometry.Geometry

This class is an azimuthal integrator based on P. Boesecke’s geometry and histogram algorithm by Manolo S. del Rio and V.A Sole

All geometry calculation are done in the Geometry class

main methods are:

>>> tth, I = ai.integrate1d(data, npt, unit="2th_deg")
>>> q, I, sigma = ai.integrate1d(data, npt, unit="q_nm^-1", error_model="poisson")
>>> regrouped = ai.integrate2d(data, npt_rad, npt_azim, unit="q_nm^-1")[0]

DEFAULT_METHOD = 'splitbbox'¶

__init__(dist=1, poni1=0, poni2=0, rot1=0, rot2=0, rot3=0, pixel1=None, pixel2=None, splineFile=None, detector=None, wavelength=None)¶

Parameters:

dist (float) – distance sample - detector plan (orthogonal distance, not along the beam), in meter.
poni1 (float) – coordinate of the point of normal incidence along the detector’s first dimension, in meter
poni2 (float) – coordinate of the point of normal incidence along the detector’s second dimension, in meter
rot1 (float) – first rotation from sample ref to detector’s ref, in radians
rot2 (float) – second rotation from sample ref to detector’s ref, in radians
rot3 (float) – third rotation from sample ref to detector’s ref, in radians
pixel1 (float) – Deprecated. Pixel size of the fist dimension of the detector, in meter. If both pixel1 and pixel2 are not None, detector pixel size is overwritten. Prefer defining the detector pixel size on the provided detector object. Prefer defining the detector pixel size on the provided detector object (detector.pixel1 = 5e-6).
pixel2 (float) – Deprecated. Pixel size of the second dimension of the detector, in meter. If both pixel1 and pixel2 are not None, detector pixel size is overwritten. Prefer defining the detector pixel size on the provided detector object (detector.pixel2 = 5e-6).
splineFile (str) – Deprecated. File containing the geometric distortion of the detector. If not None, pixel1 and pixel2 are ignored and detector spline is overwritten. Prefer defining the detector spline manually (detector.splineFile = "file.spline").
detector (str or pyFAI.Detector) – name of the detector or Detector instance. String description is deprecated. Prefer using the result of the detector factory: pyFAI.detector_factory("eiger4m")
wavelength (float) – Wave length used in meter

create_mask(data, mask=None, dummy=None, delta_dummy=None, mode='normal')¶

Combines various masks into another one.

Parameters:	data (ndarray) – input array of data mask (ndarray) – input mask (if none, self.mask is used) dummy (float) – value of dead pixels delta_dumy – precision of dummy pixels mode (str) – can be “normal” or “numpy” (inverted) or “where” applied to the mask
Returns:	the new mask
Return type:	ndarray of bool

This method combine two masks (dynamic mask from data & dummy and mask) to generate a new one with the ‘or’ binary operation. One can adjust the level, with the dummy and the delta_dummy parameter, when you consider the data values needs to be masked out.

This method can work in two different mode:

“normal”: False for valid pixels, True for bad pixels

“numpy”: True for valid pixels, false for others

This method tries to accomodate various types of masks (like valid=0 & masked=-1, ...) and guesses if an input mask needs to be inverted.

dark_correction(data, dark=None)¶

Correct for Dark-current effects. If dark is not defined, correct for a dark set by “set_darkfiles”

Parameters:	data – input ndarray with the image dark – ndarray with dark noise or None
Returns:	2tuple: corrected_data, dark_actually used (or None)

darkcurrent¶

darkfiles¶

empty¶

flat_correction(data, flat=None)¶

Correct for flat field. If flat is not defined, correct for a flat set by “set_flatfiles”

Parameters:	data – input ndarray with the image flat – ndarray with flatfield or None for no correction
Returns:	2tuple: corrected_data, flat_actually used (or None)

flatfield¶

flatfiles¶

get_darkcurrent()¶

get_empty()¶

get_flatfield()¶

inpainting(data, mask, npt_rad=1024, npt_azim=512, unit='r_m', method='splitpixel', poissonian=False, grow_mask=3)¶

Re-invent the values of masked pixels

Parameters:

data – input image as 2d numpy array
mask – masked out pixels array
npt_rad – number of radial points
npt_azim – number of azimuthal points
unit – unit to be used for integration
method – pathway for integration
poissonian – If True, add some poisonian noise to the data to make then more realistic
grow_mask – grow mask in polar coordinated to accomodate pixel splitting algoritm

Returns:

inpainting object which contains the restored image as .data

integrate1d(data, npt, filename=None, correctSolidAngle=True, variance=None, error_model=None, radial_range=None, azimuth_range=None, mask=None, dummy=None, delta_dummy=None, polarization_factor=None, dark=None, flat=None, method='csr', unit=q_nm^-1, safe=True, normalization_factor=1.0, block_size=32, profile=False, all=False, metadata=None)¶

Calculate the azimuthal integrated Saxs curve in q(nm^-1) by default

Multi algorithm implementation (tries to be bullet proof), suitable for SAXS, WAXS, ... and much more

Parameters:	data (ndarray) – 2D array from the Detector/CCD camera npt (int) – number of points in the output pattern filename (str) – output filename in 2/3 column ascii format correctSolidAngle (bool) – correct for solid angle of each pixel if True variance (ndarray) – array containing the variance of the data. If not available, no error propagation is done error_model (str) – When the variance is unknown, an error model can be given: “poisson” (variance = I), “azimuthal” (variance = (I-<I>)^2) radial_range ((float, float), optional) – The lower and upper range of the radial unit. If not provided, range is simply (data.min(), data.max()). Values outside the range are ignored. azimuth_range ((float, float), optional) – The lower and upper range of the azimuthal angle in degree. If not provided, range is simply (data.min(), data.max()). Values outside the range are ignored. mask (ndarray) – array (same size as image) with 1 for masked pixels, and 0 for valid pixels dummy (float) – value for dead/masked pixels delta_dummy (float) – precision for dummy value polarization_factor (float) – polarization factor between -1 (vertical) and +1 (horizontal). 0 for circular polarization or random, None for no correction, True for using the former correction dark (ndarray) – dark noise image flat (ndarray) – flat field image method (str) – can be “numpy”, “cython”, “BBox” or “splitpixel”, “lut”, “csr”, “nosplit_csr”, “full_csr”, “lut_ocl” and “csr_ocl” if you want to go on GPU. To Specify the device: “csr_ocl_1,2” unit (pyFAI.units.Unit) – Output units, can be “q_nm^-1”, “q_A^-1”, “2th_deg”, “2th_rad”, “r_mm” for now safe (bool) – Do some extra checks to ensure LUT/CSR is still valid. False is faster. normalization_factor (float) – Value of a normalization monitor block_size – size of the block for OpenCL integration (unused?) profile – set to True to enable profiling in OpenCL all (bool) – if true return a dictionary with many more parameters (deprecated, please refer to the documentation of Integrate1dResult). metadata – JSON serializable object containing the metadata, usually a dictionary.
Returns:	q/2th/r bins center positions and regrouped intensity (and error array if variance or variance model provided), uneless all==True.
Return type:	Integrate1dResult, dict

integrate2d(data, npt_rad, npt_azim=360, filename=None, correctSolidAngle=True, variance=None, error_model=None, radial_range=None, azimuth_range=None, mask=None, dummy=None, delta_dummy=None, polarization_factor=None, dark=None, flat=None, method='bbox', unit=q_nm^-1, safe=True, normalization_factor=1.0, all=False, metadata=None)¶

Calculate the azimuthal regrouped 2d image in q(nm^-1)/chi(deg) by default

Multi algorithm implementation (tries to be bullet proof)

Parameters:	data (ndarray) – 2D array from the Detector/CCD camera npt_rad (int) – number of points in the radial direction npt_azim (int) – number of points in the azimuthal direction filename (str) – output image (as edf format) correctSolidAngle (bool) – correct for solid angle of each pixel if True variance (ndarray) – array containing the variance of the data. If not available, no error propagation is done error_model (str) – When the variance is unknown, an error model can be given: “poisson” (variance = I), “azimuthal” (variance = (I-<I>)^2) radial_range ((float, float), optional) – The lower and upper range of the radial unit. If not provided, range is simply (data.min(), data.max()). Values outside the range are ignored. azimuth_range ((float, float), optional) – The lower and upper range of the azimuthal angle in degree. If not provided, range is simply (data.min(), data.max()). Values outside the range are ignored. mask (ndarray) – array (same size as image) with 1 for masked pixels, and 0 for valid pixels dummy (float) – value for dead/masked pixels delta_dummy (float) – precision for dummy value polarization_factor (float) – polarization factor between -1 (vertical) and +1 (horizontal). 0 for circular polarization or random, None for no correction dark (ndarray) – dark noise image flat (ndarray) – flat field image method (str) – can be “numpy”, “cython”, “BBox” or “splitpixel”, “lut”, “csr; “lut_ocl” and “csr_ocl” if you want to go on GPU. To Specify the device: “csr_ocl_1,2” unit (pyFAI.units.Unit) – Output units, can be “q_nm^-1”, “q_A^-1”, “2th_deg”, “2th_rad”, “r_mm” for now safe (bool) – Do some extra checks to ensure LUT is still valid. False is faster. normalization_factor (float) – Value of a normalization monitor all (bool) – if true, return many more intermediate results as a dict (deprecated, please refer to the documentation of Integrate2dResult). metadata – JSON serializable object containing the metadata, usually a dictionary.
Returns:	azimuthaly regrouped intensity, q/2theta/r pos. and chi pos.
Return type:	Integrate2dResult, dict

integrate_radial(data, npt, npt_rad=100, correctSolidAngle=True, radial_range=None, azimuth_range=None, mask=None, dummy=None, delta_dummy=None, polarization_factor=None, dark=None, flat=None, method='csr', unit=chi_deg, radial_unit=q_nm^-1, normalization_factor=1.0)¶

Calculate the radial integrated profile curve as I = f(chi)

Parameters:	data (ndarray) – 2D array from the Detector/CCD camera npt (int) – number of points in the output pattern npt_rad (int) – number of points in the radial space. Too few points may lead to huge rounding errors. filename (str) – output filename in 2/3 column ascii format correctSolidAngle (bool) – correct for solid angle of each pixel if True radial_range (Tuple(float, float)) – The lower and upper range of the radial unit. If not provided, range is simply (data.min(), data.max()). Values outside the range are ignored. Optional. azimuth_range (Tuple(float, float)) – The lower and upper range of the azimuthal angle in degree. If not provided, range is simply (data.min(), data.max()). Values outside the range are ignored. Optional. mask (ndarray) – array (same size as image) with 1 for masked pixels, and 0 for valid pixels dummy (float) – value for dead/masked pixels delta_dummy (float) – precision for dummy value polarization_factor (float) – polarization factor between -1 (vertical) and +1 (horizontal). * 0 for circular polarization or random, * None for no correction, * True for using the former correction dark (ndarray) – dark noise image flat (ndarray) – flat field image method (str) – can be “numpy”, “cython”, “BBox” or “splitpixel”, “lut”, “csr”, “nosplit_csr”, “full_csr”, “lut_ocl” and “csr_ocl” if you want to go on GPU. To Specify the device: “csr_ocl_1,2” unit (pyFAI.units.Unit) – Output units, can be “chi_deg” or “chi_rad” radial_unit (pyFAI.units.Unit) – unit used for radial representation, can be “q_nm^-1”, “q_A^-1”, “2th_deg”, “2th_rad”, “r_mm” for now normalization_factor (float) – Value of a normalization monitor
Returns:	chi bins center positions and regrouped intensity
Return type:	Integrate1dResult

medfilt1d(data, npt_rad=1024, npt_azim=512, correctSolidAngle=True, polarization_factor=None, dark=None, flat=None, method='splitpixel', unit=q_nm^-1, percentile=50, mask=None, normalization_factor=1.0, metadata=None)¶

Perform the 2D integration and filter along each row using a median filter

Parameters:

data – input image as numpy array
npt_rad – number of radial points
npt_azim – number of azimuthal points
correctSolidAngle (bool) – correct for solid angle of each pixel if True
polarization_factor (float) – polarization factor between -1 (vertical) and +1 (horizontal). 0 for circular polarization or random, None for no correction, True for using the former correction
dark (ndarray) – dark noise image
flat (ndarray) – flat field image
unit – unit to be used for integration
method – pathway for integration and sort
percentile – which percentile use for cutting out percentil can be a 2-tuple to specify a region to average out
mask – masked out pixels array
normalization_factor (float) – Value of a normalization monitor
metadata (JSON serializable dict) – any other metadata,

Returns:

Integrate1D like result like

reset()¶: Reset azimuthal integrator in addition to other arrays.

reset_engines()¶: Urgently free memory by deleting all regrid-engines

save1D(*args, **kwargs)¶

This method save the result of a 1D integration.

Deprecated on 13/06/2017

Parameters:

filename (str) – the filename used to save the 1D integration
dim1 (numpy.ndarray) – the x coordinates of the integrated curve
I (numpy.mdarray) – The integrated intensity
error (numpy.ndarray or None) – the error bar for each intensity
dim1_unit (pyFAI.units.Unit) – the unit of the dim1 array
has_dark (bool) – save the darks filenames (default: no)
has_flat (bool) – save the flat filenames (default: no)
polarization_factor (float) – the polarization factor
normalization_factor (float) – the monitor value

save2D(*args, **kwargs)¶

This method save the result of a 2D integration.

Deprecated on 13/06/2017

Parameters:

filename (str) – the filename used to save the 2D histogram
dim1 (numpy.ndarray) – the 1st coordinates of the histogram
dim1 – the 2nd coordinates of the histogram
I (numpy.mdarray) – The integrated intensity
error (numpy.ndarray or None) – the error bar for each intensity
dim1_unit (pyFAI.units.Unit) – the unit of the dim1 array
has_dark (bool) – save the darks filenames (default: no)
has_flat (bool) – save the flat filenames (default: no)
polarization_factor (float) – the polarization factor
normalization_factor (float) – the monitor value

saxs(*args, **kwargs)¶

Calculate the azimuthal integrated Saxs curve in q in nm^-1.

Wrapper for integrate1d emulating behavour of old saxs method

Parameters:	data (ndarray) – 2D array from the CCD camera npt (int) – number of points in the output pattern filename (str) – file to save data to correctSolidAngle (bool) – if True, the data are devided by the solid angle of each pixel variance (ndarray) – array containing the variance of the data, if you know it error_model (str) – When the variance is unknown, an error model can be given: “poisson” (variance = I), “azimuthal” (variance = (I-<I>)^2) qRange ((float, float), optional) – The lower and upper range of the sctter vector q. If not provided, range is simply (data.min(), data.max()). Values outside the range are ignored. chiRange ((float, float), optional) – The lower and upper range of the chi angle. If not provided, range is simply (data.min(), data.max()). Values outside the range are ignored. mask (ndarray) – array (same size as image) with 1 for masked pixels, and 0 for valid pixels dummy (float) – value for dead/masked pixels delta_dummy (float) – precision for dummy value polarization_factor (float) – polarization factor between -1 and +1. 0 for circular correction, None for no correction dark (ndarray) – dark noise image flat (ndarray) – flat field image method (str) – can be “numpy”, “cython”, “BBox” or “splitpixel”
Returns:	azimuthaly regrouped data, 2theta pos. and chi pos.
Return type:	3-tuple of ndarrays

separate(data, npt_rad=1024, npt_azim=512, unit='2th_deg', method='splitpixel', percentile=50, mask=None, restore_mask=True)¶

Separate bragg signal from powder/amorphous signal using azimuthal integration, median filering and projected back before subtraction.

Parameters:	data – input image as numpy array npt_rad – number of radial points npt_azim – number of azimuthal points unit – unit to be used for integration method – pathway for integration and sort percentile – which percentile use for cutting out mask – masked out pixels array restore_mask – masked pixels have the same value as input data provided
Returns:	bragg, amorphous

set_darkcurrent(dark)¶

set_darkfiles(files=None, method='mean')¶

Set the dark current from one or mutliple files, avaraged according to the method provided.

Moved to Detector.

Parameters:	files (str or list(str) or None) – file(s) used to compute the dark. method (str) – method used to compute the dark, “mean” or “median”

set_empty(value)¶

set_flatfield(flat)¶

set_flatfiles(files, method='mean')¶

Set the flat field from one or mutliple files, averaged according to the method provided.

Moved to Detector.

Parameters:	files (str or list(str) or None) – file(s) used to compute the flat-field. method (str) – method used to compute the dark, “mean” or “median”

setup_CSR(shape, npt, mask=None, pos0_range=None, pos1_range=None, mask_checksum=None, unit=2th_deg, split='bbox')¶

Prepare a look-up-table

Parameters:

shape ((int, int)) – shape of the dataset
npt (int or (int, int)) – number of points in the the output pattern
mask (ndarray) – array with masked pixel (1=masked)
pos0_range ((float, float)) – range in radial dimension
pos1_range ((float, float)) – range in azimuthal dimension
mask_checksum (int (or anything else ...)) – checksum of the mask buffer
unit (pyFAI.units.Unit) – use to propagate the LUT object for further checkings
split – Splitting scheme: valid options are “no”, “bbox”, “full”

This method is called when a look-up table needs to be set-up. The shape parameter, correspond to the shape of the original datatset. It is possible to customize the number of point of the output histogram with the npt parameter which can be either an integer for an 1D integration or a 2-tuple of integer in case of a 2D integration. The LUT will have a different shape: (npt, lut_max_size), the later parameter being calculated during the instanciation of the splitBBoxLUT class.

It is possible to prepare the LUT with a predefine mask. This operation can speedup the computation of the later integrations. Instead of applying the patch on the dataset, it is taken into account during the histogram computation. If provided the mask_checksum prevent the re-calculation of the mask. When the mask changes, its checksum is used to reset (or not) the LUT (which is a very time consuming operation !)

It is also possible to restrain the range of the 1D or 2D pattern with the pos1_range and pos2_range.

The unit parameter is just propagated to the LUT integrator for further checkings: The aim is to prevent an integration to be performed in 2th-space when the LUT was setup in q space.

setup_LUT(shape, npt, mask=None, pos0_range=None, pos1_range=None, mask_checksum=None, unit=2th_deg)¶

Prepare a look-up-table

Parameters:

shape ((int, int)) – shape of the dataset
npt (int or (int, int)) – number of points in the the output pattern
mask (ndarray) – array with masked pixel (1=masked)
pos0_range ((float, float)) – range in radial dimension
pos1_range ((float, float)) – range in azimuthal dimension
mask_checksum (int (or anything else ...)) – checksum of the mask buffer
unit (pyFAI.units.Unit) – use to propagate the LUT object for further checkings

This method is called when a look-up table needs to be set-up. The shape parameter, correspond to the shape of the original datatset. It is possible to customize the number of point of the output histogram with the npt parameter which can be either an integer for an 1D integration or a 2-tuple of integer in case of a 2D integration. The LUT will have a different shape: (npt, lut_max_size), the later parameter being calculated during the instanciation of the splitBBoxLUT class.

It is possible to prepare the LUT with a predefine mask. This operation can speedup the computation of the later integrations. Instead of applying the patch on the dataset, it is taken into account during the histogram computation. If provided the mask_checksum prevent the re-calculation of the mask. When the mask changes, its checksum is used to reset (or not) the LUT (which is a very time consuming operation !)

It is also possible to restrain the range of the 1D or 2D pattern with the pos1_range and pos2_range.

The unit parameter is just propagated to the LUT integrator for further checkings: The aim is to prevent an integration to be performed in 2th-space when the LUT was setup in q space.

sigma_clip(data, npt_rad=1024, npt_azim=512, correctSolidAngle=True, polarization_factor=None, dark=None, flat=None, method='splitpixel', unit=q_nm^-1, thres=3, max_iter=5, mask=None, normalization_factor=1.0, metadata=None)¶

Perform the 2D integration and perform a sigm-clipping iterative filter along each row. see the doc of scipy.stats.sigmaclip for the options.

Parameters:

data – input image as numpy array
npt_rad – number of radial points
npt_azim – number of azimuthal points
correctSolidAngle (bool) – correct for solid angle of each pixel if True
polarization_factor (float) –
polarization factor between -1 (vertical) and +1 (horizontal).
- 0 for circular polarization or random,
- None for no correction,
- True for using the former correction
dark (ndarray) – dark noise image
flat (ndarray) – flat field image
unit – unit to be used for integration
method – pathway for integration and sort
thres – cut-off for n*sigma: discard any values with (I-<I>)/sigma > thres. The threshold can be a 2-tuple with sigma_low and sigma_high.
max_iter – maximum number of iterations :param mask: masked out pixels array
normalization_factor (float) – Value of a normalization monitor
metadata (JSON serializable dict) – any other metadata,

Returns:

Integrate1D like result like

xrpd(*args, **kwargs)¶

Calculate the powder diffraction pattern from a set of data, an image.

Cython implementation

Parameters:	data (ndarray) – 2D array from the CCD camera npt (integer) – number of points in the output pattern filename (str) – file to save data in ascii format 2 column correctSolidAngle (bool or int) – solid angle correction, order 1 or 3 (like fit2d) tthRange ((float, float), optional) – The lower and upper range of the 2theta chiRange ((float, float), optional, disabled for now) – The lower and upper range of the chi angle. mask (ndarray) – array with 1 for masked pixels, and 0 for valid pixels dummy (float) – value for dead/masked pixels (dynamic mask) delta_dummy (float) – precision for dummy value polarization_factor (float or None) – polarization factor correction dark (ndarray) – dark noise image flat (ndarray) – flat field image
Returns:	(2theta, I) in degrees
Return type:	2-tuple of 1D arrays

This method compute the powder diffraction pattern, from a given data image. The number of point of the pattern is given by the npt parameter. If you give a filename, the powder diffraction is also saved as a two column text file.

It is possible to correct or not the powder diffraction pattern using the correctSolidAngle parameter. The weight of a pixel is ponderate by its solid angle.

The 2theta range of the powder diffraction pattern can be set using the tthRange parameter. If not given the maximum available range is used. Indeed pixel outside this range are ignored.

Each pixel of the data image as also a chi coordinate. So it is possible to restrain the chi range of the pixels to consider in the powder diffraction pattern. you just need to set the range with the chiRange parameter. like the tthRange parameter, value outside this range are ignored.

Sometimes one needs to mask a few pixels (beamstop, hot pixels, ...), to ignore a few of them you just need to provide a mask array with a value of 1 for those pixels. To take a pixel into account you just need to set a value of 0 in the mask array. Indeed the shape of the mask array should be idential to the data shape (size of the array _must_ be the same). Pixels can also be maseked by seting them to an

Bad pixels can be masked out by setting them to an impossible value (-1) and calling this value the “dummy value”. Some Pilatus detectors are setting non existing pixel to -1 and dead pixels to -2. Then use dummy=-2 & delta_dummy=1.5 so that any value between -3.5 and -0.5 are considered as bad.

Some Pilatus detectors are setting non existing pixel to -1 and dead pixels to -2. Then use dummy=-2 & delta_dummy=1.5 so that any value between -3.5 and -0.5 are considered as bad.

The polarisation correction can be taken into account with the polarization_factor parameter. Set it between [-1, 1], to correct your data. If set to 0, the circular polarization is used. When None, there is no correction at all.

The dark and the flat can be provided to correct the data before computing the radial integration.

xrpd2(*args, **kwargs)¶

Calculate the 2D powder diffraction pattern (2Theta,Chi) from a set of data, an image

Split pixels according to their coordinate and a bounding box

Parameters:	data (ndarray) – 2D array from the CCD camera npt_rad – number of bin of the Radial (horizontal) axis (2Theta) npt_azim (int) – number of bin of the Azimuthal (vertical) axis (chi) filename (str) – file to save data in correctSolidAngle (bool or int) – solid angle correction, order 1 or 3 (like fit2d) tthRange ((float, float)) – The lower and upper range of 2theta chiRange ((float, float), disabled for now) – The lower and upper range of the chi angle. mask (ndarray) – array with 1 for masked pixels, and 0 for valid pixels dummy (float) – value for dead/masked pixels (dynamic mask) delta_dummy (float) – precision for dummy value polarization_factor (float) – polarization factor correction dark (ndarray) – dark noise image flat (ndarray) – flat field image
Returns:	azimuthaly regrouped data, 2theta pos. and chi pos.
Return type:	3-tuple of ndarrays

This method convert the data image from the pixel coordinates to the 2theta, chi coordinates. This is similar to a rectangular to polar conversion. The number of point of the new image is given by npt_rad and npt_azim. If you give a filename, the new image is also saved as an edf file.

It is possible to correct the 2theta/chi pattern using the correctSolidAngle parameter. The weight of a pixel is ponderate by its solid angle.

The 2theta and range of the new image can be set using the tthRange parameter. If not given the maximum available range is used. Indeed pixel outside this range are ignored.

Each pixel of the data image has a 2theta and a chi coordinate. So it is possible to restrain on any of those ranges ; you just need to set the range with the tthRange or thee chiRange parameter. like the tthRange parameter, value outside this range are ignored.

Sometimes one needs to mask a few pixels (beamstop, hot pixels, ...), to ignore a few of them you just need to provide a mask array with a value of 1 for those pixels. To take a pixel into account you just need to set a value of 0 in the mask array. Indeed the shape of the mask array should be idential to the data shape (size of the array _must_ be the same).

Masking can also be achieved by setting masked pixels to an impossible value (-1) and calling this value the “dummy value”. Some Pilatus detectors are setting non existing pixel to -1 and dead pixels to -2. Then use dummy=-2 & delta_dummy=1.5 so that any value between -3.5 and -0.5 are considered as bad.

the polarisation correction can be taken into account with the polarization_factor parameter. Set it between [-1, 1], to correct your data. If set to 0: circular polarization. When None there is no correction at all.

The dark and the flat can be provided to correct the data before computing the radial integration.

xrpd2_histogram(*args, **kwargs)¶

Calculate the 2D powder diffraction pattern (2Theta,Chi) from a set of data, an image

Cython implementation: fast but incaccurate

Parameters:	data (ndarray) – 2D array from the CCD camera npt_rad – number of bin of the Radial (horizontal) axis (2Theta) npt_azim (int) – number of bin of the Azimuthal (vertical) axis (chi) filename (str) – file to save data in correctSolidAngle (bool or int) – solid angle correction, order 1 or 3 (like fit2d) tthRange ((float, float)) – The lower and upper range of 2theta chiRange ((float, float), disabled for now) – The lower and upper range of the chi angle. mask (ndarray) – array with 1 for masked pixels, and 0 for valid pixels dummy (float) – value for dead/masked pixels (dynamic mask) delta_dummy (float) – precision for dummy value
Returns:	azimuthaly regrouped data, 2theta pos and chipos
Return type:	3-tuple of ndarrays

This method convert the data image from the pixel coordinates to the 2theta, chi coordinates. This is simular to a rectangular to polar conversion. The number of point of the new image is given by npt_rad and npt_azim. If you give a filename, the new image is also saved as an edf file.

It is possible to correct the 2theta/chi pattern using the correctSolidAngle parameter. The weight of a pixel is ponderate by its solid angle.

The 2theta and range of the new image can be set using the tthRange parameter. If not given the maximum available range is used. Indeed pixel outside this range are ignored.

Each pixel of the data image has a 2theta and a chi coordinate. So it is possible to restrain on any of those ranges ; you just need to set the range with the tthRange or thee chiRange parameter. like the tthRange parameter, value outside this range are ignored.

Sometimes one needs to mask a few pixels (beamstop, hot pixels, ...), to ignore a few of them you just need to provide a mask array with a value of 1 for those pixels. To take a pixel into account you just need to set a value of 0 in the mask array. Indeed the shape of the mask array should be idential to the data shape (size of the array _must_ be the same).

Masking can also be achieved by setting masked pixels to an impossible value (-1) and calling this value the “dummy value”. Some Pilatus detectors are setting non existing pixel to -1 and dead pixels to -2. Then use dummy=-2 & delta_dummy=1.5 so that any value between -3.5 and -0.5 are considered as bad.

xrpd2_numpy(*args, **kwargs)¶

Calculate the 2D powder diffraction pattern (2Theta, Chi) from a set of data, an image

Pure numpy implementation (VERY SLOW !!!)

Parameters:	data (ndarray) – 2D array from the CCD camera npt_rad – number of bin of the Radial (horizontal) axis (2Theta) npt_azim (int) – number of bin of the Azimuthal (vertical) axis (chi) filename (str) – file to save data in correctSolidAngle (bool or int) – solid angle correction, order 1 or 3 (like fit2d) tthRange ((float, float)) – The lower and upper range of 2theta chiRange ((float, float), disabled for now) – The lower and upper range of the chi angle. mask (ndarray) – array with 1 for masked pixels, and 0 for valid pixels dummy (float) – value for dead/masked pixels (dynamic mask) delta_dummy (float) – precision for dummy value
Returns:	azimuthaly regrouped data, 2theta pos and chipos
Return type:	3-tuple of ndarrays

This method convert the data image from the pixel coordinates to the 2theta, chi coordinates. This is simular to a rectangular to polar conversion. The number of point of the new image is given by npt_rad and npt_azim. If you give a filename, the new image is also saved as an edf file.

It is possible to correct the 2theta/chi pattern using the correctSolidAngle parameter. The weight of a pixel is ponderate by its solid angle.

The 2theta and range of the new image can be set using the tthRange parameter. If not given the maximum available range is used. Indeed pixel outside this range are ignored.

Each pixel of the data image has a 2theta and a chi coordinate. So it is possible to restrain on any of those ranges ; you just need to set the range with the tthRange or thee chiRange parameter. like the tthRange parameter, value outside this range are ignored.

Sometimes one needs to mask a few pixels (beamstop, hot pixels, ...), to ignore a few of them you just need to provide a mask array with a value of 1 for those pixels. To take a pixel into account you just need to set a value of 0 in the mask array. Indeed the shape of the mask array should be idential to the data shape (size of the array _must_ be the same).

Masking can also be achieved by setting masked pixels to an impossible value (-1) and calling this value the “dummy value”. Some Pilatus detectors are setting non existing pixel to -1 and dead pixels to -2. Then use dummy=-2 & delta_dummy=1.5 so that any value between -3.5 and -0.5 are considered as bad.

xrpd2_splitBBox(*args, **kwargs)¶

Calculate the 2D powder diffraction pattern (2Theta,Chi) from a set of data, an image

Split pixels according to their coordinate and a bounding box

Parameters:	data (ndarray) – 2D array from the CCD camera npt_rad – number of bin of the Radial (horizontal) axis (2Theta) npt_azim (int) – number of bin of the Azimuthal (vertical) axis (chi) filename (str) – file to save data in correctSolidAngle (bool or int) – solid angle correction, order 1 or 3 (like fit2d) tthRange ((float, float)) – The lower and upper range of 2theta chiRange ((float, float), disabled for now) – The lower and upper range of the chi angle. mask (ndarray) – array with 1 for masked pixels, and 0 for valid pixels dummy (float) – value for dead/masked pixels (dynamic mask) delta_dummy (float) – precision for dummy value polarization_factor (float) – polarization factor correction dark (ndarray) – dark noise image flat (ndarray) – flat field image
Returns:	azimuthaly regrouped data, 2theta pos. and chi pos.
Return type:	3-tuple of ndarrays