discard_atoms_outside_image

macromol_voxelize.discard_atoms_outside_image(atoms: DataFrame, img_params: ImageParams)

Return only those atoms that will be present in the image.

Parameters:

• atoms – See image_from_atoms(), but only the x, y, and z columns are required. If the radius_A column is specified, it will be used. Otherwise, img_params.max_radius_A must be specified, and every atom will be assumed to have that radius.

• img_params – See image_from_atoms().

Returns:

A copy of the atoms dataframe containing only those rows corresponding to atoms that have some overlap with the image. No changes are made to any of the rows that are returned.

The primary reason to use this function is to save a little bit of time by only calculating columns such as channels and radius_A for those the atoms that need them. When using image_from_atoms(), there’s no way to know which atoms will actually be part of the image. So if any columns need to be calculated, they need to be calculated for every atom. This can be wasteful for large structures, where only a small fraction of the atoms participate in the final image.

This function is typically followed by image_from_all_atoms(), not image_from_atoms(), to avoid needlessly repeating this filtering step. Be careful not to modify the x, y, z, or radius_A columns of the filtered atoms dataframe produced by this function before generating the image. Doing so could move the affected atoms outside the image, meaning that the dataframe would no longer be an accurate listing of the atoms in the image.