BornAgain-git-develop Datafield

Datafield

A Datafield holds experimental or simulated scattering data. Most importantly, simulation.simulate() returns a Datafield.

A Datafield contains

an array of intensities,
optionally, an array of error estimates,
coordinate axes, and
optionally, a title.

Extract arrays

datafield = simulation.simulate()
datafield.xCenters()     # centers of x bins
datafield.yCenters()     # centers of y bins (2D data)
datafield.intensities()  # intensities
datafield.errors()       # error estimates, or None

These methods return NumPy arrays. For 2D data, intensities() has shape (ny, nx): rows correspond to y, columns to x. The arrays are copies; changing them does not change the field.

To save the arrays to files, see Export.

Title and plot

datafield.setTitle("Measured intensity")
ba.plot_datafield(datafield)
ba.plt.show()

Titles distinguish fields that are put together in a list. Plotting functions use them as legend labels. See Plotting for plotting options and Axis coordinates and transformations for coordinate systems.

Process

row = datafield.xProjection(0.5)             # row nearest y = 0.5
band = datafield.xProjection(0.5, 1.5)       # sum of rows from y = 0.5 to 1.5
column = datafield.yProjection(1.5)          # column nearest x = 1.5
region = datafield.crop(0.2, 0.2, 2.8, 1.8)  # xmin, ymin, xmax, ymax
normalized = datafield.normalizedToMax()
synthetic = datafield.noisy(0.2, 0.0)

Coordinates are given in the units of the field’s axes. Projections sum values along one axis and return a 1D field. For 1D data, use crop(xmin, xmax). normalizedToMax() divides by the maximum value. noisy(prefactor, minimum) adds Gaussian noise with standard deviation prefactor*sqrt(value) and clamps the result below at minimum. All of these return new fields and leave the original unchanged.

For analysis examples, see Fourier transform and Finding intensity peaks.

Individual values

Values are stored in flat order. For 2D data, column ix and row iy have the index i = iy*nx + ix:

nx = datafield.xAxis().size()
i = 1*nx + 2                  # column 2, row 1
value = datafield.valAt(i)
datafield.setAt(i, value + 1)

datafield.size() is the total number of values. datafield.minVal() and datafield.maxVal() return the smallest and largest value.

Create a field

For your own data, create a Frame for the coordinates and pass the values in flat order:

import bornagain as ba
import numpy as np

frame = ba.Frame(
    ba.EquiDivision("x (nm)", 3, 0, 3),
    ba.EquiDivision("y (nm)", 2, 0, 2))
values = np.array([[1., 2., 3.], [4., 5., 6.]])
datafield = ba.Datafield("Example", frame, values.ravel().tolist())

The title is optional. An optional final argument supplies error estimates in the same order.

All operations

Arrays

Operation	Result
`intensities()`	NumPy copy of the values, shaped like the data.
`errors()`	NumPy copy of the error estimates, or `None`.
`flatVector()`	Values in flat order.
`errorSigmas()`	Error estimates in flat order, or an empty sequence.
`xCenters()`	NumPy array of x-bin centers.
`yCenters()`	NumPy array of y-bin centers, for 2D data.

Title

Operation	Result
`title()`	Title of the field.
`setTitle(title)`	Change the title.

Axes

Operation	Result
`frame()`	Frame holding the axes.
`axis(k)`	Axis `k`, numbered from zero.
`xAxis()`	First axis.
`yAxis()`	Second axis, for 2D data.
`rank()`	Number of axes.

Values

Operation	Result
`size()`	Total number of values.
`empty()`	Whether the field contains no values.
`valAt(i)`	Value at flat index `i`.
`setAt(i, value)`	Change the value at flat index `i`.
`setAllTo(value)`	Change every value.
`minVal()`	Smallest value.
`maxVal()`	Largest value.

Projections and cropping

Operation	Result
`xProjection(y)`	Row nearest `y`, as a 1D field.
`xProjection(ylow, yup)`	Sum of the rows from `ylow` to `yup`.
`yProjection(x)`	Column nearest `x`, as a 1D field.
`yProjection(xlow, xup)`	Sum of the columns from `xlow` to `xup`.
`crop(xmin, ymin, xmax, ymax)`	Part of a 2D field within the given range.
`crop(xmin, xmax)`	Part of a 1D field within the given range.

New fields

Operation	Result
`normalizedToMax()`	Copy divided by the maximum value.
`noisy(prefactor, minimum)`	Copy with added Gaussian noise.
`flat()`	Copy with single-bin axes removed.
`plottableField()`	Copy with axes in display units, such as degrees.

Introduction
- Functionality overview

Install BornAgain

Python scripting

Reference

Examples

How to

Developers' corner