KAHIBARO
14.7. Actor Filters
Table of Contents
Particle filters
Actor filters in GATE let you decide which events an actor will record, instead of saving everything. This reduces file size, speeds up analysis, and focuses results on what you actually need.
A particle filter selects particles by type before the actor records anything. In practice you attach a filter object to an actor, and the actor ignores all hits or steps that do not pass the filter.
In OpenGATE Python you typically configure a particle filter by setting a list of allowed particle names. For example you can keep only gammas for an energy deposition actor that is attached to a detector crystal, so that electrons or other secondaries are ignored. Or you can keep only protons in a dose actor for a proton therapy phantom.
The particle names follow Geant4 conventions, such as "gamma", "e-", "e+", "proton", "neutron", or ion names. The filter logic is usually inclusive, which means the actor records an event if its particle type is in the allowed list and ignores all others. Multiple actors can use different particle filters in the same simulation, which lets you record, for example, one energy map for electrons and another for photons in the same geometry.
Particle filters are commonly used with:
The simulation statistics actor, to count separate statistics for gammas, electrons, or protons.
Energy deposition and dose actors, to separate contributions by particle type.
Phase space and fluence actors, to restrict output to the clinically relevant particles such as 511 keV photons in PET or primary protons in therapy.
When you design a filter, remember that many dose and detector effects come from secondary particles. If you restrict too tightly to primaries only, you may underestimate dose or misinterpret detector response.
Energy filters
Energy filters let an actor record only events where the particle energy or deposited energy lies within a specified range. This is similar in spirit to an energy window in detector digitization, but here it acts at the actor level on hits, steps, or scored quantities.
Most energy filters in GATE are based on a lower and an upper energy bound. During the simulation, for each candidate event the filter checks the relevant energy value, and the actor records the event only if it satisfies the configured condition.
There are two common use cases.
First, filtering on kinetic energy, where the filter checks the particle kinetic energy at the point of interaction or at the scoring location. This is useful for phase space or fluence actors if you want to restrict output to certain energy ranges, for example, only near the photopeak in SPECT or only therapeutic proton energies at a specific plane.
Second, filtering on deposited energy, where the filter uses the energy deposited in a step or hit. This is often used with energy deposition or dose actors if you want to suppress small, noise‑like deposits below a threshold or focus on higher energy events.
Energy filters usually specify energies using GATE units, for example $400 \text{ keV}$ or $0.5 \text{ MeV}$. In Python you must multiply by the appropriate unit symbol, such as 400 keV or 0.5 MeV. Forgetting the unit is a frequent source of errors, since raw numbers are interpreted in default Geant4 units, not in keV or MeV.
Important rule: Always specify energy thresholds and windows with explicit GATE units, for example low = 400 keV, high = 650 keV. Never use bare numbers for energies.
Energy filters are particularly powerful when combined with particle filters. For instance, you can create a phase space actor that records only gamma particles and only those in a 511 keV photopeak window, or a proton fluence actor that records only protons above a chosen kinetic energy cutoff. By carefully selecting energy thresholds you can drastically reduce output size while preserving the physics that matters for your application.
Volume filters
Volume filters restrict actor scoring to specific regions of the geometry. Instead of scoring in the entire world, you can target one or more logical or physical volumes, such as a detector crystal array, a phantom, or a region of interest.
In practice a volume filter compares the volume in which a step, hit, or deposition occurs with a list of allowed volumes. If the current volume name matches one of these, the event is kept. Otherwise the actor ignores it. You configure the filter with the exact names you gave your volumes when building the geometry.
There are two common strategies when using volume filters.
The first is to attach a single actor and restrict it to multiple volumes. For example, a dose actor might have a volume filter that includes several patient organs, or all voxels corresponding to a target volume, while excluding everything else.
The second is to create multiple actors with different volume filters. This can, for example, give you separate dose maps for a target and an organ at risk, or separate fluence maps for different detector modules, all in one simulation run.
Volume filters are essential when you combine them with region‑based settings such as production cuts or complex voxelized geometries. They allow you to record detailed results only where needed, while the simulation itself can still transport particles everywhere.
When you set up volume filters, pay attention to how GATE resolves names. Typically, filters use logical or physical volume names, and the matching is exact and case sensitive. If your actor reports empty output, one of the first things to check is that the filter’s volume list matches the geometry names used in the simulation.
Combining volume filters with particle and energy filters gives you very fine control. For example, you might configure a dose actor that only records gamma contributions above a certain energy, and only inside a tumor volume, or a phase space actor that records protons crossing a specific scoring plane at the phantom exit. In this way, actor filters let you tailor simulation output to the precise scientific question you want to answer.
Views: 11