xmipp3.protocols.protocol_particle_pick_consensus module
- class xmipp3.protocols.protocol_particle_pick_consensus.ProtPickingConsensusOutput(value)[source]
Bases:
EnumPossible outputs for particle picking protocols
AI Generated
## Overview
The Picking Consensus protocol combines several particle-picking results and keeps coordinates that are supported by a user-defined level of agreement.
Different particle pickers, or the same picker with different parameters, may select slightly different coordinates. Some picks may be reliable because several methods select the same particle. Other picks may be method-specific and may correspond to false positives, contaminants, weak particles, or borderline cases.
This protocol compares multiple coordinate sets micrograph by micrograph. A coordinate is considered to represent the same particle as another coordinate if the two positions are within a user-defined radius. The protocol then counts how many input pickers support each candidate particle and writes a consensus coordinate set.
The protocol can behave strictly, keeping only particles selected by all pickers, or flexibly, keeping particles selected by one or more pickers. This makes it useful both for cleaning particle sets and for merging complementary picking strategies.
## Inputs and General Workflow
The input is a list of coordinate sets.
Each input coordinate set should correspond to particle picks on the same micrographs, although the protocol can also handle streaming situations where different coordinate sets become available progressively.
For each micrograph, the protocol collects the coordinates from all input coordinate sets. If the input coordinate sets have different sampling rates, their coordinates are rescaled to the sampling rate of the first coordinate set.
The protocol then groups nearby coordinates within the selected consensus radius. Each group receives a number of votes corresponding to how many input coordinate sets contributed a coordinate to that group.
Finally, the protocol keeps only the coordinate groups that satisfy the selected consensus rule and writes them as a new Scipion coordinate set.
## Input Coordinates
The Input coordinates parameter contains the coordinate sets to compare.
These coordinate sets may come from different particle-picking protocols, different picking algorithms, different parameter settings, or manual and automatic picking runs.
The first input coordinate set is used as the main reference for micrograph information, box size, and sampling-rate scaling. The output coordinate set is linked to the micrographs of this first input.
For best results, all input coordinate sets should refer to the same micrographs or to matching micrograph sets. If the input pickers were run on different subsets of micrographs, the protocol processes only the micrographs that are available according to its streaming and readiness logic.
## Consensus Radius
The Radius parameter defines the distance, in pixels, within which two coordinates are considered to correspond to the same particle.
For example, if the radius is 10 pixels, two picks closer than 10 pixels are merged into a single candidate particle. The merged coordinate is updated as a weighted average of the contributing positions.
A small radius is strict. It requires different pickers to place coordinates very close to each other. This may reduce false matches but can also fail to merge picks that clearly correspond to the same particle but are slightly shifted.
A large radius is more permissive. It can merge picks with larger positional differences, but if it is too large it may incorrectly merge nearby distinct particles.
The radius should be chosen according to particle size, picking precision, and typical particle separation. It should normally be smaller than the particle diameter.
## Consensus Number
The Consensus parameter defines how many input coordinate sets must support a particle for it to be included in the output.
If the value is set to -1, the protocol requires support from all input coordinate sets. This corresponds to an AND operation. It is the strictest mode.
If the value is set to 1, a coordinate is accepted if it is selected by at least one input coordinate set. This corresponds to an OR operation. It is the most permissive mode.
Intermediate values allow more flexible behavior. For example, if four picking methods are provided and the consensus value is 3, a particle is accepted if three or more pickers agree on it, depending on the selected consensus mode.
This parameter controls the balance between precision and recall. Strict consensus reduces false positives but may discard true particles missed by some pickers. Flexible consensus recovers more particles but may retain more false positives.
## Consensus Mode
The Consensus mode parameter controls how the number of votes is compared with the consensus number.
If the mode is >=, a particle is accepted if it has at least the selected number of votes. This is the usual and more flexible behavior.
If the mode is =, a particle is accepted only if it has exactly the selected number of votes. This is more specialized and can be useful when the user wants to isolate particles picked by a specific number of methods.
For most workflows, the >= mode is recommended.
## Coordinate Merging
When coordinates from different pickers fall within the consensus radius, the protocol merges them into a single candidate coordinate.
The merged coordinate is computed progressively as an average of the positions that vote for the same particle. This means that the output coordinate may not be exactly equal to any individual input coordinate, but instead represents the central consensus position.
This is useful when different pickers identify the same particle with slightly different centers.
## AND and OR Interpretations
The protocol can be understood in terms of familiar logical operations.
With Consensus = -1, the protocol behaves like an AND operation: a particle is accepted only if all input pickers selected it.
With Consensus = 1 and mode >=, the protocol behaves like an OR operation: a particle is accepted if at least one picker selected it.
Values between these extremes implement majority-like rules. For example, with three input pickers and Consensus = 2, the protocol keeps particles selected by at least two pickers.
These modes allow users to tune how conservative the final coordinate set should be.
## Jaccard Index File
During consensus calculation, the protocol writes a Jaccard-like agreement value for each processed micrograph.
This value summarizes the degree of overlap between the input coordinate sets for that micrograph. It can help identify micrographs where pickers agree well and micrographs where the picking results are inconsistent.
Low agreement may indicate poor micrograph quality, difficult particle appearance, contaminants, low contrast, or strong differences between picking methods.
This file is mainly diagnostic and should be interpreted as a guide to picking agreement rather than as an absolute quality measure.
## Output Consensus Coordinates
The main output is consensusCoordinates, a new SetOfCoordinates.
This output contains the coordinates that satisfy the selected consensus rule. It is linked to the micrographs of the first input coordinate set and uses the box size from that same set.
The consensus coordinate set can be passed to particle extraction protocols in the same way as any other coordinate set.
Depending on the selected consensus parameters, the output may be smaller, similar in size, or larger than the individual input coordinate sets.
## Streaming Behavior
The protocol supports streaming coordinate inputs.
In streaming mode, the protocol waits until coordinates for a micrograph are available from the relevant input coordinate sets before computing consensus for that micrograph. When all input streams are closed, it processes any remaining available micrographs and closes the output stream.
This makes the protocol suitable for automated pipelines where particle picking results are produced progressively by different pickers.
## Practical Recommendations
Use this protocol when you have several picking results and want to combine them in a controlled way.
For a conservative cleaned set, use Consensus = -1, requiring all pickers to agree. This can reduce false positives but may lose true particles.
For a permissive merged set, use Consensus = 1 with mode >=. This keeps any particle selected by at least one picker, but later cleaning by particle screening or 2D classification becomes more important.
For a balanced strategy, use a majority rule, such as requiring 2 out of 3 pickers or 3 out of 4 pickers.
Choose the consensus radius carefully. It should reflect expected picking uncertainty but should not be so large that nearby particles are merged.
Inspect the output coordinates visually on representative micrographs. This is especially important when combining pickers with very different behavior.
Use the Jaccard agreement information to identify micrographs where picking methods disagree strongly.
## Final Perspective
Picking Consensus is a coordinate-combination and quality-control protocol. It does not pick particles directly. Instead, it integrates the results of several picking methods or parameter settings and produces a coordinate set based on their agreement.
For biological users, this is useful because no single picker is perfect. Consensus can help reduce method-specific false positives, recover robust particles, and create more reliable coordinate sets for extraction.
The protocol is most effective when the input pickers are complementary and when the consensus radius and voting threshold are chosen according to the particle size and the desired strictness of the workflow.
- consensusCoordinates = <class 'pwem.objects.data.SetOfCoordinates'>
- class xmipp3.protocols.protocol_particle_pick_consensus.XmippProtConsensusPicking(**args)[source]
Bases:
ProtParticlePickingProtocol to estimate the agreement between different particle picking algorithms. The protocol takes several Sets of Coordinates calculated by different programs and/or different parameter settings. Let’s say: we consider N independent pickings. Then, a coordinate is considered to be a correct particle if M pickers have selected the same particle (within a radius in pixels specified in the form).
If you want to be very strict, then set M=N; that is, a coordinate represents a particle if it has been selected by all particles (this is the default behaviour). Then you may relax this condition by setting M=N-1, N-2, …
If you want to be very flexible, set M=1, in this way it suffices that 1 picker has selected the coordinate to be considered as a particle. Note that in this way, the cleaning of the dataset has to be performed by other means (screen particles, 2D and 3D classification, …).
- FN_PREFIX = 'consensusCoords_'
- outputName = 'consensusCoordinates'
- xmipp3.protocols.protocol_particle_pick_consensus.consensusWorker(coords, consensus, consensusRadius, posFn, jaccFn=None, mode=0)[source]
- Worker for calculate the consensus of N picking algorithms of
M_n coordinates each one.
coords: Array of N numpy arrays of M_n coordinates each one. consensus: Minimum number of votes to get a consensus coordinate consensusRadius: Tolerance to see two coordinates as the same (in pixels) posFn: Where to write the consensus coordinates jaccFN: Where to write the Jaccard index per micrograph