Masks basics

Masks are maps that are used in the alignment operation during subtomogram averaging and classification, where they are part of the required inputs. Masks are treated as as 3d numpy.arrays objects in the same way as maps, and they are loaded and saved with the same file extensions as maps.

Masks can be distinguished in binary masks and masks with smooth edges:

• In binary masks, voxels have only 0 and 1 values (e.g. masks from segmentations);

• In masks with soft edges, voxels have values from 0 to 1. This can be accomplished applying a Gaussian filter to the mask.

Work with masks: Basic examples

In the following section, some examples of how to work with masks are provided. For a complete list of functions, please refer to the cryomask module in the API reference. NOTE: For all the functions displayed, it is assumed that the cryomask module is imported:

import cryocat
from cryocat import cryomask

Generate a mask

To create a mask different options are available. Thee most common are illustrated below:

• Spherical mask: This is accomplished via the spherical_mask() function.

sphere_mask = cryomask.spherical_mask(30, center= (20,15,15), radius=5) #this creates a spherical, binary hard-edge mask in a box of 30x30x30 voxels, centered on (20,15,15) and a radius of 5 voxels
sphere_mask = cryomask.spherical_mask((20,25,20), radius=5, gaussian=1, gaussian_outwards=False) #this creates a spherical, soft-edge mask in a box of 20x25x20 voxels with a Gaussian filter applied with sigma value 1 centered around the sphere surface

• Cylindrical mask: This is accomplished via the cylindrical_mask() function.

cylinder_mask = cryomask.cylindrical_mask((20,40,40), radius=2, height=4, center=None, gaussian=0.4, gaussian_outwards=True, angles=(5,10,0), output_name = '/path/to/mask_r2_h4_g0-4.em') #this creates a cylindrical mask with a Gaussian filter outward from the mask surface, centered in a box of 20x40x40 voxels, with a radius of 2 voxels, a height of 4 voxels, and a Gaussian filter with sigma value 0.4 applied to the mask surface. The mask is rotated by 5 degrees around the x-axis and 10 degrees around the y-axis and it is saved in the specified path

• Ellipsoid mask: This is accomplished via the ellipsoid_mask() function.

ellips_mask = cryomask.ellipsoid_mask(40, radii=(5,15,10)) #this creates an ellipsoid hard-edge mask in a box of 40x40x40 voxels with radii of 5, 15 and 10 voxels

• Tight mask: This is accomplished via the map_tight_mask() function and requires an input map from subtomogram averaging or single particle analysis. This kind of mask is usually required to compute the FSC curve.

tight_mask = cryomask.map_tight_mask(input_map='/path/to/sta_or_spa_map.em', dilation_size=2, output_name='/path/to/tight_mask.em') #this will create a mask from the imput map by performing 2 iterations of dilation to extend the map
tight_mask = cryomask.map_tight_mask(input_map='/path/to/sta_or_spa_map.em', gaussian= 3, gaussian_outwards=True, output_name='/path/to/tight_mask.em') #this will create a mask from the imput map by applying a Gaussian filter with sigma value 3 centered on the surface of the map to extend the map

Shell masks

There is the possibility of creating shell masks with either spherical or ellipsoidal shape and desired shell thickness. The fucntions available for this purpose are ellipsoidal_shell_mask() and spherical_shell_mask().

sphere_shell = cryomask.spherical_shell_mask(40, 10, radius=15, gaussian=1) #this creates a spherical shell mask in a box of 40x40x40 voxels with a radius of 15 voxels and a thickness of 10 voxels. A Gaussian filter with sigma value 1 is applied to the mask surface
ellipsoidal_shell = cryomask.ellipsoid_shell_mask(50, 5, (10,20,10), angles=(5,10,10), output_name='/path/to/ellipsoidal_shell.em') #this creates an ellipsoidal shell mask in a box of 50x50x50 voxels with radii of 10, 20 and 10 voxels in the x-axis, y-axis and z-axis, respectively, and a thickness of 5 voxels. The mask is rotated by 5 degrees around the x-axis, 10 degrees around the y-axis and 10 degrees around the z-axis and it is saved in the specified path

In addition, the generate_mask() function can be used to generate mask of the shape and dimensions specified in the mask name passed to the function. The string patterns that are handled are described in the table below:

String	Description
sphere_rR	spherical mask with radius R
cylinder_rR_hH	cylindrical mask with radus R and height H
ellipsoid_rxRX_ryRY_rzRZ	ellipsoidal mask with radii RX on the x dimension, RY on the y dimension and RZ on the z direction
s_shell_rR_sS	spherical shell mask with radius R and shell thickness S
e_shell_rxRX_ryRY_rzRZ_sS	ellipsoidal shell mask with radii RX on the x dimension, RY on the y dimension and RZ on the z direction and shell thickness S

Some examples:

sphere_mask = cryomask.generate_mask('sphere_r20', mask_size=60) #this will create a sherical mask centered in a box of 60x60x60 pixels, with a radius of 20 pixels
sphere_shell_mask = cryomask.generate_mask('s_shell_r20_s10', mask_size=60) #this will create a spherical shell mask centered in a box of 60x60x60 pixels, with a radius of 20 pixels and a shell thickness of 10 pixels

Apply a Gaussian filter

To add a Gaussian filter to a mask, the add_gaussian() function is available. The required arguments are the numpy.ndarray object of the input mask and the standard deviations of the Gaussian filter to apply (sigma).

filtered_mask = cryomask.add_gaussian(my_mask, 1) #apply gaussian filyter to my_mask with sigma=1

Add, subtract and get intersection between masks

• To add two or multiple masks, the union() function is avalable.

• To subtract two or multiple masks, the subtraction() function is available.

In both cases, the masks need to be provided as a list and the order of addition/subtraction will follow the order of the list elements. Examples:

# Combine masks - pass path to maps
mask1 = '/path/to/mask1.em'
mask2 = '/path/to/mask2.em'
combined_mask = cryomask.union([mask1, mask2], output_name='/path/to/combined_mask.em')

# Subtract masks - pass numpy.ndarray objects
from cryocat import cryomap
mask1 = cryomap.read('/path/to/mask1.em')
mask2 = cryomap.read('/path/to/mask2.em')
subtracted_mask = cryomask.subtract([mask1, mask2], output_name='/path/to/subtracted_mask.em')

• To extract the intersection between different masks, the intersection() function is available.

• To combine two or multiple masks and subtract their intersection from the output mask, the difference() fucntion is available.

intersection_mask = cryomask.intersection([mask1, mask2], output_name='/path/to/intersection_mask.em')
difference_mask = cryomask.difference([mask1, mask2, '/path/to/mask3'], output_name='/path/to/difference_mask.em')

Note that the masks that are passed as inputs need to have the same box dimensions. For all the functions illustrated in this section, the values of the final masks are clipped to 0.0 and 1.0. If an output path is provided, the resulting numpy.ndarray object will be written to a file.

Write a mask to file

To write the numpy array object of a mask to a file, the write_out() function is available:

cryomask.write_out(my_mask, 'path/to/my_mask.em')