pept.processing.circles2d

pept.processing.circles2d(positions, number_of_pixels, radii=0.0, xlim=None, ylim=None, verbose=True)[source]

Compute the 2D occupancy of circles of different radii.

This corresponds to the pixellisation of circular particles, such that each pixel’s value corresponds to the area covered by the particle.

You must specify the particles’ positions (2D numpy array) and the number_of_pixels in each dimension ([nx, ny, nz]). The radii can be either:

  1. Zero: the particles are considered to be points. Each pixel will have a value +1 for every particle.

  2. Single positive value: all particles have the same radius.

  3. List of values of same length as positions: specify each particle’s radius.

The pixel area’s bounds can be specified in xlim and ylim. If unset, they will be computed automatically based on the minimum and maximum values found in positions.

Parameters
positions: (P, 2) numpy.ndarray

The particles’ 2D positions, where each row is formatted as [x_coordinate, y_coordinate].

number_of_pixels: (2,) list-like

The number of pixels in the x-dimension and y-dimension. Each dimension must have at least 2 pixels.

radii: float or (P,) list-like

The radius of each particle. If zero, every particle is considered as a discrete point. If a single float, all particles are considered to have the same radius. If it is a numpy array, it specifies each particle’s radius, and must have the same length as positions.

xlim: (2,) list-like, optional

The limits of the system over which the pixels span in the x-dimension, formatted as [xmin, xmax]. If unset, they will be computed automatically based on the minimum and maximum values found in positions.

ylim: (2,) list-like, optional

The limits of the system over which the pixels span in the y-dimension, formatted as [ymin, ymax]. If unset, they will be computed automatically based on the minimum and maximum values found in positions.

verbose: bool, default True

Time the pixellisation step and print it to the terminal.

Returns
pept.Pixels (numpy.ndarray subclass)

The created pixels, each cell containing the area covered by particles. The pept.Pixels class inherits all properties and methods from numpy.ndarray, so you can use it exactly like you would a numpy array. It just contains extra attributes (e.g. xlim, ylim) and some PEPT-oriented methods (e.g. pixels_trace).

Raises
ValueError

If positions is not a 2D array-like with exactly 2 columns, or number_of_pixels is not a 1D list-like with exactly 2 values or it contains a value smaller than 2. If radii is a list-like that does not have the same length as positions.

Examples

Create ten random particle positions between 0-100 and radii between 0.5-2.5:

>>> positions = np.random.random((10, 2)) * 100
>>> radii = 0.5 + np.random.random(len(positions)) * 2

Now pixellise those particles as circles over a grid of (20, 10) pixels:

>>> import pept.processing as pp
>>> num_pixels = (20, 10)
>>> pixels = pp.circles2d(positions, num_pixels, radii)

Alternatively, specify the system’s bounds explicitly:

>>> pixels = pp.circles2d(
>>>     positions, (20, 10), radii, xlim = [10, 90], ylim = [-5, 105]
>>> )

You can plot those pixels in two ways - using PlotlyGrapher (this plots a 3D “heatmap”, as a coloured surface):

>>> from pept.visualisation import PlotlyGrapher
>>> grapher = PlotlyGrapher()
>>> grapher.add_pixels(pixels)
>>> grapher.show()

Or using raw Plotly (this plots a “true” heatmap) - this is recommended:

>>> import plotly.graph_objs as go
>>> fig = go.Figure()
>>> fig.add_trace(pixels.heatmap_trace())
>>> fig.show()
Post Processing (pept.processing) pept.processing.occupancy2d