cima.maps package

Submodules

cima.maps.density_properties module

cima.maps.density_properties.CropBox(map_target: Map, contour: float) → Map

Crop the map to the bounding box of the region with density above the given contour level.

Parameters:

• map_target (Map) – The target map object.

• contour (float) – The density contour level.

• Returns

• Map – The cropped map object.

cima.maps.density_properties.Hist_density(map_target: Map) → tuple[float, float, float, float, float, float, float, float]

Calculate various statistical properties of the density map.

Parameters:

map_target (Map) – The target map object.

Returns:

A tuple containing:

• The average density.

• The standard deviation of the density.

• The kurtosis of the density distribution.

• The skewness of the density distribution.

• The 25th percentile of the density.

• The 50th percentile (median) of the density.

• The 75th percentile of the density.

• The 90th percentile of the density.

Return type:

tuple

cima.maps.density_properties.MaskCountour(map_target: Map, contour: float) → Map

Mask the map at the given contour level.

Parameters:

• map_target (Map) – The target map object.

• contour (float) – The density contour level.

Returns:

The masked map object.

Return type:

Map

cima.maps.density_properties.calculate_map_threshold_SR(map_target: Map, factor: float = 1.5)

Calculate the threshold for the density map based on a noise factor. If the volume threshold is below 0.5, it is set to 0.5.

Parameters:

• map_target (Map) – The target map object.

• factor (float) – The noise level in sigmas to be added to the average density. Default is 1.5.

• Returns

• float – The calculated volume threshold.

cima.maps.density_properties.get_binarized_points(map_target: Map, value: float) → ndarray

Retrieve all points with a density greater than or equal to the specified value.

Parameters:

• map_target (Map) – The target map object.

• value (float) – The density threshold value.

• Returns – An array of 3-tuple (indices of the voxels in x, y, z format).

cima.maps.density_properties.get_contour_points(map_target: Map, contour: float) → ndarray

Retrieve all points with a density greater than the given contour level.

Parameters:

• map_target (Map) – The target map object.

• contour (float) – The density contour level.

Returns:

An array of 3-tuple (indices of the voxels in x, y, z format).

Return type:

np.ndarray

cima.maps.density_properties.get_index_points(map_target: Map) → ndarray

Retrieve all points with a density greater than zero.

Parameters:

map_target (Map) – The target map object.

Returns:

An array of 3-tuple (indices of the voxels in x, y, z format).

Return type:

np.ndarray

cima.maps.emmap module

class cima.maps.emmap.Map(fullMap: ndarray, origin: tuple[float, float, float] = (0.0, 0.0, 0.0), apix: float = 1.0, filename: str = '', header: list = [])

Bases: object

A class representing information from a density map file and routines for filtering and processing. NOTE: Currently it can only read the CCP4/MRC format.

box_size() → tuple[int, int, int]

Size of the map array, in ZYX format.

centre() → Vector

Centre of the map.

Returns:

Vector instance of the centre of the map in Angstroms.

Return type:

Vector.Vector

change_origin(x_origin: float, y_origin: float, z_origin: float) → Map

Change the origin of the map to a new origin.

Parameters:

• x_origin (float) – new co-ordinates of origin.

• y_origin (float) – new co-ordinates of origin.

• z_origin (float) – new co-ordinates of origin.

Returns:

new Map instance with the origin changed to the specified co-ordinates.

Return type:

Map

copy() → Map

Copy of the Map.

downsample_map(spacing: float) → Map

Downsample the map to a given spacing.

Parameters:

spacing (float) – The spacing to downsample to.

Returns:

The downsampled map.

Return type:

Map

fourier_transform() → Map

Apply Fourier transform on the density map.

Returns:

new Map instance

Return type:

Map

getBinaryMap(threshold: float = 0.5) → Map

Return a new Map instance that has been binarised. All voxel with densities above and below the specified cutoff value are assigned a value of 1.0 and 0.0 respectively.

Parameters:

threshold (float) – threshold density value

Returns:

new binarised Map instance

Return type:

Map

getFilledMap() → Map

Assumes the map is binary (values 0.0 and 1.0) and returns a copy of the map with holes filled.

Returns:

new Map instance with holes filled

Return type:

Map

getMap() → ndarray

Array containing the map density data in the format of (z, y, x).

get_com() → Vector

Retrieve the centre of mass of the map.

Returns:

Vector instance with the CoM of the density map

Return type:

Vector.Vector

get_line_between_points(point1: Vector, point2: Vector) → ndarray

Return an array of float values representing a line of density values between two points on the map.

Parameters:

• point1 (Vector.Vector) – Vector instance of the first end point of the line.

• point2 (Vector.Vector) – Vector instance of the second end point of the line.

Returns:

Array of floating values representing the line of density values.

Return type:

np.ndarray

get_normal_vector(x_pos: int, y_pos: int, z_pos: int) → Vector

Calculate the normal vector at the point specified. Point calculated using 3SOM algorithm used by Ceulemans H. & Russell R.B. (2004).

Parameters:

• x_pos (int) – pixel in map on which to calculate normal vector.

• y_pos (int) – pixel in map on which to calculate normal vector.

• z_pos (int) – pixel in map on which to calculate normal vector.

Returns:

Normal vector at the point specified

Return type:

Vector.Vector

get_point_map(min_thr: float, percentage: float = 0.2) → float

Calculates the amount of point to use for the NV and CD score.

Parameters:

• min_thr (float) – run get_primary_boundary on target map.

• percentage (float) – percentage of the protein volume.

Returns:

Percentage of points above a given threshold

Return type:

float

get_pos(minDens: float, maxDens: float) → ndarray

Identify a set of voxels in the map whose density values fall between the specified minimum and maximum values.

Parameters:

• minDens (float) – minimum density value to include in array.

• maxDens (float) – maximum density value to include in array.

Returns:

An array of 3-tuples (indices of the voxels in x,y,z format)

Return type:

np.ndarray

get_primary_boundary(molWeight: float, low: float, high: float, vol_factor: float = 1.21) → float

Calculates primary boundary density value. Volume of pixels with greater density than output is equivalent to volume given by molecular weight of protein. Uses recursive algorithm. NOTE: when used to calculated the NV score this value should be calculated for the experimental map.

Parameters:

• molWeight (float) – molecular weight of protein; use get_prot_mass_from_atoms() if your structure contains HETATOMS else use get_prot_mass_from_res().

• low (float) – minimum value between which the boundary will be taken. Initial value should be given by minimum density value in map.

• high (float) – maximum value between which the boundary will be taken. Initial value should be given by maximum density value in map.

• vol_factor (float) – in cubic Angstroms per Dalton. This is the approximate value for globular proteins used in Chimera (Petterson et al, 2004) from Harpaz 1994. Other recommended volume factor are 1.5 (1.1-1.9) cubic Angstroms per Dalton in EMAN Volume/mass conversions assume a density of 1.35 g/ml (0.81 Da/A3) (~1.23A3/Da)

Returns:

primary boundary density value (float)

Return type:

float

get_second_boundary(primary_boundary: float, noOfPoints: int, low: float, high: float, err_percent: float = 1) → float | complex

Calculate the second bound density value. For a given boundary value, it calculates the second bound density value such that a specified number of points whose density values fall between the defined boundaries Uses recursive algorithm.

Parameters:

• primary_boundary (float) – primary threshold, normally given by get_primary_boundary method based on protein molecular weight.

• noOfPoints (int) – Number of points to use in the normal vector score - try first with 10% (maybe 5%better) of the number of points in the map ( round((self.map_size())*0.1)

• low (float) – minimum value between which the threshold will be taken. low should be equal to the value returned by the get_primary_boundary() method.

• high (float) – maximum value between which the threshold will be taken. high is the maximum density values in map.

• err_percent (float) – default value of 1. Allowed to find a secondary boundary that includes a 1% error.

Returns:

secondary boundary density value

Return type:

float | complex

get_significant_points() → ndarray

Retrieve all points with a density greater than one standard deviation above the mean.

Return type:

An array of 4-tuple (indices of the voxels in x,y,z format and density value)

get_vectors() → ndarray

Retrieve all non-zero density points in the form of Vector instances.

Return type:

An array of 4-tuple (indices of the voxels in x,y,z format and density value)

header_to_binary()

Returns binary version of map header data. For use in writing out density maps in MRC file format.

laplace_filtered() → Map

Apply Laplacian filter on density maps

Returns:

new Map instance

Return type:

Map

makeKDTree(minDens: float, maxDens: float) → KDTree | None

Returns k-dimensional tree of points in the map with values between those chosen for quick nearest-neighbor lookup.

Parameters:

• minDens (float) – minimum density value to include in k-dimensional tree.

• maxDens (float) – maximum density value to include in k-dimensional tree.

Returns:

index into a set of k-dimensional points.

Return type:

Option(“KDTree”, None)

make_bin_map(cutoff: float) → Map

Return a new Map instance that has been binarised. All voxel with densities above and below the specified cutoff value are assigned a value of -1 and 0 respectively.

Parameters:

cutofffloat

cutoff density value

Returns:

new binarised Map instance

Return type:

Map

map_rotate_by_axis_angle(angle: float, x: float, y: float, z: float, CoM: Vector, rad: bool = False)

Return a new Map instance rotated around its centre.

Parameters:

• angle (float) – angle (in radians if rad == True, else in degrees) to rotate map.

• x (float) – x component of the axis to rotate about.

• y (float) – y component of the axis to rotate about.

• z (float) – z component of the axis to rotate about.

• CoM (np.ndarray) – centre of mass around which map will be rotated.

• rad (bool) – boolean indicating if the angle is in radians (True) or degrees (False).

Returns:

Rotated new Map instance

Return type:

Map

map_size() → int

Size of the array fullMap.

matrix_transform(mat: ndarray, x: float = 0.0, y: float = 0.0, z: float = 0.0) → Map

Apply affine transform to the map.

Parameters:

• mat (np.ndarray) – 3x3 matrix used to transform map.

• x (float) – translation in angstroms.

• y (float) – translation in angstroms.

• z (float) – translation in angstroms.

Returns:

new Map instance with the affine transformed applied.

Return type:

Map

max() → float

Retrieve the maximum density value of the map.

Returns:

Maximum density value of the map.

Return type:

float

mean() → float

Retrieve the mean density value of the map.

Returns:

Mean density value of map.

Return type:

float

median() → float

Retrieve the median density value of the map.

Return type:

Median density value of map.

min() → float

Retrieves the minimum density value of the map.

Returns:

Minimum density value of the map.

Return type:

float

normalise() → Map

Return a new Map instance with normalised density values.

Returns:

new Map instance with normalised density values (so that the mean is 0 and the standard deviation is 1).

Return type:

Map

origin_change_maps(MapRef: Map) → Map

Return a new Map instance with origin changed accordingly to Reference Map

Parameters:

MapRef (Map) – Reference Map

Returns:

new Map instance

Return type:

Map

pad_map(nx: int, ny: int, nz: int)

Pad a map (in place) with specified increments along each dimension.

Parameters:

• nx (int) – The number of voxels to pad along the x, y, and z dimensions, respectively.

• ny (int) – The number of voxels to pad along the x, y, and z dimensions, respectively.

• nz (int) – The number of voxels to pad along the x, y, and z dimensions, respectively.

pixel_centre() → Vector

Retrieve the centre of the map in pixels.

Returns:

Vector instance of the centre of the map in pixels.

Return type:

Vector.Vector

resample_by_apix(new_apix: float) → Map

Resample the map based on new_apix sampling.

Parameters:

new_apix (float) – Angstrom per pixel sampling

Returns:

new Map instance

Return type:

Map

resample_by_box_size(new_box_size: tuple[int, int, int]) → Map

Resample the map based on new box size.

Parameters:

new_box_size (tuple[int, int, int]) – An array containing box dimension in ZYX format

Returns:

new Map instance

Return type:

Map

resize_map(new_size, centre=False) → Map

Resize Map instance.

Parameters:

• new_size (tuple) – 3-tuple (x,y,z) giving the box size.

• centre (bool, optional) – Whether to centre the map, by default False

Returns:

new Map instance

Return type:

Map

rotate_by_axis_angle(angle: float, axis2rotate: tuple, CoM: ndarray, rad: bool = False) → Map

Rotate the map around its centre given an axis and angle.

Parameters:

• angle (float) – Angle (in radians if rad == True, else in degrees) to rotate map.

• axis2rotate (tuple) – Axis to rotate about, ie. (0,0,1) rotates the Map round the xy-plane.

• CoM (np.ndarray) – Centre of mass around which map will be rotated.

• rad (bool, optional) – Whether the angle is in radians, by default False (in which case it is in degrees

Returns:

new Map instance with the map rotated around its centre given the specified axis and angle.

Return type:

Map

rotate_by_euler(x, y, z, CoM, rad=False) → Map

Rotated map around pivot given by CoM using Euler angles.

Parameters:

• x (float) – Euler angles (in radians if rad == True, else in degrees) used to rotate map.

• y (float) – Euler angles (in radians if rad == True, else in degrees) used to rotate map.

• z (float) – Euler angles (in radians if rad == True, else in degrees) used to rotate map.

• CoM (float) – Centre of mass around which map will be rotated.

• rad (bool, optional) – Whether the angles are in radians, by default False (in which case they are in degrees).

Returns:

new Map instance with the map rotated around its centre given the specified Euler angles.

Return type:

Map

rotate_by_matrix(mat: ndarray, CoM: Vector, rad=False) → Map

Rotate the map around pivot given by CoM using a rotation matrix

Parameters:

• mat (np.ndarray) – 3x3 matrix used to rotate map (in radians if rad == True, else in degrees).

• CoM (Vector.Vector) – rotation pivot, usually the centre of mass around which map will be rotated.

• Return – new Map instance with the map rotated around its centre given the specified rotation matrix.

scale_map(scaling: float) → Map

Scaling Map by scaling factor

Parameters:

• scaling (float) – The scaling factor.

• ------ (Returns) – new Map instance

shift_origin(x_shift: float, y_shift: float, z_shift: float) → Map

Shift the Map origin.

Parameters:

• x_shift (float) – translation in angstroms.

• y_shift (float) – translation in angstroms.

• z_shift (float) – translation in angstroms.

Returns:

new Map instance with the shifted origin.

Return type:

Map

std() → float

Retrieve the standard deviation for the density values of the map.

Returns:

Standard deviation of density values in map.

Return type:

float

threshold_map(minDens: float, maxDens: float) → Map

Create a Map instance containing only density values between the specified min and max values.

Parameters:

• minDens (float) – minimum density threshold

• maxDens (float) – maximum density threshold

Returns:

new Map instance

Return type:

Map

translate(x: float, y: float, z: float) → Map

Translate the map by changing origin.

Parameters:

• x (float) – translation in angstroms

• y (float) – translation in angstroms

• z (float) – translation in angstroms

Returns:

new Map instance

Return type:

Map

update_header()

Update self.header to values currently relevant.

vectorise_point(x: float, y: float, z: float) → Vector

Return a tuple of the Angstrom co-ordinates and density value of a particular density point in map. Transform the voxel specified by its indices (x,y,z) into a Vector object. The vector defines the position of the voxel with respect to the origin of the map. The magnitude of the vector is in Angstrom units.

Parameters:

• x (float) – Co-ordinates of the density point to be vectorised.

• y (float) – Co-ordinates of the density point to be vectorised.

• z (float) – Co-ordinates of the density point to be vectorised.

Returns:

Vector instance with the co-ordinates of the density point in Angstroms.

Return type:

Vector.Vector

write_to_MRC_file(mrcfilename: str)

Write out a MRC file

Parameters:

mrcfilename (str) – name of the output mrc file

x_origin() → float

x-coordinate of the origin.

x_size() → int

x size of the map array in x direction.

y_origin() → float

y-coordinate of the origin.

y_size() → int

y size of the map array in y direction.

z_origin() → float

z-coordinate of the origin.

z_size() → int

z size of the map array in z direction.

cima.maps.map_features module

cima.maps.map_features.GetArea_abovecontour(map: Map, threshold: float = 0.5) → float

Calculate the surface area of a map instance above a specified contour threshold.

Parameters:

• map (Map) – The map instance to analyze.

• threshold (float, optional) – The contour threshold value. Defaults to 0.5.

Returns:

The surface area of the map instance above the specified contour threshold.

Return type:

float

cima.maps.map_features.GetArea_equivalent_diameter(surface_area: float) → float

Calculate surface area-equivalent diameter.

Parameters:

surface_area (float) – Surface area of the object.

Returns:

Surface area-equivalent diameter.

Return type:

float

cima.maps.map_features.GetEccenticity_abovecontour(map: Map, threshold: float = 0.5, verbose: bool = False, full: bool = False) → float | tuple[float, float, float, float, ndarray, ndarray, ndarray]

Calculate Eccenticity of a map instance above its optimal contour. Both ellipticity and eccentricity are measures of how elongated an object is based on based on the semi-major axis and semi-minor axis.

Parameters:

• map (Map) – Density Map Object

• threshold (float, optional) – Value above which to compute ellipticity. Defaults to 0.5.

• verbose (bool, optional) – If True, prints out calculations. Defaults to False.

• full (bool, optional) – If True, returns normalized scores. Defaults to False.

Returns:

The eccentricity value of the map instance above its optimal contour.

Return type:

float | tuple[float, float, float, float, np.ndarray, np.ndarray, np.ndarray]

cima.maps.map_features.GetEllipticity_abovecontour(map: Map, threshold: float = 0.5, verbose: bool = False, full: bool = False) → float | tuple[float, float, float, float, ndarray, ndarray, ndarray]

Calculate Ellipticity of a map instance above its optimal contour. Both ellipticity and eccentricity are measures of how elongated an object is based on based on the semi-major axis and semi-minor axis.

Parameters:

• map (Map) – Density Map Object

• threshold (float, optional) – Value above which to compute ellipticity. Defaults to 0.5.

• verbose (bool, optional) – If True, prints out calculations. Defaults to False.

• full (bool, optional) – If True, returns normalized scores. Defaults to False.

Returns:

The ellipticity value of the map instance above its optimal contour.

Return type:

float | tuple[float, float, float, float, np.ndarray, np.ndarray, np.ndarray]

cima.maps.map_features.GetSparseness(map: Map, strobj, threshold: float = 0.5) → float

The ratio between the ellipsoid volume and the object volume

Parameters:

• map (Map) – Density Map Object

• strobj (Structure Object) – Structure Object

• threshold (float, optional) – The threshold above which to compute sparseness. Defaults to 0.5.

Returns:

The sparseness value of the map instance above its optimal contour.

Return type:

float

cima.maps.map_features.GetSphericity(map: Map, threshold: float = 0.5) → float

Calculate the sphericity of a map instance above its optimal contour.

Sphericity is a measure of the degree to which a particle approximates the shape of a sphere, and is independent of its size. Any particle which is not a sphere will have sphericity less than 1.

Parameters:

• map (Map) – The map instance to calculate sphericity for.

• threshold (float, optional) – The threshold value for the contour. Defaults to 0.5.

Returns:

• float – The sphericity of the map instance above its optimal contour.

• References – Wadell, H. (1935). Volume, Shape, and Roundness of Rock Particles. The Journal of Geology, 43(3), 250–280.

cima.maps.map_features.GetSphericity_bribiesca(map: Map, threshold: float = 0.5, verbose: bool = False) → float

Calculate the sphericity of a map instance above its optimal contour.

It is a measure of discrete compactness for rigid solids composed of voxels. This method requires more computation than the classical measure but has two important advantages: it varies linearly, which may be useful in 3D shape classification, and it depends significantly on the sum of the contact surface areas of the face-connected voxels of solids, providing a more robust measure for noisy enclosing surfaces.

Parameters:

• map (Map) – The map instance containing the fullMap attribute.

• threshold (float, optional) – The threshold value to determine the contour. Defaults to 0.5.

• verbose (bool, optional) – If True, prints intermediate values for debugging purposes. Defaults to False.

Returns:

• float – The sphericity value of the map instance.

• References – BRIBIESCA Computers and Mathematics with Applications 40 (2000)

cima.maps.map_features.GetVolume_abovecontour(map: Map, threshold: float = 0.5) → float

Calculate the volume of a map instance above a specified threshold.

Parameters:

• map (Map) – The density map object.

• threshold (float) – The threshold value above which to compute the volume.

Returns:

Volume of the map instance above the specified threshold.

Return type:

float

cima.maps.map_features.GetVolume_equivalent_diameter(volume: float) → float

Calculate volume equivalent diameter.

Parameters:

volume (float) – Volume of the object.

Returns:

Volume-equivalent diameter.

Return type:

float

cima.maps.map_features.getClassicalCompactness(segment_map: Map, threshold: float = 0.5) → float

Returns Compactness defined as surface_area^3/volume^2

BRIBIESCA Computers and Mathematics with Applications 40 (2000).

Parameters:

• segment_map (Map) – The map instance to analyze.

• threshold (float, optional) – The threshold value above which to compute compactness. Defaults to 0.5.

Returns:

The compactness of the map instance above the specified threshold.

Return type:

float

cima.maps.map_features.getConvexHullVolume(coords: ndarray) → float

Calculate the volume of the convex hull for a given set of coordinates.

Parameters:

coords (np.ndarray) – A 2D array of shape (n, 3) representing the coordinates of the points.

Returns:

The volume of the convex hull enclosing the given points.

Return type:

float

cima.maps.map_features.getConvexMap(input_map: Map, threshold: float) → Map

Generate a convex hull map from the input map at a specified threshold.

This function creates a new map representing the convex hull of the input map at the given threshold. The returned map has values 1.0 inside the convex hull and 0.0 everywhere else.

Parameters:

• input_map (Map) – The input density map object.

• threshold (float) – The threshold value to determine the contour.

Returns:

A new map instance representing the convex hull of the input map.

Return type:

Map

cima.maps.map_features.getConvexity(segment_map: Map, threshold: float = 0.5) → float

Calculate the convexity of a segment based on its density map.

Convexity is computed as the ratio of the area above the threshold in the convex map to the area above the threshold in the original segment map. This method is primarily designed for 2D shapes and may not yield accurate results for 3D shapes.

Parameters:

• segment_map (Map) – The map instance to analyze.

• threshold (float, optional) – The density level at which the feature is computed. Defaults to 0.5.

Returns:

• float – The convexity value, which is the ratio of the convex hull area to the segment area.

• References – Liu, S., Cai, W., Song, Y., Pujol, S., Kikinis, R., Wen, L., & Feng, D. D. (2013, July). Localized sparse code gradient in Alzheimer’s disease staging. In 2013 35th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 5398-5401). IEEE.

cima.maps.map_features.getDiscreteCompactness(segment_map: Map, threshold: float = 0.5) → float

Calculate the discrete compactness of a map instance above a specified threshold.

Paper: Bribiesca 2008, An easy measure of compactness for 2D and 3D shapes.

Parameters:

• segment_map (Map) – The map instance to analyze.

• threshold (float, optional) – The threshold value above which to compute compactness. Defaults to 0.5.

Returns:

The discrete compactness of the map instance above the specified threshold.

Return type:

float

cima.maps.map_features.getHolelessSolidity(segment_map: Map, threshold: float = 0.5) → float

Calculate the solidity of a map instance above a specified threshold, with holes filled.

Solidity is defined as the ratio of the volume of the map instance (with holes filled) to the volume of its convex hull. The value of this measure is between 0 and 1.

Parameters:

• segment_map (Map) – The map instance to analyze.

• threshold (float, optional) – The threshold value above which to compute the solidity. Defaults to 0.5.

Returns:

The solidity of the map instance above the specified threshold, with holes filled.

Return type:

float

cima.maps.map_features.getMapRelativePointsFromMap(map: Map, threshold: float = 0.0) → ndarray

Returns a numpy array with each row represening a cell of map with value > threshold, independently of the origin and apix of the map

Parameters:

• map (Map) – The map instance to analyze.

• threshold (float, optional) – The threshold value above which to extract points. Defaults to 0.0.

Returns:

A numpy array where each row represents the coordinates of a cell in the map with a value greater than the specified threshold.

Return type:

np.ndarray

cima.maps.map_features.getPointsFromMap(map: Map, threshold: float = 0.0) → ndarray

Returns a numpy array with each row represening a cell of map with value > threshold.

Parameters:

• map (Map) – The map instance to analyze.

• threshold (float, optional) – The threshold value above which to extract points. Defaults to 0.0.

Returns:

A numpy array where each row represents the coordinates of a cell in the map with a value greater than the specified threshold.

Return type:

np.ndarray

cima.maps.map_features.getSolidity(segment_map: Map, threshold: float = 0.5) → float

Calculate the solidity of a map instance above a specified threshold.

Solidity is defined as the ratio of the volume of the map instance to the volume of its convex hull. The value of this measure is between 0 and 1.

Parameters:

• segment_map (Map) – The map instance to analyze.

• threshold (float, optional) – The threshold value above which to compute the solidity. Defaults to 0.5.

Returns:

• float – The solidity of the map instance above the specified threshold.

• References – Liu, S., Cai, W., Song, Y., Pujol, S., Kikinis, R., Wen, L., & Feng, D. D. (2013, July). Localized sparse code gradient in Alzheimer’s disease staging. In 2013 35th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 5398-5401). IEEE.

cima.maps.map_parser module

class cima.maps.map_parser.MapParser

Bases: object

A class to read various EM map file types into a Map object instance.

static get_endian(filename: str) → str

Read an MRC map file

Parameters:

filename (str) – Input MRC map file name.

Returns:

endian – Endianness: Little or big

Return type:

str

static readMRC(filename: str) → Map

Read an MRC map file

Parameters:

filename (str) – Input MRC map file name.

Returns:

map – A Map instance containing the data read from MRC map file.

Return type:

Map

static readMRCHeader(filename: str, endian: str = '<') → tuple

Gets the header information from the MRC map file.

Parameters:

• filename (str) – Input MRC map file name.

• endian (str, optional) – Endianness: Little or big

Returns:

header – A tuple containing the MRC header information.

Return type:

tuple

cima.maps.map_spatial_features module

cima.maps.map_spatial_features.DistanceBetweenSegments(map_s1: Map, map_s2: Map, threshold1: float = 0.5, threshold2: float = 0.5) → float

Calculate the distance between the centers of mass of two map instances.

This function computes the distance between the centers of mass of two density map objects, considering only the regions above specified threshold values.

Args: * map_s1: Density Map Object The first density map object. * map_s2: Density Map Object The second density map object. * threshold1 (float, optional): The threshold value for the first map above which to compute the center of mass. Default is 0.5. * threshold2 (float, optional): The threshold value for the second map above which to compute the center of mass. Default is 0.5.

Returns: * float: The distance between the centers of mass of the two map instances.

cima.maps.map_spatial_features.EntanglementBetweenSegments(map_s1: Map, map_s2: Map, threshold1: float = 0.5, threshold2: float = 0.5) → float

Calculate Entanglement of two map instance (within the optimal contour) as define in Nir et al. PlosGen 2018. (Intersection over minor)

Parameters:

• map_s1 (Map) – The first density map object.

• map_s2 (Map) – The second density map object.

• threshold1 (float, optional) – The threshold value for the first map above which to define the surface. Default is 0.5.

• threshold2 (float, optional) – The threshold value for the second map above which to define the surface. Default is 0.5.

Returns:

Entanglement

Return type:

float

cima.maps.map_spatial_features.getSurfaceDistance(map_s1: Map, map_s2: Map, threshold1: float = 0.5, threshold2: float = 0.5) → float

Calculate the distance between the surfaces of two map instances.

This function computes the distance between the surfaces of two density map objects, considering only the regions above specified threshold values. If the two maps intersect, the distance is 0.0.

Parameters:

• map_s1 (Map) – The first density map object.

• map_s2 (Map) – The second density map object.

• threshold1 (float, optional) – The threshold value for the first map above which to define the surface. Default is 0.5.

• threshold2 (float, optional) – The threshold value for the second map above which to define the surface. Default is 0.5.

Returns:

The distance between the surfaces of the two map instances. If the maps intersect, returns 0.0.

Return type:

float

cima.maps.maptomap module

cima.maps.maptomap.Map2Map(m1: Map, m2: Map, c1: float, c2: float, dirin: str, precision: int = 45, number_alternative_fits: int = 100, chimerapath: str = '', runchimera: str = 'Mac', writemx: bool = False, listfit: bool = False) → list | float | None

Map to Map comparison based on Rigid Body fitting.

Parameters:

• m1 (Map) – Density map objects to be compared.

• m2 (Map) – Density map objects to be compared.

• c1 (float) – Optimal contours for the density maps.

• c2 (float) – Optimal contours for the density maps.

• dirin (str) – Working directory.

• precision (int, optional) – Precision to use for the fitting (default is 45).

• number_alternative_fits (int, optional) – Number of fits to perform (default is 100).

• chimerapath (str, optional) – Path to Chimera executable (default is ‘’).

• runchimera (str, optional) – Platform-specific Chimera run command (default is ‘Mac’).

• writemx (bool, optional) – If True, write the rotation matrix (default is False).

• listfit (bool, optional) – If True, return the CCC score for each fit (default is False).

Returns:

If listfit is True, returns a list of CCC scores for each fit. Otherwise, returns the top scoring fit’s CCC score.

Return type:

list | float | None

cima.maps.scoring_functions module

class cima.maps.scoring_functions.ScoringFunctions

Bases: object

A class implementing various scoring functions used in density fitting. Reference: Vasishtan and Topf (2011) Scoring functions for cryoEM density fitting. J Struct Biol 174:333-343.

CCC_map(map_target: Map, map_probe: Map, map_target_threshold: float = 0.0, map_probe_threshold: float = 0.0, mode: int = 1, meanDist: bool = False, cmode: bool = True, overlap_type: str = 'ios', verbose: bool = False) → tuple[float, float]

Calculates the cross-correlation coefficient and overlap between two EMMap instances.

Parameters:

• map_target (Map) – The target map instance to compare.

• map_probe (Map) – The probe map instance to compare.

• map_target_threshold (float, optional) – Threshold for the target map. If not provided, it will be calculated.

• map_probe_threshold (float, optional) – Threshold for the probe map. If not provided, it will be calculated.

• mode (int, optional) – Mode of calculation: - 1: Calculation on the complete map. - 2: Calculation on contoured maps. - 3: Calculation on the mask. Defaults to 1.

• meanDist (bool, optional) – If True, the deviation from the mean will be calculated. Defaults to False.

• cmode (bool, optional) – If True, use the custom CCC calculation method. Defaults to False.

• overlap_type (str, optional) – Type of overlap calculation. Options include: - ‘ios’: Intersection over Smaller volume. - ‘iob’: Intersection over Bigger volume. - ‘iou’: Intersection over Union. Defaults to ‘ios’.

• verbose (bool, optional) – If True, prints additional information during calculation. Defaults to False.

Returns:

• tuple – A tuple containing: - float: Cross-correlation coefficient. - float: Percentage overlap.

• Notes –

  • If the maps cannot be matched, the function returns (-1.0, 0.0).

  • If there is no overlap between the maps, the function returns (-1.0, 0.0).

  • The overlap_type parameter determines the overlap calculation method.

FSC_betweenMaps(map_1, map_2, shellmin, shellmax, step=0.005, c1=0, c2=0, reso=None) → tuple[list[float], list[float]]

Calculate the Fourier Shell Correlation (FSC) between two maps.

This function computes the Fourier Shell Correlation (FSC) between two maps, map_1 and map_2. FSC is used to assess similarity in the frequency domain between two maps, often for structural resolution assessment. The function supports pyfftw (if installed) for efficient Fourier transforms.

Parameters:

• map_1 (Map) – The first map instance.

• map_2 (Map) – The second map instance.

• shellmin (float) – Minimum shell frequency.

• shellmax (float) – Maximum shell frequency.

• step (float, optional) – Frequency step size for FSC calculation. Defaults to 0.005.

• c1 (float, optional) – Unused parameter for compatibility. Defaults to 0.

• c2 (float, optional) – Unused parameter for compatibility. Defaults to 0.

• reso (float, optional) – Resolution cutoff for low-pass filtering. Defaults to None.

Returns:

A tuple containing: - lfreq (list): List of frequencies for each shell. - listC (list): List of FSC values for each shell.

Return type:

tuple

LSF(map_target: Map, map_probe: Map) → float

Calculate the least-squares difference between two map instances.

This function computes the least-squares value between two maps, map_target and map_probe, by taking the difference between the maps’ data, squaring it, and averaging the result. This metric quantifies the similarity between the two maps, with a lower value indicating a closer match.

Parameters:

• map_target (Map) – The target map instance to compare.

• map_probe (Map) – The probe map instance to compare.

Returns:

The computed least-squares value between map_target and map_probe.

Return type:

float

MI(map_target: Map, map_probe: Map, map_target_threshold: float = 0.0, map_probe_threshold: float = 0.0, mode: int = 1, layers1: int = 20, layers2: int = 20, weight: bool = False, cmode: bool = True)

Calculate the mutual information (MI) score between two instances.

This function calculates the mutual information score, a measure of similarity between map_target and map_probe. Mutual information quantifies the amount of shared information between two datasets, making it useful for comparing map regions. The function offers options for using the entire map or only the overlapping region, as well as optional normalization.

Parameters:

• map_target (Map) – The target map instance to compare.

• map_probe (Map) – The probe map instance to compare.

• map_target_threshold (float, optional) – Threshold for contouring map_target. Defaults to 0.0.

• map_probe_threshold (float, optional) – Threshold for contouring map_probe. Defaults to 0.0.

• mode (int, optional) – Calculation mode. 1 for full map, 3 for overlap region. Defaults to 1.

• layers1 (int, optional) – Number of layers (bins) for map_target intensity values. Defaults to Sturges’ rule if None.

• layers2 (int, optional) – Number of layers (bins) for map_probe intensity values. Defaults to Sturges’ rule if None.

• weight (bool, optional) – If True, applies normalized MI using Studholme et al.’s method for contour overlap. Defaults to False.

• cmode (bool, optional) – If True, uses a custom C-based implementation for speed. Defaults to True.

Returns:

The mutual information score between map_target and map_probe. Returns None if no overlap exists or calculation fails.

Return type:

float

envelope_score(map_target: Map, primary_boundary: float, structure_instance, norm=True)

Calculate the envelope score between a target Map and a Structure Instances.

Parameters:

• map_target (Map) – Target Map Instance.

• primary_boundary (float) – Value specified is calculated with primary_boundary of the map object.

• structure_instance (StructureInstance) – Structure Instance to compare.

• norm (bool, optional) – If True, the score is normalized to a range of [0, 1]. Defaults to True.

Returns:

Envelope score. If norm=True, the score is normalized; otherwise, it is a raw score.

Return type:

float

envelope_score_map(map_target: Map, map_probe: Map, map_target_threshold: float = 0, map_probe_threshold: float = 0, norm: bool = True)

Calculate the envelope score between two map instances.

This function calculates an envelope score, a measure of similarity between map_target and map_probe based on thresholded binary maps. It computes the overlap between the thresholded regions of the two maps to determine how well they match. Optionally, the score can be normalized.

Parameters:

• map_target (Map) – The target map instance.

• map_probe (Map) – The probe map instance.

• map_target_threshold (float, optional) – Threshold value for the target map. If set to 0, the threshold is calculated using calculate_map_threshold. Defaults to 0.

• map_probe_threshold (float, optional) – Threshold value for the probe map. If set to 0, the threshold is calculated using calculate_map_threshold. Defaults to 0.

• norm (bool, optional) – If True, the score is normalized to a range of [0, 1]. Defaults to True.

Returns:

The envelope score. If norm=True, the score is normalized; otherwise, it is a raw score.

Return type:

float

static getMapsOverlap(map_target: Map, map_probe: Map, map_target_threshold: float = 0.0, map_probe_threshold: float = 0.0, overlap_type: str = 'ios', verbose: bool = False) → float

Calculate the overlap between two maps based on a specified threshold and overlap type.

Parameters:

• map_target (Map) – The target map object containing the fullMap attribute.

• map_probe (Map) – The probe map object containing the fullMap attribute.

• map_target_threshold (float, optional) – Threshold for the target map. Defaults to 0.0.

• map_probe_threshold (float, optional) – Threshold for the probe map. Defaults to 0.0.

• overlap_type (str, optional) – Type of overlap calculation. Defaults to ios. Options include: • ‘ios’ (Intersection over Smaller): Calculates overlap as the intersection volume divided by the smaller volume. • ‘iob’ (Intersection over Bigger): Calculates overlap as the intersection volume divided by the larger volume. • ‘iou’ (Intersection over Union): Calculates overlap as the intersection volume divided by the union of the two volumes. • ‘iofirst’: Uses the volume of map_target as the denominator. • ‘iosecond’: Uses the volume of map_probe as the denominator.

• verbose (bool, optional) – If True, prints additional information. Defaults to False.

• Returns

• -------

• float – The percentage overlap between the two maps.

get_partial_DLSF(map_target: Map, map_probe: Map, num_of_points: int) → float

Calculate the DLSF score between two Map instances. The DLSF is similar to the LSF; whereas the LSF compares absolute density values, the DLSF compares the difference between pairs of values.

Parameters:

• map_target (Map) – The target Map instance to compare.

• map_probe (Map) – The probe Map instance to compare.

• num_of_points (int) – Number of significant points.

Returns:

DLSF score between map_target and map_probe. Returns a message if the maps cannot be matched.

Return type:

float

laplace_CCC(map_target: Map, map_probe: Map, prefil_target: bool = False, prefil_probe: bool = False) → float

Calculate the Laplacian cross-correlation (CCC) score between two Map instances.

This method calculates the Laplacian cross-correlation between map_target and map_probe, based on the approach described by Chacon and Wriggers (2002). The Laplacian CCC score quantifies the similarity between two maps after applying a Laplacian filter to each map, enhancing edge features for better comparison. The maps can optionally be pre-filtered.

Parameters:

• map_target (Map) – The target map instance to compare.

• map_probe (Map) – The probe map instance to compare.

• prefil_target (bool, optional) – Indicates whether the target map has already been Laplacian-filtered. Defaults to False.

• prefil_probe (bool, optional) – Indicates whether the probe map has already been Laplacian-filtered. Defaults to False.

Returns:

The Laplacian cross-correlation score between map_target and map_probe.

Return type:

float

normal_vector_score(map_target: Map, map_probe: Map, primary_boundary: float, secondary_boundary: float = 0.0, filter_type: str = None)

Calculate the Normal Vector Score between two Map surfaces.

This method calculates the Normal Vector Score between map_target and map_probe, comparing the normal vectors of surfaces defined by a primary and secondary boundary. The algorithm is based on the 3SOM algorithm by Ceulemans and Russell (2004), which evaluates surface alignment using normal vectors.

Parameters:

• map_target (Map) – The target map instance to compare.

• map_probe (Map) – The probe map instance to compare.

• primary_boundary (float) – Primary threshold value defining the main surface boundary.

• secondary_boundary (float, optional) – Secondary threshold for boundary, defaulting to 0.0.

• filter_type (str, optional) – Filter to apply before calculating normal vectors. Options are: - ‘Sobel’: Sobel filter for edge detection - ‘Laplace’: Laplace filter for edge detection - ‘Minimum’: Minimum filter for surface points - ‘Mean’: Mean filter for surface smoothing - Defaults to None.

Returns:

The Normal Vector Score, a measure of alignment between the map surfaces. Returns None if no points are available to score.

Return type:

float

cima.maps.structure_blurrer module

class cima.maps.structure_blurrer.StructureBlurrer

Bases: object

A class to generates a density map from a structure instance.

gaussian_blur(prot, resolution: float, densMap: Map | None = None, sigma_coeff: float = 0.356, normalise: bool = True, filename: str = 'None') → Map

Returns a Map instance based on a Gaussian blurring of a protein. The convolution of atomic structures is done in reciprocal space.

Parameters:

• prot (Structure) – the Structure instance to be blurred.

• resolution (float) – the resolution, in Angstroms, to blur the protein to.

• densMap (Map or None) – None to build a Map with dimensions based on the protein, or a Map instance to be used as a template.

• sigma_coeff (float) – the sigma value (multiplied by the resolution) that controls the width of the Gaussian. Default value is 0.356. Other values used : - 0.187R corresponding with the Gaussian width of the Fourier transform falling to half the maximum at 1/resolution, as used in Situs (Wriggers et al, 1999); - 0.225R which makes the Fourier transform of the distribution fall to 1/e of its maximum value at wavenumber 1/resolution, the default in Chimera (Petterson et al, 2004) - 0.356R corresponding to the Gaussian width at 1/e maximum height equaling the resolution, an option in Chimera (Petterson et al, 2004); - 0.425R the fullwidth half maximum being equal to the resolution, as used by FlexEM (Topf et al, 2008); - 0.5R the distance between the two inflection points being the same length as the resolution, an option in Chimera (Petterson et al, 2004); - 1R where the sigma value simply equal to the resolution, as used by NMFF (Tama et al, 2004).

• filename (str, optional) – Output name of the map file, by default None.

Returns:

A Map instance based on a Gaussian blurring of the input protein.

Return type:

Map

gaussian_blur_box(prot, resolution, box_size_x, box_size_y, box_size_z, sigma_coeff: float = 0.356, normalise: bool = True, filename: str = 'None') → Map

Returns a Map instance based on a Gaussian blurring of a protein. The convolution of atomic structures is done in reciprocal space.

Parameters:

• prot (Structure) – the Structure instance to be blurred.

• resolution (float) – the resolution, in Angstroms, to blur the protein to.

• box_size_x (float) – x dimension of map box in Angstroms.

• box_size_y (float) – y dimension of map box in Angstroms.

• box_size_z (float) – z dimension of map box in Angstroms.

• sigma_coeff (float, optional) – the sigma value (multiplied by the resolution) that controls the width of the Gaussian. Default values is 0.356. Other values used : - 0.187R corresponding with the Gaussian width of the Fourier transform falling to half the maximum at 1/resolution, as used in Situs (Wriggers et al, 1999); - 0.225R which makes the Fourier transform of the distribution fall to 1/e of its maximum value at wavenumber 1/resolution, the default in Chimera (Petterson et al, 2004) - 0.356R corresponding to the Gaussian width at 1/e maximum height equaling the resolution, an option in Chimera (Petterson et al, 2004); - 0.425R the fullwidth half maximum being equal to the resolution, as used by FlexEM (Topf et al, 2008); - 0.5R the distance between the two inflection points being the same length as the resolution, an option in Chimera (Petterson et al, 2004); - 1R where the sigma value simply equal to the resolution, as used by NMFF (Tama et al, 2004).

• normalise (bool, optional) – Whether to normalise the map after blurring. Default is True.

• filename (str, optional) – Output name of the map file. Default is None.

Returns:

A Map instance based on a Gaussian blurring of the input protein, with specified box dimensions.

Return type:

Map

gaussian_blur_real_space(prot, resolution: float, densMap: Map | None = None, sigma_coeff: float = 0.356, normalise: bool = True, filename: str = 'None') → Map

Returns a Map instance based on a Gaussian blurring of a protein. The convolution of atomic structures is done in real space

Parameters:

• prot (Structure) – the Structure instance to be blurred.

• resolution (float) – the resolution, in Angstroms, to blur the protein to.

• densMap (Map | None, optional) – None to build a Map with dimensions based on the protein, or a Map instance to be used as a template.

• sigma_coeff (float, optional) – the sigma value (multiplied by the resolution) that controls the width of the Gaussian. Default values is 0.356. Other values used: - 0.187R corresponding with the Gaussian width of the Fourier transform falling to half the maximum at 1/resolution, as used in Situs (Wriggers et al, 1999); - 0.225R which makes the Fourier transform of the distribution fall to 1/e of its maximum value at wavenumber 1/resolution, the default in Chimera (Petterson et al, 2004) - 0.356R corresponding to the Gaussian width at 1/e maximum height equaling the resolution, an option in Chimera (Petterson et al, 2004); - 0.425R the fullwidth half maximum being equal to the resolution, as used by FlexEM (Topf et al, 2008); - 0.5R the distance between the two inflection points being the same length as the resolution, an option in Chimera (Petterson et al, 2004); - 1R where the sigma value simply equal to the resolution, as used by NMFF (Tama et al, 2004).

• filename (str, optional) – output name of the map file.

Returns:

A Map instance based on a Gaussian blurring of the input protein, with convolution done in real space.

Return type:

Map

gaussian_blur_real_space_box(prot, resolution: float, box_size_x: float, box_size_y: float, box_size_z: float, sigma_coeff: float = 0.356, normalise: bool = True, filename: str = 'None')

Returns a Map instance based on a Gaussian blurring of a protein. The convolution of atomic structures is done in real space

Parameters:

• prot (Structure) – the Structure instance to be blurred.

• resolution (float) – the resolution, in Angstroms, to blur the protein to.

• box_size_x (float) – x dimension of map box in Angstroms.

• box_size_y (float) – y dimension of map box in Angstroms.

• box_size_z (float) – z dimension of map box in Angstroms.

• sigma_coeff (float) – the sigma value (multiplied by the resolution) that controls the width of the Gaussian. Default values is 0.356. Other values used : - 0.187R corresponding with the Gaussian width of the Fourier transform falling to half the maximum at 1/resolution, as used in Situs (Wriggers et al, 1999); - 0.225R which makes the Fourier transform of the distribution fall to 1/e of its maximum value at wavenumber 1/resolution, the default in Chimera (Petterson et al, 2004); - 0.356R corresponding to the Gaussian width at 1/e maximum height equaling the resolution, an option in Chimera (Petterson et al, 2004); - 0.425R the fullwidth half maximum being equal to the resolution, as used by FlexEM (Topf et al, 2008); - 0.5R the distance between the two inflection points being the same length as the resolution, an option in Chimera (Petterson et al, 2004); - 1R where the sigma value simply equal to the resolution, as used by NMFF (Tama et al, 2004).

• normalise (bool, optional) – Whether to normalise the map after blurring. Default is True.

• filename (str, optional) – output name of the map file.

Returns:

A Map instance based on a Gaussian blurring of the protein.

Return type:

Map

get_coordinates(structure_instance) → tuple[dict, dict]

Returns flat indices of the pixels occupied by each residue in a chain.

Parameters:

structure_instance (Structure) – Structure instance of the model.

Returns:

A tuple containing two dictionaries: - dict_chain_indices: A dictionary mapping chain identifiers to residue indices. - dict_chain_CA: A dictionary mapping chain identifiers to CA atom coordinates.

Return type:

tuple[dict, dict]

get_indices(structure_instance, emmap: Map, res_map: float, sim_sigma_coeff: float = 0.187, sigma_thr: float = 2.0, atom_sel=None) → tuple[dict, dict, dict]

Returns flat indices of the pixels occupied by each residue in a chain.

Parameters:

• structure_instance (Structure) – Structure instance of the model.

• emmap (Map) – Map instance the model is to be placed on.

• res_map (float) – Resolution of the map

• sim_sigma_coeff (float) – Sigma factor used for blurring

• sigma_thr (float) – Sigma threshold

• atom_sel (str, optional) – Atom selection criteria

Returns:

A tuple containing three dictionaries: - dict_chain_indices: A dictionary mapping chain identifiers to residue indices. - dict_chain_res: A dictionary mapping chain identifiers to residue numbers. - dict_res_dist: A dictionary mapping residue numbers to their CA atom coordinates.

Return type:

tuple[dict, dict, dict]

hard_sphere(prot, resolution: float, densMap: Map | None = None, normalise: bool = True) → Map

Returns a Map instance based on a Hard Sphere model of a protein. Usefull for rigid fitting (Topf et al, 2008)

Parameters:

• prot (Structure) – the Structure instance to be blurred.

• resolution (float) – the resolution, in Angstroms, to blur the protein to.

• densMap (Map | None, optional) – None to build a Map with dimensions based on the protein, or a Map instance to be used as a template.

Returns:

A Map instance based on a Hard Sphere model of the input protein.

Return type:

Map

hard_sphere_box(prot, resolution: float, box_size_x: float, box_size_y: float, box_size_z: float, normalise: bool = True, filename: str = 'None') → Map

Returns a Map instance based on a Hard Sphere model of a protein. Usefull for rigid fitting (Topf et al, 2008)

Parameters:

• prot (Structure) – the Structure instance to be blurred.

• resolution (float) – the resolution, in Angstroms, to blur the protein to.

• box_size_x (float) – x dimension of map box in Angstroms.

• box_size_y (float) – y dimension of map box in Angstroms.

• box_size_z (float) – z dimension of map box in Angstroms.

• normalise (bool, optional) – Whether to normalise the map after blurring. Default is True.

• filename (str, optional) – output name of the map file.

Returns:

A Map instance based on a Hard Sphere model of the input protein, with specified box dimensions.

Return type:

Map

make_atom_overlay_map(densMap: Map, prot) → Map

Returns a Map instance with atom masses superposed on it.

Parameters:

• densMap (Map) – an empty (all densities zero) Map instance to superpose the atoms onto.

• prot (Structure) – a Structure instance.

Returns:

A Map instance with atom masses superposed on it.

Return type:

Map

make_atom_overlay_map1(densMap: Map, prot) → Map

Returns a Map instance with atom locations recorded on the nearest voxel with a value of 1.

Parameters:

• densMap (Map) – an empty (all densities zero) Map instance to superpose the atoms onto.

• prot (Structure) – a Structure instance.

Returns:

A Map instance with atom locations recorded on the nearest voxel with a value of 1.

Return type:

Map

make_atom_overlay_mapB(densMap: Map, prot) → Map

Returns a Map instance with atom masses superposed on it.

Parameters:

• densMap (Map) – an empty (all densities zero) Map instance to superpose the atoms onto.

• prot (Structure) – a Structure instance.

Returns:

A Map instance with atom masses superposed on it.

Return type:

Map

mapGridPosition(densMap: Map, atom) → tuple[float, float, float, float] | int

Returns the index of the nearest pixel to an atom, and atom mass (4 values in list form).

Parameters:

• densMap (Map) – Map instance the atom is to be placed on.

• atom (Atom) – Atom instance.

Returns:

A tuple of the form (x_pos, y_pos, z_pos, atom.mass) where x_pos, y_pos and z_pos are the indices of the nearest pixel to the atom in the map grid, and atom.mass is the mass of the atom. If the position of the atom is outside the bounds of the map, returns 0.

Return type:

tuple[float, float, float, float] | int

mapGridPositions(densMap: Map, atom, gridtree: KDTree, res_map: float, sim_sigma_coeff: float = 0.187, sigma_thr: float = 2.0) → list[int]

Returns the indices of the nearest pixels to an atom as a list.

Parameters:

• densMap (Map) – Map instance the atom is to be placed on.

• atom (Atom) – Atom instance.

• gridtree (KDTree) – KDTree of the map coordinates (absolute cartesian)

• res_map (float) – Map resolution

• sim_sigma_coeff (float, optional) – Coefficient for the Gaussian sigma calculation.

• sigma_thr (float, optional) – Threshold for the sigma value.

Returns:

A list of indices of the nearest pixels to the atom in the map grid that are within the specified sigma threshold.

Return type:

list[int]

mapGridPositions_vdw(densMap: Map, atom, gridtree) → tuple[list[int], tuple[int, int, int]]

Returns the index of the nearest pixel to an atom, and atom mass (4 values in list form).

Parameters:

• densMap (Map) – Map instance the atom is to be placed on.

• atom (Atom) – Atom instance.

• gridtree (KDTree) – KDTree of the map coordinates (absolute cartesian).

Returns:

A tuple containing a list of points within the van der Waals radius and the grid position of the atom.

Return type:

tuple

maptree(densMap: Map) → KDTree

Returns the KDTree of coordinates from a map grid.

Parameters:

densMap (Map) – Map instance the atom is to be placed on.

Returns:

KDTree of the map coordinates (absolute cartesian).

Return type:

KDTree

model_tree(list_coord1: list, distpot: float = 6.0, list_coord2: list = []) → list

Returns a list of neighboring points within a specified distance potential using KDTree.

protMap(struct, apix: float, resolution: float | None = None, filename: str = 'None') → Map

Returns an Map instance sized and centred based on the atomic structure.

Parameters:

• struct (Structure) – the Structure instance.

• apix (float) – nm per pixel for the Map to be outputted.

• resolution (float | None, optional) – Target precision SR of the outputted map.

• filename (str, optional) – output name of the map file.

Returns:

A Map instance

Return type:

Map

protMapBox(struct, apix, resolution, box_size_x, box_size_y, box_size_z, filename) → Map

Create a Map instance sized and centered based on the atomic structure.

Parameters:

• struct (Structure) – the Structure instance.

• apix (float) – nm per pixel for the output Map.

• resolution (float) – the resolution, in Angstroms, to blur the protein to.

• box_size_x (float) – x dimension of output map box in Angstroms.

• box_size_y (float) – y dimension of output map box in Angstroms.

• box_size_z (float) – z dimension of output map box in Angstroms.

• filename (str) – output name of the map file.

Returns:

A Map instance

Return type:

Map

cima.maps.vq module

cima.maps.vq.VQ(D, n, epochs, alpha0=0.5, lam0=False)

Clusters a set of vectors (D) into a number (n) of codebook vectors

cima.maps.vq.get_VQ_points(emmap: Map, threshold: float, noOfPoints: int, epochs: int, lap_fil: bool = True) → list

Returns a list of VQ points for a given map, threshold and number of points. The VQ points are returned as a list of Vector objects.

Parameters:

• emmap (Map) – Map (to be clustered) instance.

• threshold (float) – voxels with density above this value are used in the VQ run.

• noOfPoints (int) – num of VQ points to output.

• epochs (int) – num of iterations to run the algorithm

• lap_fil (bool) – True if you want to Laplacian filter the map first, False otherwise. Note that filtering the map will change the density values of the map, which is relevant for the threshold parameter.

Returns:

A list of Vector objects representing the VQ points.

Return type:

list

cima.maps.vq.map_points(emmap, threshold)