ImageParams

class macromol_voxelize.ImageParams(channels: int, grid: ~macromol_voxelize._voxelize.Grid, dtype: ~typing.Type[~numpy.floating] = <class 'numpy.float32'>, max_radius_A: float | None = None, fill_algorithm: ~macromol_voxelize._voxelize.FillAlgorithm = <FillAlgorithm.FractionAtom: 1>, agg_algorithm: ~macromol_voxelize._voxelize.AggAlgorithm = <AggAlgorithm.Sum: 0>)

A collection of parameters that apply to the image as a whole, as opposed to individual atoms.

The most important parameters are channels and grid. Together, these specify the dimensions of the image. The remaining parameters have reasonable defaults.

channels: int

The number of channels in the image.

Note that this must be consistent with the channels column of the atoms data frame passed to image_from_atoms(). An error will be raised if any atoms have channel indices that exceed the actual number of channels, or are negative.

grid: Grid

The spatial dimensions of the image.

dtype: Type[numpy.floating] = numpy.float32

The data type used to encode each voxel of the image.

The following data types are supported:

• numpy.float32, a.k.a. numpy.single

• numpy.float64, a.k.a. numpy.double

Note that 64-bit (i.e. double-precision) floating point numbers are always used for the intermediate calculations needed to fill in each voxel. According to the overlap library, which implements most of these calculations, “reducing the numerical precision of the scalar floating point type will have a significant impact on the precision and stability of the calculations”. Therefore, this setting only affects the precision used to store the final result, and in turn the size of the final image.

max_radius_A: float | None = None

The maximum radius to use when filtering atoms that are outside the image, in units of angstroms.

If not specified, the maximum radius will be calculated from the radius_A column of the atoms dataframe passed to image_from_atoms(). The main reason to specify this parameter is to allow radius_A to be calculated after the initial filtering step, which can be more efficient. Note that an error will be raised if any atoms in the image have radii larger than this maximum (and if __debug__ == True).

fill_algorithm: FillAlgorithm = FillAlgorithm.FractionAtom

The algorithm used to calculate a value for each voxel in the image. The following values are supported:

• FillAlgorithm.OverlapA3: The volume of overlap between the voxel and any atoms, in units of ų.

• FillAlgorithm.FractionAtom: The number (usually fractional) of atoms contained in the voxel. A nice property of this algorithm is that the sum of all the voxels in the image will match the number of atoms used to make it.

• FillAlgorithm.FractionVoxel: The fraction of the voxel that is occupied by atoms. This is calculated separately for each atom, then summed, so the result can be greater than 1.

agg_algorithm: AggAlgorithm = AggAlgorithm.Sum

The algorithm used to aggregate a new fill value for a voxel with the existing value of that voxel.

• AggAlgorithm.Sum: Sum the two values. This results in meaningful volumes/fractions when a voxel is partially occupied by two different atoms.

• AggAlgorithm.Max: Keep the higher of the two values. This may give more reasonable results than summing when there are lots of overlapping atoms.

dtype

alias of float32