Equation Editor for Signals and Images

[PierreRaybaut]

Summary

Add equation editor capabilities to DataLab/Sigima for:

1. Generic mathematical operations between objects — apply user-defined formulas
   combining multiple signals (or images) with arbitrary expressions
   (e.g. (S1 + S2) * S3 / 2 + constant)
2. Object creation from mathematical expression — generate a new signal from
   y = f(x) or a new image from z = f(x, y) using a free-form formula

Currently, DataLab provides only fixed-operator arithmetic (ArithmeticParam:
(obj1 op obj2) × factor + constant with +, -, ×, /) and hardcoded
parametric generators (Gaussian, Sine, Polynomial up to degree 5, etc.).
There is no expression evaluation engine in the codebase.

---

Motivation

• Power users frequently need formulas like (S1 - S2) / (S1 + S2) (normalized
  difference), log10(S1 / S2) (attenuation), or S1 * exp(-S2) that cannot be
  expressed with the current single-operator arithmetic dialog.
• Signal/image creation from arbitrary expressions (y = A * sin(2π·f·x) + B * cos(3π·f·x),
  z = x² + y²) is only possible via macros today. A built-in equation editor would
  make this accessible to all users without scripting.
• Competing tools (Origin, MATLAB, Igor Pro) all provide formula-based operations as
  core features.

---

Design Overview

A. Expression Engine (Sigima layer — sigima.tools.expression)

A safe, sandboxed expression evaluator operating on NumPy arrays, shared by both
use cases. No eval()/exec() — use ast.parse() + whitelist-based AST walker.

Allowed constructs:

• Arithmetic operators: +, -, *, /, **, %, //
• Comparison operators (for masking): >, <, >=, <=, ==, !=
• Ternary-like via np.where: where(condition, a, b)
• Parentheses for grouping
• Numeric literals (int, float, scientific notation)
• Named constants: pi, e, inf, nan
• Math functions: sin, cos, tan, asin, acos, atan, atan2,
  exp, log, log2, log10, sqrt, abs, sign, floor, ceil,
  round, clip, min, max, where, sinc, sinh, cosh, tanh
• Signal/image variable references: S1, S2, ..., Sn (or I1, ..., In)
• Coordinate variables: x (signal), x/y (image)

Forbidden constructs (raise ExpressionError):

• Function calls not in whitelist
• Attribute access (no os.system, __import__, etc.)
• Subscript/index operations (initially; could be added later for ROI)
• Assignments, imports, class/function definitions
• String literals

B. Two Equation Editor Dialogs (DataLab GUI layer)

Dialog	Context	Input	Output
Operation Equation Editor	Operations menu, acts on selected objects	Formula referencing S1..Sn (signals) or I1..In (images)	1 new object
Creation Equation Editor	Create menu, standalone	Formula y = f(x) or z = f(x, y) + domain parameters	1 new object

---

Detailed Implementation Plan

Phase 1 — Expression Engine (sigima.tools.expression)

New module: sigima/tools/expression.py

1.1 Safe AST-based evaluator

class ExpressionEvaluator:
    """Safe mathematical expression evaluator for NumPy arrays.

    Parses the expression once, validates the AST against a whitelist,
    then compiles to a callable for efficient repeated evaluation.

    Args:
        expression: Mathematical expression string
        allowed_names: Set of allowed variable names (e.g. {"S1", "S2", "x"})

    Raises:
        ExpressionError: If expression contains forbidden constructs
    """

    MATH_FUNCTIONS: dict[str, Callable]  # sin, cos, log, etc. → np.sin, np.cos, ...
    CONSTANTS: dict[str, float]          # pi → np.pi, e → np.e, ...

    def __init__(self, expression: str, allowed_names: set[str]) -> None: ...
    def validate(self) -> None: ...       # AST validation pass
    def evaluate(self, variables: dict[str, np.ndarray]) -> np.ndarray: ...

Implementation approach:

1. ast.parse(expression, mode='eval') → get AST
2. Walk AST nodes, reject anything not in whitelist (no ast.Call except
   whitelisted functions, no ast.Attribute, no ast.Import, etc.)
3. Transform AST to replace function names with np.* equivalents
4. compile() the validated AST → code object
5. eval() the compiled code with a restricted __builtins__={} namespace
   containing only whitelisted functions and variables

Alternative considered: numexpr library. Pros: very fast for large arrays,
thread-safe. Cons: limited function set, external dependency, no custom function
support. → Decision: Start with AST approach for maximum flexibility;
optionally add numexpr backend later for performance on large data.

1.2 Expression validation and introspection

def get_variable_names(expression: str) -> set[str]:
    """Extract all variable names referenced in expression."""

def validate_expression(expression: str, allowed_names: set[str]) -> list[str]:
    """Validate expression and return list of error messages (empty if valid)."""

1.3 Unit tests

• Test all whitelisted functions with scalar and array inputs
• Test rejection of forbidden constructs (attribute access, imports, builtins)
• Test error messages for common mistakes (missing operator, unbalanced parens)
• Test with edge cases: division by zero, log of negative, overflow
• Performance benchmark: compare with direct NumPy for 10M element arrays

Files to create:

• sigima/tools/expression.py
• sigima/tests/tools/test_expression.py

---

Phase 2 — Computation Functions (sigima.proc)

2.1 Signal expression operations (sigima.proc.signal.expression)

class SignalExpressionParam(gds.DataSet):
    """Parameters for signal expression operation."""
    expression = gds.StringItem(_("Expression"), default="S1 + S2")

    def generate_title(self) -> str:
        return self.expression

class NewSignalExpressionParam(NewSignalParam):
    """Parameters for creating a signal from expression."""
    expression = gds.StringItem(_("Expression y=f(x)"), default="sin(2*pi*x)")

    def generate_1d_data(self) -> tuple[np.ndarray, np.ndarray]:
        x = np.linspace(self.xmin, self.xmax, self.size)
        evaluator = ExpressionEvaluator(self.expression, {"x", "pi", "e"})
        y = evaluator.evaluate({"x": x})
        return x, y


@computation_function()
def expression_operation(
    src_list: list[SignalObj], p: SignalExpressionParam
) -> SignalObj:
    """Apply user-defined expression to multiple signals.

    Variables S1, S2, ..., Sn reference the input signals' Y data.
    The variable `x` references the X array of the first signal.

    Args:
        src_list: List of input signals
        p: Expression parameters

    Returns:
        Result signal
    """

2.2 Image expression operations (sigima.proc.image.expression)

class ImageExpressionParam(gds.DataSet):
    """Parameters for image expression operation."""
    expression = gds.StringItem(_("Expression"), default="I1 + I2")

class NewImageExpressionParam(NewImageParam):
    """Parameters for creating an image from expression."""
    expression = gds.StringItem(_("Expression z=f(x,y)"), default="x**2 + y**2")
    x0 = gds.FloatItem(_("X₀"), default=0.0)
    y0 = gds.FloatItem(_("Y₀"), default=0.0)
    dx = gds.FloatItem(_("ΔX"), default=1.0, min=0)
    dy = gds.FloatItem(_("ΔY"), default=1.0, min=0)

    def generate_2d_data(self) -> np.ndarray:
        x = np.arange(self.width) * self.dx + self.x0
        y = np.arange(self.height) * self.dy + self.y0
        xx, yy = np.meshgrid(x, y)
        evaluator = ExpressionEvaluator(self.expression, {"x", "y", "pi", "e"})
        return evaluator.evaluate({"x": xx, "y": yy})


@computation_function()
def expression_operation(
    src_list: list[ImageObj], p: ImageExpressionParam
) -> ImageObj:
    """Apply user-defined expression to multiple images.

    Variables I1, I2, ..., In reference the input images' data arrays.
    Variables `x` and `y` reference pixel coordinate arrays.

    Args:
        src_list: List of input images
        p: Expression parameters

    Returns:
        Result image
    """

2.3 Exports and parameters

• Export functions in sigima/proc/signal/__init__.py and sigima/proc/image/__init__.py
• Re-export param classes in sigima/params.py
• Add SignalTypes.EXPRESSION and ImageTypes.EXPRESSION enum values

2.4 Unit tests

• Test expression operations with 2, 3, 5 signals/images
• Test creation from various expressions (trig, polynomial, composite)
• Test error handling (invalid expression, variable count mismatch)
• Test with complex data, NaN, Inf edge cases

Files to create:

• sigima/proc/signal/expression.py
• sigima/proc/image/expression.py
• sigima/tests/signal/test_expression.py
• sigima/tests/image/test_expression.py

Files to modify:

• sigima/proc/signal/__init__.py (add exports)
• sigima/proc/image/__init__.py (add exports)
• sigima/params.py (add param re-exports)
• sigima/objects/signal/creation.py (add EXPRESSION type + param class)
• sigima/objects/image/creation.py (add EXPRESSION type + param class)

---

Phase 3 — GUI Integration (DataLab layer)

3.1 New processing pattern: compute_list_to_1

The existing compute_n_to_1 pattern passes src_list but doesn't expose
individual object references by name. The equation editor needs to let users
reference objects as S1, S2, etc., based on selection order.

Option A (preferred): Extend compute_n_to_1 to pass an ordered list and
let the computation function handle variable assignment internally. The dialog
shows which object maps to which variable (e.g., "S1 = Signal #3 'Spectrum'").

Option B: Create a new compute_list_to_1 pattern that provides a mapping
{name: obj} to the function.

→ Decision: Option A — reuse compute_n_to_1 since expression functions
already receive src_list in order. The dialog simply labels them S1..Sn.

3.2 Expression editor widget (datalab/gui/widgets/expression_editor.py)

A reusable Qt widget providing:

• Text input with syntax highlighting (operators, functions, variables in
  different colors)
• Variable reference panel showing available variables (S1..Sn or x/y)
  with click-to-insert
• Function palette — categorized buttons (Trig, Log/Exp, Comparison, etc.)
  to insert function templates
• Live validation — real-time AST validation with error indicator
• Preview (optional) — small plot showing result preview for signals, or
  thumbnail for images (computed on a downsampled version for responsiveness)

┌─ Expression Editor ──────────────────────────────────┐
│                                                      │
│  ┌─ Formula ───────────────────────────────────────┐ │
│  │ (S1 - S2) / (S1 + S2)                     [▶]   │ │
│  └─────────────────────────────────────────────────┘ │
│  ✓ Expression valid                                  │
│                                                      │
│  ┌─ Variables ──────┐  ┌─ Functions ──────────────┐  │
│  │ S1: Spectrum_A   │  │ sin cos tan asin acos    │  │
│  │ S2: Spectrum_B   │  │ exp log log10 sqrt       │  │
│  │ x : X-axis       │  │ abs sign where clip      │  │
│  │ (click to insert)│  │ pi e                     │  │
│  └──────────────────┘  └─────-────────────────────┘  │
│                                                      │
│  ┌─ Preview (optional) ───────────────────────────┐  │
│  │        ~~~~~~/\~~~~~~                          │  │
│  │  ─────/──────────\─────                        │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
│                               [ OK ]  [ Cancel ]     │
└──────────────────────────────────────────────────────┘

3.3 Operation Equation Editor dialog

Menu location: Operations → Expression... (after Arithmetic...)

Workflow:

1. User selects 1+ objects in the panel
2. Clicks Operations → Expression...
3. Dialog opens showing selected objects as S1, S2, ..., Sn (or I1..In)
4. User types formula referencing these variables
5. Live validation + optional preview
6. On OK → calls expression_operation(src_list, param)
7. Result added to panel

Registration in SignalProcessor.register_operations():

self.register_n_to_1(
    sips.expression_operation,
    _("Expression..."),
    paramclass=SignalExpressionParam,
    icon_name="equation.svg",
)

And in SignalActionHandler.setup_operation_actions():

act = self.action_for("expression_operation")
self.operation_menu.addAction(act)

Same pattern for ImageProcessor and ImageActionHandler.

3.4 Creation Equation Editor

Menu location: Create → From expression... (at the end of the creation list)

Workflow:

1. User clicks Create → From expression...
2. Dialog opens with domain parameters (xmin, xmax, N for signals; width, height, dtype for images) + formula input
3. User types y = f(x) for signals or z = f(x, y) for images
4. Live preview plot
5. On OK → creates object from expression

Integration: Register NewSignalExpressionParam (resp. NewImageExpressionParam)
in the creation enum, so it appears naturally in the Create menu alongside existing
generators.

3.5 Expression history and presets

Store recently used expressions in DataLab's configuration (Conf):

• Last 20 expressions per context (operation vs creation, signal vs image)
• Built-in presets: normalized difference, ratio, weighted sum, etc.
• User-defined presets (save/load)

The expression input widget includes a dropdown showing history and presets.

Files to create:

• datalab/gui/widgets/expression_editor.py

Files to modify:

• datalab/gui/processor/signal.py (register expression operation)
• datalab/gui/processor/image.py (register expression operation)
• datalab/gui/actionhandler.py (add menu entries)
• datalab/gui/newobject.py (handle expression creation params)
• datalab/config.py (expression history config keys)

---

Phase 4 — Remote Control & Macro Support

4.1 Proxy API

Expression operations are automatically available via proxy.calc():

# Multi-signal expression
proxy.select_objects([0, 1, 2])  # Select S1, S2, S3
p = sigima.params.SignalExpressionParam.create(expression="(S1 - S2) / S3")
proxy.calc("expression_operation", p)

# Create signal from expression
from sigima.objects.signal.creation import NewSignalExpressionParam
p = NewSignalExpressionParam.create(
    expression="sin(2*pi*x) + 0.5*sin(6*pi*x)",
    size=1000, xmin=0, xmax=1
)
proxy.add_signal_from_param(p)  # or proxy.call_method("new_object", p)

4.2 Convenience methods (optional)

Add shortcut methods to BaseProxy:

def calc_expression(
    self, expression: str, object_indices: list[int] | None = None
) -> None:
    """Evaluate expression on selected objects."""

def add_signal_from_expression(
    self, expression: str, xmin: float, xmax: float, size: int = 500,
    title: str | None = None, **kwargs
) -> bool:
    """Create a signal from y=f(x) expression."""

def add_image_from_expression(
    self, expression: str, width: int, height: int,
    title: str | None = None, **kwargs
) -> bool:
    """Create an image from z=f(x,y) expression."""

Files to modify:

• datalab/control/baseproxy.py (optional convenience methods)
• datalab/control/proxy.py (implementations)

---

Phase 5 — Documentation & Translations

5.1 User documentation

• doc/features/signal/menu_operations.rst — document expression operation
• doc/features/image/menu_operations.rst — document expression operation
• doc/features/signal/menu_create.rst — document expression creation
• doc/features/image/menu_create.rst — document expression creation
• doc/features/general/expression_editor.rst — general reference for the
  expression syntax (functions, operators, variables, examples)
• API reference for sigima.tools.expression module

5.2 Translations

• UI strings: scan and translate to French
• Documentation: extract and translate to French via sphinx-intl

5.3 Release notes

User-focused entries in doc/release_notes/release_X.YY.md:

**New features:**

* Added equation editor for applying arbitrary mathematical expressions to
  signals and images (e.g. `(S1 - S2) / (S1 + S2)`, `log10(S1 / S2)`)
* Added signal and image creation from mathematical expressions
  (e.g. `y = sin(2*pi*x) + noise`, `z = exp(-(x² + y²))`)

---

Implementation Order & Dependencies

Phase 1: Expression Engine (Sigima)
  └──► Phase 2: Computation Functions (Sigima)
         ├──► Phase 3: GUI Integration (DataLab)
         │      └──► Phase 5: Docs & Translations
         └──► Phase 4: Remote Control (DataLab)
                └──► Phase 5: Docs & Translations

Phase	Scope	Estimated effort	Dependencies
1	sigima.tools.expression	Medium	None
2	sigima.proc.{signal,image}.expression + creation params	Medium	Phase 1
3	DataLab GUI dialogs, menus, widget	Large	Phase 2
4	Remote/macro API	Small	Phase 2
5	Documentation + translations	Medium	Phases 3 & 4

---

Security Considerations

The expression evaluator MUST prevent arbitrary code execution:

1. AST whitelist approach: Only allow ast.BinOp, ast.UnaryOp, ast.Compare,
   ast.Call (whitelisted names only), ast.Name (whitelisted), ast.Constant
   (numeric only), ast.IfExp
2. No attribute access: Reject ast.Attribute nodes entirely
3. No string literals: Reject ast.Constant with str value
4. No subscripts (initially): Reject ast.Subscript to prevent
   __class__.__bases__ exploitation
5. Restricted builtins: eval() called with {"__builtins__": {}} namespace
6. Timeout (optional): For very large arrays, wrap evaluation in a thread
   with timeout to prevent accidental infinite loops (though pure NumPy
   expressions on finite arrays cannot loop)

---

Open Questions

1. Should we support conditional expressions? E.g. where(S1 > 0, S1, 0) or
   Python ternary S1 if S1 > 0 else 0. → Recommendation: support where()
   function (maps to np.where).

2. Should multi-line expressions be supported? E.g. intermediate variables
   like a = S1 + S2; b = S1 - S2; a / b. → Recommendation: defer to a later
   version. Single-expression is sufficient for v1.

3. Should we provide auto-completion/IntelliSense in the expression widget?
   → Recommendation: yes for variable names and function names, using a simple
   completer (not a full language server).

4. numexpr as optional accelerator? → Recommendation: defer. The AST-based
   evaluator is fast enough for typical signal/image sizes. Add numexpr backend
   if profiling shows bottlenecks.

5. Expression-based ROI filtering? E.g. "keep only points where S1 > threshold".
   → Recommendation: out of scope for this feature. Could be a separate
   "Expression Filter" operation later.

---

References

• Current ArithmeticParam implementation: sigima/proc/base.py
• Signal creation system: sigima/objects/signal/creation.py
• Image creation system: sigima/objects/image/creation.py
• Processor registration: datalab/gui/processor/base.py
• Action handler: datalab/gui/actionhandler.py
• Menu structure: scripts/datalab_menus.txt
• Remote API: datalab/control/baseproxy.py