xmipp3.protocols.protocol_subtract_projection module

class xmipp3.protocols.protocol_subtract_projection.XmippProtBoostParticles(**kwargs)

Bases: XmippProtSubtractProjectionBase

This protocol tries to boost the frequencies of the particles to imporve them, based on an adjustment on its correspondent projections from a reference volume.

INPUT_PARTICLES = 'input_particles.xmd'

boostingStep()

convertStep()

class xmipp3.protocols.protocol_subtract_projection.XmippProtSubtractProjection(**kwargs)

Bases: XmippProtSubtractProjectionBase

This protocol computes the subtraction between particles and a reference volume, by computing its projections with the same angles that input particles have. Then, each particle and the correspondent projection of the reference volume are numerically adjusted and subtracted using a mask which denotes the region to keep.

INPUT_PARTICLES = 'input_particles.xmd'

convertStep()

subtractionStep()

class xmipp3.protocols.protocol_subtract_projection.XmippProtSubtractProjectionBase(**kwargs)

Bases: EMProtocol

Helper class that contains some Protocol utilities methods used by both XmippProtSubtractProjection and XmippProtBoostParticles.

AI Generated

## Overview

The Subtract Projection protocol subtracts projections of a reference volume from a set of experimental particles.

In single-particle cryo-EM, each particle image corresponds to a projection of the 3D structure in a particular orientation. If the particles already have alignment information, the protocol can project a reference volume using those same orientations and compare each experimental particle with its corresponding reference projection.

This protocol uses that idea to remove, or alternatively keep, selected regions of the particle signal. It is useful when the user wants to focus downstream analysis on a specific part of a complex, remove a dominant region, or generate particles where a chosen structural component has been subtracted.

The protocol can use a circular mask or a 3D protein mask during the numerical adjustment, can optionally use a region-of-interest mask, can take CTF into account, and can use either Fourier or real-space projection.

The main output is a new particle set containing the processed particles and subtraction-related metadata.

## Inputs and General Workflow

The protocol requires:

• a set of particles;

• a reference volume;

• a mask strategy;

• optionally, a region-of-interest mask.

The input particles are first written to Xmipp metadata format. The reference volume is then projected using the orientations stored in the particle set. For each particle, the protocol compares the experimental image with the corresponding projection of the reference volume.

The projection and particle are numerically adjusted, and the selected subtraction or keeping operation is applied. The resulting particles are saved as a new particle stack and read back into Scipion as an output particle set.

The output particles include additional metadata describing the subtraction fit.

## Input Particles

The Particles parameter defines the particle set to be processed.

The particles must have projection-alignment information, because the protocol uses the orientation of each particle to generate the corresponding projection of the reference volume.

The input particles and reference volume must have the same X and Y dimensions, and they must have the same sampling rate. The protocol validates these requirements before running.

This protocol is therefore intended for particles that have already been aligned or refined against a compatible reference.

## Reference Volume

The Reference volume parameter defines the 3D map that will be projected and compared with the particles.

For each particle, the protocol generates the projection of this volume using the particle orientation. This projected reference is then adjusted and used for subtraction or signal keeping.

The reference volume should correspond to the same structure and coordinate system as the input particles. If the reference is shifted, rotated, scaled, or sampled differently from the particles, the subtraction will be unreliable.

## Mask Used for the Adjustment

The Mask parameter controls which region is considered during the numerical adjustment between each particle and its corresponding reference projection.

There are two options:

Circular mask applies a circular mask to every particle.

Protein mask uses a 3D specimen mask indicating the region of the map that should be considered in the analysis.

Pixels outside the selected mask are ignored during the adjustment. This helps avoid fitting the reference projection to solvent, background, or irrelevant regions.

## Circular Mask Radius

The Circular mask radius parameter is used when the mask option is Circular mask.

It defines the radius of the circular mask applied to the particles. The purpose of this mask is to avoid edge artifacts and restrict the comparison to the central particle region.

If the value is -1, the protocol uses half the X dimension of the input particles.

A smaller radius focuses the fit on the central region. A larger radius includes more peripheral density and background.

## Protein Mask

The Mask volume parameter is used when the mask option is Protein mask.

This mask should define the region of the input volume that must be considered during the particle-projection adjustment.

The mask must have the same dimensions and sampling rate as the reference volume. The protocol validates these conditions.

A good mask should include the density that should drive the fit while excluding solvent and irrelevant background. Masks with values in background regions should be avoided when they are not intended to contribute to the analysis.

## ROI Mask

The ROI mask parameter defines the region that the user wants to keep or subtract.

This mask is different from the main fitting mask. The main mask controls the region used for numerical adjustment, while the ROI mask defines the structural region affected by the final operation.

If no ROI mask is provided, the subtraction is performed on the whole particle image.

The ROI mask should correspond to the region of the reference volume that the user wants to remove or preserve. It should avoid including background voxels as part of the region of interest.

## Keep or Subtract

The Mask contains the part to parameter controls how the ROI mask is interpreted.

If Keep is selected, the protocol keeps the region represented by the ROI mask and removes the rest according to the projection-subtraction operation.

If Subtract is selected, the protocol subtracts the region represented by the ROI mask from the particles.

This option determines whether the ROI mask marks the part of the structure to retain or the part to remove.

## Ignore CTF

The Ignore CTF option controls whether CTF effects are considered during the subtraction.

If this option is disabled, the protocol considers CTF information when matching the reference projections to the particles.

If this option is enabled, CTF is ignored. This is appropriate when the input particles have already been CTF corrected or when the user intentionally wants to perform the subtraction without CTF modulation.

Using the wrong CTF setting can produce incomplete or biased subtraction.

## Maximum Resolution

The Maximum resolution parameter defines the highest resolution used in the subtraction calculation, in angstroms.

If the value is -1, the protocol uses its default behavior, described in the help as approximately the sampling divided by square root of 2.

Limiting the maximum resolution can make the subtraction more stable by avoiding high-frequency noise or details not reliably represented by the reference volume.

The value should be greater than 0 if explicitly provided.

## Ignore Particles with Negative beta0 or R2

The Ignore particles with negative beta0 or R2? option controls whether particles with problematic fitting parameters are excluded from the output.

The subtraction procedure estimates numerical parameters describing how the reference projection fits each particle. Particles with negative beta0 or R2 are considered bad particles by the protocol.

When this option is enabled, these particles are not included in the output particle set. Negative beta values also do not contribute to the mean beta when the corresponding mean option is used internally.

This option helps remove particles for which the projection fit is not reliable.

## Projector

The Projector parameter controls how projections of the reference volume are generated.

There are two options:

Fourier projection is faster but may be more prone to artifacts.

Real space projection is slower but more accurate.

The mask is always projected in real space.

For exploratory workflows or large datasets, Fourier projection may be convenient. For more accurate subtraction, real-space projection may be preferable.

## Filter Decay Sigma

The Decay of the filter (sigma) parameter is used with the Fourier projector.

It controls the smoothness of the mask transition. A smoother transition can reduce edge artifacts during projection and subtraction.

This is an advanced parameter. Most users should keep the default unless they observe mask-related artifacts or have a specific reason to tune the filter decay.

## Fourier Padding Factor

The Fourier padding factor parameter is used with the Fourier projector.

It defines how much the volume is zero-padded before generating projections. Padding can improve projection accuracy but increases memory use.

The protocol warns that if the input particles are very large, for example larger than about 750 pixels, users may consider reducing the padding factor to 1 to save RAM.

## Output Particles

The main output is outputParticles.

This output contains the processed particles after projection subtraction or signal keeping. The particles are saved in a new MRC stack and metadata file, then read back into Scipion.

The output particle set preserves input particle information and includes additional Xmipp metadata labels related to the subtraction fit, including:

• subtraction R2;

• beta0;

• beta1;

• beta.

These values can be useful for inspecting how well each particle was explained by the reference projection.

## Interpreting the Output

The output particles should be interpreted as modified images in which a reference-derived projection has been used to remove or preserve selected signal.

This operation depends strongly on the quality of the reference volume, the accuracy of particle orientations, the correctness of the masks, and the CTF setting.

Incomplete subtraction may occur if the reference does not match the particles, if the particles are heterogeneous, if alignments are inaccurate, or if the mask is poorly defined.

Over-subtraction or artifacts may occur if the reference projection is fitted too aggressively or if the ROI mask includes inappropriate regions.

## Practical Recommendations

Use this protocol only with particles that have reliable projection-alignment parameters.

Make sure the particle box size and sampling rate match the reference volume.

Use a reference volume in the same coordinate frame as the input particles.

Use a protein mask when the fitting should focus on the molecular region. Use a circular mask for simpler, central-particle masking.

Define the ROI mask carefully. It should correspond to the region to keep or subtract and should not include background unnecessarily.

Use Ignore CTF only when particles have already been CTF corrected or when CTF-aware subtraction is not desired.

Start with conservative maximum-resolution settings. Avoid relying on noisy high-frequency information for subtraction.

Inspect output particles visually and examine subtraction metadata before using the output for downstream classification or refinement.

## Final Perspective

Subtract Projection is a focused particle-processing protocol for removing or preserving reference-derived signal in aligned particles.

For biological users, its main value is that it allows analysis to focus on a selected region of a larger structure. For example, a dominant stable domain can be subtracted so that variability in another region becomes easier to classify, or a region of interest can be kept while the rest of the particle is suppressed.

The quality of the result depends on accurate alignments, an appropriate reference volume, correct CTF handling, and carefully designed masks.

createOutputStep()