```{image} ../../src/orangecontrib/ewoks3dxrd/icons/filter-invert.svg
:alt: Intensity Filter Widget Icon
:class: widget-title-icon
```
# Intensity Filter Widget
The Intensity Filter widget allows users to down-select diffraction peaks based on their scattering strength. 

## Functionality
This widget allows you to:
1. **Normalize Intensity:** Calculate a filtered intensity metric by combining raw sum intensity with a reciprocal distance ($ds$​) correction.
2. **Threshold Peaks:** Apply a fractional cutoff to keep only the most significant reflections.
3. **Visualize the Cutoff:**  Compare the distribution of all peaks against those that pass the intensity filter in a real-time plot.

## User Interface
![Image showing the initial state of the intensity filtering widget](../_static/tuto/initial_intensity_filtering.png)

## Control Panel
These two parameters work together to define which peaks are "strong enough" to be kept:
1. **Intensity Fraction** (intensity_frac): A percentile-based threshold (between 0.0 and 1.0). 
    It defines the global cutoff for the normalized intensity metric.
    * **Example:** A value of 0.95 will filter out the weakest peaks, retaining only the top 5% of the normalized signal.
    * **Visual Synchronization:** The Intensity Fraction and the **Elbow Curve** marker are dynamically synced. 
    Adjusting the numerical value will move the marker on the plot, and dragging the marker will update the numerical fraction.
    * **Interaction:** Moving the marker allows you to visually select the saturation threshold of the intensity orders.

2. **Thermal Factor:** This parameter adjusts the filtering strength relative to the reciprocal distance ($ds$​).
    * **Low values:** Treat peaks at low and high $ds$​ similarly.
    * **High values:** Increase the "penalty" for peaks at high $ds​$, 
        effectively allowing you to filter weak intensity more 
        aggressively at lower rings while being more "mild" or permissive 
        at higher rings where signal naturally weakens.
    * **Default Value**: 0.2

## Execution Control

```{include} ./execution_filtering.md
```

## Example Usage
1. **Connect or Load:** Connect the widget to a Lattice Filter output or manually browse to a Nexus file containing a filtered data group.
2. **Initial Observation:** Observe the blue distribution (unfiltered peaks) in the scatter plot.
3. **Set Global Cutoff:** Adjust the Intensity Fraction to set your baseline noise floor (e.g., 0.98).
4. **Refine with Thermal Factor:** Adjust the Thermal Factor to fine-tune the filter across the rings. 
    Use higher values if you find that you are losing too many valid peaks at high ds​ compared to the low $ds$​ region.
5. **Execute:** Click Filter Peaks. The red points will indicate the peaks that passed the filter.


![Image showing the intensity filtering widget after task completion](../_static/tuto/intensity_filtering.png)