Helicity quantification

The helicity of an objct can be analyzed in different ways. The main method presented in our paper is to calculate the helicity function (helicity_function), which gives the helicity as a function of the distance between the helical axis and the inclination angle. It is also possible to get the total helicity (total_helicity), which is a single value between -1 and +1 that indicates the total helicity of an object based on the results of the helicity function.

If you want to analyze the distribution of helical features across an object, you can use helicity_map, which returns an array that indicates the local helicity around each voxel. Use helicity_descriptor for more controll about how to calculate this helicity map, this function is internally used by helicity_function and helicity_descriptor and returns two arrays: one array containing the magnitude of helicity (i.e. the gradient magnitude) in each voxel and one array containing the inclination angle. That way, you can select for example only the parts of your object that have a certain inclination angle.

class HelicityFunction(delta_alpha: float, delta_rho: float, histogram: numpy.ndarray)[source]: Holds the contents of a helicity function.

helicity_descriptor(data: numpy.ndarray, kernel_size: int = 5) → Tuple[numpy.ndarray, numpy.ndarray][source]

Calculate the inclination angle and gradient magnitude in each voxel.

This is not a measure of helicity itself, but is used as the first step in most other methods. It can however be used to analyze the helicity of a particle with a custom method.

Parameters

data – The voxel data as a 3D array that describes the object.
kernel_size – The size of the Sobel kernel used for calculating the gradient, should be an odd integer.

Returns

A tuple of two elements, the first is the normalized gradient magnitude in each voxel and the second element is the inclination angle in degrees in each voxel.

helicity_function(data: numpy.ndarray, voxel_size: float, delta_alpha: float = 1.0, delta_rho: Optional[float] = None, kernel_size: int = 5) → heliq.helicity.HelicityFunction[source]

Calculate the helicity function for a given object.

Parameters

data – The voxel data as a 3D array that describes the object.
voxel_size – The width of the voxels in the data.
delta_alpha – The bin size for the inclination angles in degrees.
delta_rho – The bin size in the radial direction in the same units as the voxel_size, by default delta_rho = voxel_size.
kernel_size – The size of the Sobel kernel used for calculating the gradient, should be an odd integer.

Returns

A HelicityFunction containing the results.

helicity_map(data: numpy.ndarray, sigma: float, threshold: Optional[float] = None, kernel_size: int = 5) → numpy.ndarray[source]

Create a helicity map that indicates the helicity around each voxel

Parameters

data – The voxel data (3D array) that describes the object.
sigma – The effective size of a region over which the local helicity will be averaged, this is done using Gaussian smoothing in 3D.
threshold – If specified, all voxels in the result where data < threshold will be set to zero.
kernel_size – The size of the Sobel kernel used for calculating the gradient, should be an odd integer.

Returns

A 3D array with the same shape as data that contains the 3D helicity map.

plot_helicity_function(hfunc: heliq.helicity.HelicityFunction, vmax: Optional[float] = None, axis: Optional[matplotlib.axes._axes.Axes] = None, cmap: str = 'coolwarm') → matplotlib.image.AxesImage[source]

Plot the helicity function.

Parameters

hfunc – The helicity function of the object.
vmax – The limits for the intensity will be [-vmax, vmax], by default this will be calculated as max(abs(helicity_function)).
axis – The axis on which to draw the helicity function. If not provided, the currect active axis will be used.
cmap – The colormap that will be applied, which should ideally be a diverging colormap to properly visualize the difference between left- and right-handed helicity.

Returns

A matplotlib axis image containing the helicity function.

total_helicity(hfunc: heliq.helicity.HelicityFunction) → float[source]

Calculate the total helicity of an object.

The total helicity is a value between +1 and -1 that indicates the total helicity of the object: a value close to zero indicates achirality, while a value close to +/-1 indicates near-perfect helicity. Positive values indicate right-handed helicity and negative values indicate left-handed helicity.

Parameters: hfunc – The helicity function of the object.
Returns: The total helicity of the object.