Metadata-Version: 2.4
Name: ewoksid27
Version: 0.0.1b0
Summary: An Ewoks project
Author-email: ESRF <dau-pydev@esrf.fr>
License: # MIT License
        
        **Copyright (c) 2026 European Synchrotron Radiation Facility**
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of
        this software and associated documentation files (the "Software"), to deal in
        the Software without restriction, including without limitation the rights to
        use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
        the Software, and to permit persons to whom the Software is furnished to do so,
        subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
        COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
        IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
        CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://gitlab.esrf.fr/workflow/ewoksapps/ewoksid27/
Project-URL: Documentation, https://ewoksid27.readthedocs.io/
Project-URL: Repository, https://gitlab.esrf.fr/workflow/ewoksapps/ewoksid27/
Project-URL: Issues, https://gitlab.esrf.fr/workflow/ewoksapps/ewoksid27/issues
Project-URL: Changelog, https://gitlab.esrf.fr/workflow/ewoksapps/ewoksid27/-/blob/main/CHANGELOG.md
Keywords: ewoks
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: ewokscore
Requires-Dist: ewoksxrpd
Requires-Dist: pydantic>=2
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: dev
Requires-Dist: ewoksid27[test]; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: doc
Requires-Dist: ewoksid27[test]; extra == "doc"
Requires-Dist: sphinx>=4.5; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints>=1.16; extra == "doc"
Requires-Dist: pydata-sphinx-theme; extra == "doc"
Requires-Dist: sphinx-copybutton; extra == "doc"
Requires-Dist: ewokssphinx>=2.0; extra == "doc"
Dynamic: license-file

# ewoksid27

Ewoks tasks and workflows for ID27 data processing.

## Multigeometry integration

The packaged `src/ewoksid27/workflows/multigeometry.json` workflow runs:

`PrepareMultiGeometryImages → Integrate1DMultiGeometry → SaveNexusIntegrated`

The saved pattern passes through `ewoksxrpd.tasks.subtract_pattern.SubtractBackgroundPattern`
and `ewoksxrpd.tasks.ascii.SaveNexusPatternsAsAscii`.
Set `save_ascii.output_filename_template` to the ASCII destination (with `%d` for
the pattern index). It writes radial and intensity
columns, plus intensity errors when available, with units and integration settings
in the header.

Preparation averages the frames within each scan, flips vertically, multiplies
by an optional correction map, then sums repeated scans separately for each
geometry in float64. Each group corresponds to one detector y position. The
correction map is flipped as well; masks must already be in calibration
coordinates. Scan inputs may be 2D images or 3D `(frames, height, width)` stacks,
as arrays or data URLs. Set `flip_vertical=False` if images and correction maps already
match the calibration orientation.

```python
from importlib.resources import files
from ewokscore import execute_graph

workflow = files("ewoksid27") / "workflows" / "multigeometry.json"
execute_graph(
    str(workflow),
    inputs=[
        {
            "id": "prepare",
            "name": "image_groups",
            "value": [
                ["center1.h5::/image", "center2.h5::/image"],
                ["border1.h5::/image", "border2.h5::/image"],
            ],
        },
        {
            "id": "prepare",
            "name": "correction_map",
            "value": "correction.npy",
        },
        {
            "id": "integrate",
            "name": "poni_files",
            "value": ["center.poni", "border.poni"],
        },
        {
            "id": "integrate",
            "name": "masks",
            "value": ["center.mask", "border.mask"],
        },
        {
            "id": "integrate",
            "name": "integration_options",
            "value": {
                "nbpt_rad": 500,
                "unit": "q_A^-1",
                "radial_range_min": 0.9,
                "radial_range_max": 17.5,
                "polarization_factor": 0.99,
            },
        },
        {"id": "save", "name": "url", "value": "patterns.h5::/sample"},
        {
            "id": "subtract_background",
            "name": "nxdata_url",
            "value": "patterns.h5::/sample/integrate/integrated",
        },
        {
            "id": "subtract_background",
            "name": "output_nxprocess_url",
            "value": "patterns.h5::/sample/subtract_background",
        },
        {
            "id": "save_ascii",
            "name": "output_filename_template",
            "value": "patterns/sample_%d.dat",
        },
    ],
)
```

Image groups, PONI files and masks use the same geometry order. The correction
map multiplies the signal, unlike a divisive flatfield. Exposure/monitor scaling
and uncertainty propagation through preparation are not inferred. Geometry
integration is sequential by default (`threadpoolsize=0`).

Blissoda should submit the workflow once all scans in a collection are complete.
Run the same workflow for backgrounds, saving to a separate entry. Background
subtraction is included after integration and NeXus saving, before ASCII export.
It is disabled by default, so a background is integrated without subtracting itself.
For sample processing, add these workflow inputs:

```python
({"id": "subtract_background", "name": "enabled", "value": True},)
(
    {
        "id": "subtract_background",
        "name": "background_nxdata_url",
        "value": "background.h5::/sample/integrate/integrated",
    },
)
({"id": "subtract_background", "name": "background_factor", "value": 1.0},)
```

The `ewoksxrpd.tasks.subtract_pattern.SubtractBackgroundPattern` task
subtracts the integrated background and propagates available errors. The original
pattern remains at `/sample/integrate/integrated`; the corrected pattern is saved
at `/sample/subtract_background/integrated` and exported to ASCII. The factor is
manual; monitor or exposure normalization is not inferred. Wait for background
processing to succeed before using its data URL.

The workflow sets `integrate.stack_patterns=True` to save intensity and errors
with shape `(1, radial_bins)`, as required by the reused subtraction task.
The radial axis remains one-dimensional. Use the same radial grid and units for
sample and background; the subtraction task checks shapes and units but does not
compare radial coordinates. Direct integration task calls still return 1D arrays
unless `stack_patterns=True` is supplied.

## Documentation

https://ewoksid27.readthedocs.io/
