pyfsda 0.4.0__py3-none-any.whl

pyfsda/__init__.py

@@ -0,0 +1,162 @@
+"""pyfsda — call FSDA (MATLAB robust-statistics toolbox) routines from Python.
+
+Two ways to call, over the same generic engine and numpy <-> MATLAB marshalling.
+
+Functional (MATLAB-like) — call any FSDA routine as ``pyfsda.<name>(...)``; the shared
+MATLAB session starts on first use and is reused::
+
+    import pyfsda
+
+    d   = pyfsda.mahalFS(Y, MU, SIGMA)               # numeric array -> ndarray
+    out = pyfsda.Score(y, X, la=la, intercept=True)  # struct        -> dict
+    RAW, REW = pyfsda.mcd(Y, nargout=2)              # two outputs   -> tuple
+    pyfsda.stop()                                     # optional; also runs at exit
+
+Explicit session (advanced) — manage the engine yourself::
+
+    from pyfsda import FsdaEngine
+    eng = FsdaEngine.start("mahalFS")
+    d   = eng.call("mahalFS", Y, MU, SIGMA)
+    eng.stop()
+
+Requires MATLAB with the FSDA Add-On and a ``matlabengine`` release matching that
+MATLAB (see the README).
+
+On the first call, pyfsda prints (once, best-effort) the latest FSDA release available
+on GitHub, so you can check your install is current. Silence it with
+``pyfsda.start(check_version=False)`` before the first call.
+
+Optional pandas view (``pip install pyfsda[pandas]``): pass ``frames=True`` to receive
+table/timetable outputs as a ``pandas.DataFrame`` (``out = pyfsda.univariatems(y, X,
+frames=True)``), and pass a ``pandas.DataFrame`` argument to send a MATLAB ``table`` in.
+The default return is still the neutral dict -- the cross-language contract is unchanged.
+"""
+from __future__ import annotations
+
+import atexit
+import sys
+
+from .engine import FsdaEngine, from_matlab, to_matlab
+from .frames import is_table_dict, to_dataframe
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "FsdaEngine", "to_matlab", "from_matlab",
+    "to_dataframe", "is_table_dict",
+    "start", "stop", "engine", "__version__",
+]
+
+# --- shared lazily-started engine (backs the functional pyfsda.<name>(...) surface) ----
+_ENGINE: FsdaEngine | None = None
+_WRAPPERS: dict = {}
+_VALIDATED: set = set()          # FSDA names confirmed on-path for the current engine
+_CHECK_VERSION: bool = True      # set by start(); gates the first-call GitHub version notice
+_LATEST_CHECKED: bool = False    # run-once latch for _notify_latest_fsda
+
+_FSDA_RELEASES_API = "https://api.github.com/repos/UniprJRC/FSDA/releases/latest"
+
+# A few common FSDA routines advertised by __dir__ for REPL discoverability. The
+# __getattr__ mechanism accepts ANY FSDA function name, not just these.
+_COMMON = (
+    "mahalFS", "Score", "FSR", "FSRaddt", "FSM", "mcd", "pcaFS",
+    "corrNominal", "tabulateFS", "TBwei", "bc", "combsFS",
+)
+
+
+def start(routine: str | None = None, fsda_root: str | None = None,
+          check_version: bool = True) -> FsdaEngine:
+    """Start (once) and return the shared FSDA engine used by ``pyfsda.<name>(...)``.
+
+    Idempotent: returns the already-running engine on later calls. Call this before the
+    first routine only if you need to set ``fsda_root`` or disable ``check_version``.
+    """
+    global _ENGINE, _CHECK_VERSION
+    _CHECK_VERSION = check_version       # also gates the first-call GitHub version notice
+    if _ENGINE is None:
+        _ENGINE = FsdaEngine.start(routine=routine, fsda_root=fsda_root,
+                                   check_version=check_version)
+    return _ENGINE
+
+
+def engine() -> FsdaEngine:
+    """Return the shared engine, starting it with defaults if needed."""
+    return start()
+
+
+def stop() -> None:
+    """Shut the shared engine down (safe to call when it was never started)."""
+    global _ENGINE, _LATEST_CHECKED
+    if _ENGINE is not None:
+        try:
+            _ENGINE.stop()
+        finally:
+            _ENGINE = None
+            _VALIDATED.clear()
+            _LATEST_CHECKED = False        # a fresh session re-checks the latest release
+
+
+atexit.register(stop)
+
+
+def _notify_latest_fsda() -> None:
+    """Once per session, print the latest FSDA release available on GitHub (stderr).
+
+    Purely informational and best-effort: it reports the latest `tag_name` from the FSDA
+    GitHub releases API using only the standard library, and stays silent on any failure
+    (offline, rate-limited, blocked). It does NOT compare against the installed version.
+    Runs on the first `pyfsda.<name>(...)` call and is gated by `check_version` (disable
+    with `pyfsda.start(check_version=False)`). Separate from `engine.py`'s `tuna` check.
+    """
+    global _LATEST_CHECKED
+    if _LATEST_CHECKED or not _CHECK_VERSION:
+        return
+    _LATEST_CHECKED = True                  # latch up front: never retry on failure
+    try:
+        import json
+        import urllib.request
+
+        with urllib.request.urlopen(_FSDA_RELEASES_API, timeout=4.0) as resp:
+            tag = json.load(resp).get("tag_name")
+        if tag:
+            sys.stderr.write(
+                f"pyfsda: latest FSDA release on GitHub is {tag} "
+                f"(https://github.com/UniprJRC/FSDA/releases/tag/{tag}). "
+                f"Ensure your installed FSDA is current.\n"
+            )
+            sys.stderr.flush()
+    except Exception:
+        pass                                # never let a courtesy check break a call
+
+
+def _make_wrapper(name: str):
+    """Build (and cache) a callable that runs FSDA `name` on the shared engine."""
+    def _fsda_call(*args, **kwargs):
+        eng = engine()
+        _notify_latest_fsda()                          # once: latest FSDA release on GitHub
+        if name not in _VALIDATED:                     # verify once per name (typo guard)
+            if not eng.which(name):
+                raise AttributeError(
+                    f"FSDA function {name!r} not found on the MATLAB path."
+                )
+            _VALIDATED.add(name)
+        return eng.call(name, *args, **kwargs)
+    _fsda_call.__name__ = name
+    _fsda_call.__qualname__ = name
+    _fsda_call.__doc__ = (f"Call FSDA `{name}` on the shared pyfsda engine: "
+                          f"pyfsda.{name}(*args, **name_value_options).")
+    return _fsda_call
+
+
+def __getattr__(name: str):                            # PEP 562 module-level hook
+    """Expose any FSDA routine as ``pyfsda.<name>`` (e.g. ``pyfsda.Score``)."""
+    if name.startswith("_"):                            # don't hijack dunders/privates
+        raise AttributeError(f"module 'pyfsda' has no attribute {name!r}")
+    wrapper = _WRAPPERS.get(name)
+    if wrapper is None:
+        wrapper = _WRAPPERS[name] = _make_wrapper(name)
+    return wrapper
+
+
+def __dir__() -> list:
+    return sorted(set(__all__) | set(_COMMON))

pyfsda/engine.py

@@ -0,0 +1,514 @@
+"""pyfsda — a generic Python bridge for calling FSDA routines via the MATLAB Engine.
+
+Python -> matlab.engine -> MATLAB + FSDA
+
+Every per-routine `code/<target>/bridge.py` repeats the same engine/plumbing:
+start the engine, check the routine is on the path, marshal numpy <-> matlab.double,
+route MATLAB messages, handle figures, shut down. This module factors that plumbing
+into ONE place so a new FSDA routine usually needs no wrapper at all -- you call
+
+    eng = FsdaEngine.start("mahalFS")
+    d   = eng.call("mahalFS", Y, MU, SIGMA)            # numeric array  -> ndarray
+    out = eng.call("Score", y, X, la=la, intercept=True)  # struct      -> dict
+
+and the generic converters handle the crossing. It covers these MATLAB return
+shapes (see spec 016):
+
+    numeric array            matlab.double      -> ndarray
+    struct                   dict               -> dict (recursed)
+    nested struct of arrays  dict of dicts      -> dict of dicts of ndarrays
+    char/string scalar       char               -> str
+    table / timetable        (cannot return)    -> dict {VariableNames, RowNames
+                                                  / RowTimes, data}  (decomposed
+                                                  MATLAB-side; see _table_to_dict)
+    2-D cell (M x N)         (cannot return)    -> nested list (see _marshal_cell2d)
+    struct holding any of    (cannot return)    -> dict, decomposed field-by-field
+    the above                                     (see _marshal_struct)
+
+A table/timetable, a 2-D cell, or a struct *containing* one cannot be returned to Python
+by the engine at all, so `call` runs through the MATLAB workspace and decomposes them
+there (the approach `code/getYahoo/bridge.py` uses for its timetable). The struct/cell
+field-by-field path is a *fallback*: the fast whole-value read is tried first, so ordinary
+structs/numerics are untouched. STILL OUT OF SCOPE: struct-ARRAYS and datetime/duration
+scalars (getYahoo keeps its own bespoke bridge for those).
+
+Marshalling rules (CONSTITUTION sec 4):
+  * Output is returned in MATLAB's natural shape -- NO silent reshape. A column
+    vector stays (n, 1); callers squeeze if they want (n,).
+  * Input has ONE documented convention: a 1-D ndarray/list crosses as a MATLAB
+    *row* (1 x n). Pass an (n, 1) array when a routine wants a column (e.g. y).
+  * NaN / Inf are preserved; MATLAB indices stay 1-based -- interpretation is the
+    caller's.
+
+Dependencies: numpy + matlab + matlab.engine + stdlib only.
+
+See the pyfsda README for the full marshalling rules and usage.
+"""
+from __future__ import annotations
+
+import io
+import re
+import sys
+
+import numpy as np
+import matlab
+import matlab.engine
+
+from .frames import apply_frames, is_dataframe
+
+# call() reserves these keyword names for its own control; every OTHER keyword is
+# forwarded to MATLAB as a name/value pair. Notably `msg` is NOT reserved -- it
+# passes straight through to FSDA (FSR/FSRaddt/getYahoo each have their own `msg`
+# option). The bridge's stdout/stderr tee is `echo_output`, deliberately named so
+# it cannot collide with an FSDA option. `frames` is the opt-in pandas view (see
+# call()). The rare case where an FSDA option's name does collide with one of these
+# reserved words is handled via the `options` dict:
+#     eng.call("FSR", y, X, options={"nargout": ...})
+_RESERVED_CALL_KWARGS = ("nargout", "echo_output", "options", "frames")
+
+# call()/eval() execute through the MATLAB workspace (so table/timetable outputs --
+# which the engine cannot return directly -- can be decomposed MATLAB-side). The
+# function name and option names are interpolated into an eval command, so they are
+# validated against this allow-list first (an injection guard, like getYahoo).
+_IDENT_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_]*$")
+
+
+def _cellstr_list(raw) -> list:
+    """MATLAB cellstr -> Python list[str]. The engine returns a 1-element cell as a
+    bare str and a multi-element cell as a list; an empty cell as an empty value.
+    Collapse all of these to a list[str]."""
+    if raw is None:
+        return []
+    if isinstance(raw, str):
+        return [raw]
+    try:
+        return [str(x) for x in raw]
+    except TypeError:
+        return [str(raw)]
+
+
+def to_matlab(x):
+    """Marshal a Python value to a MATLAB-engine input type.
+
+    ndarray : 0-D -> float; 1-D -> MATLAB row (1 x n); 2-D -> matlab.double as-is.
+              (1-D -> row is a *convention*; pass an (n, 1) array for a column.)
+    bool    -> bool (MATLAB logical) -- checked before int (bool is an int subclass).
+    int/float -> float.   str -> str (char).   list/tuple of numbers -> row matlab.double.
+    Anything else is passed through untouched (already a matlab.* type, etc.).
+    """
+    if is_dataframe(x):
+        raise TypeError(
+            "pandas.DataFrame inputs are marshalled to a MATLAB table by call() -- "
+            "pass a DataFrame as a positional/option argument to call(), not to to_matlab().")
+    if isinstance(x, np.ndarray):
+        a = np.asarray(x, dtype=float)
+        if a.ndim == 0:
+            return float(a)
+        if a.ndim == 1:
+            a = a.reshape(1, -1)            # documented: 1-D -> MATLAB row
+        return matlab.double(a.tolist())
+    if isinstance(x, bool):
+        return x
+    if isinstance(x, (int, float)):
+        return float(x)
+    if isinstance(x, str):
+        return x
+    if isinstance(x, (list, tuple)):
+        return matlab.double([float(v) for v in x])
+    return x
+
+
+def from_matlab(x):
+    """Marshal a MATLAB-engine return value to plain Python, recursively.
+
+    None        -> None (e.g. an nargout=0 call).
+    dict        -> {k: from_matlab(v)}                 (struct / nested struct).
+    str/bool/int/float -> passed through                (char scalar, logical scalar).
+    list/tuple  -> [from_matlab(v) ...]                 (cell array / nargout > 1).
+    matlab.*    -> np.asarray(x)  (numeric/logical array; shape & NaN/Inf preserved,
+                  NO reshape).
+    """
+    if x is None:
+        return None
+    if isinstance(x, dict):
+        return {k: from_matlab(v) for k, v in x.items()}
+    if isinstance(x, str):
+        return x
+    if isinstance(x, (bool, int, float)):
+        return x
+    if isinstance(x, (list, tuple)):
+        return [from_matlab(v) for v in x]
+    # matlab.double / matlab.logical / matlab.int* and anything array-like.
+    try:
+        return np.asarray(x)
+    except Exception:
+        return x
+
+
+class FsdaEngine:
+    """A reusable MATLAB engine session with a generic, routine-agnostic `call`."""
+
+    def __init__(self, eng):
+        self.eng = eng
+
+    # --- lifecycle -----------------------------------------------------------
+    @classmethod
+    def start(cls, routine: str | None = None, fsda_root: str | None = None,
+              check_version: bool = True) -> "FsdaEngine":
+        """Start a MATLAB engine; optionally verify one FSDA `routine` resolves.
+
+        FSDA is normally a MATLAB Add-On (already on the path), so `fsda_root` can
+        be None; pass the FSDA install dir only as a fallback (added with
+        addpath(genpath(...))). When `routine` is given and cannot be found, the
+        engine is closed and RuntimeError is raised.
+
+        When `check_version` is True (default), a one-off, non-fatal FSDA
+        up-to-date check runs once the session is up (see `_check_fsda_version`):
+        it is silent when FSDA is current and prints a notice otherwise. Pass
+        `check_version=False` for a network-free / hermetic session.
+        """
+        eng = matlab.engine.start_matlab()
+        if fsda_root:
+            eng.addpath(eng.genpath(fsda_root), nargout=0)
+        if routine and not eng.which(routine):
+            eng.quit()
+            raise RuntimeError(
+                f"FSDA `{routine}` not found on the MATLAB path. Install the FSDA "
+                f"Add-On in MATLAB, or pass fsda_root=<FSDA install dir>."
+            )
+        self = cls(eng)
+        if check_version:
+            self._check_fsda_version()
+        return self
+
+    def stop(self) -> None:
+        """Shut the engine session down (startup is slow -- callers control this)."""
+        self.eng.quit()
+
+    def _check_fsda_version(self) -> None:
+        """Notify, once at session start, if the installed FSDA is not the latest.
+
+        Uses FSDA's own `tuna` utility in its quiet, no-GUI mode
+        (`tuna('FSDA','uniprJRC','FSDA','gui',false)`): tuna compares the installed
+        version (from the Add-On manager) against the latest GitHub release and
+        writes a message to the MATLAB Command Window ONLY when an update is
+        available -- so this prints nothing when FSDA is current. No modal dialog
+        is shown; a failure to reach GitHub is non-fatal MATLAB-side.
+
+        `tuna` is a recent FSDA utility, so `exist('tuna','file')==0` means FSDA is
+        either not installed or too old to self-check -- reported as such. The whole
+        check is best-effort: any Python-side failure is swallowed so it can never
+        break a session (disable it entirely with `start(check_version=False)`).
+        """
+        try:
+            has_tuna = int(self.eng.eval("double(exist('tuna','file')>0)", nargout=1))
+        except Exception:
+            return
+        if not has_tuna:
+            sys.stderr.write("FSDA not found on the MATLAB path, or too old to include "
+                             "'tuna' -- FSDA version check skipped.\n")
+            sys.stderr.flush()
+            return
+        out, err = io.StringIO(), io.StringIO()
+        try:
+            self.eng.eval("tuna('FSDA','uniprJRC','FSDA','gui',false)",
+                          nargout=0, stdout=out, stderr=err)
+        except Exception:
+            return                                    # tuna raised -> stay silent
+        msg = out.getvalue() + err.getvalue()
+        if msg.strip():                               # current FSDA -> tuna is silent
+            sys.stderr.write(msg)
+            sys.stderr.flush()
+
+    # --- the generic call ----------------------------------------------------
+    def call(self, name: str, *args, nargout: int = 1, echo_output: bool = False,
+             options: dict | None = None, frames: bool = False, **kwargs):
+        """Call FSDA function `name` generically and return plain Python.
+
+        Positional `args` are marshalled with `to_matlab` and passed in order.
+        Keyword args (and any `options` dict) become MATLAB name/value pairs, in
+        the given order -- e.g. ``call("Score", y, X, la=la, intercept=True)``
+        sends ``Score(y, X, 'la', la, 'intercept', true)``. FSDA's own ``msg``
+        option is just such a kwarg -- ``call("FSR", y, X, msg=0)`` forwards it to
+        MATLAB (it is NOT consumed by the bridge).
+
+        nargout     : number of outputs to request (default 1).
+        echo_output : when True, route MATLAB's stdout/stderr to this terminal (the
+                      engine needs io.StringIO buffers, so capture then echo). This
+                      is the bridge's OWN tee, named so it cannot clash with an FSDA
+                      option; it does not change what FSDA prints, only whether an
+                      embedded host (reticulate / PythonCall) surfaces it.
+        frames      : when True, table/timetable outputs (the dict returned by
+                      `_table_to_dict`) are returned as a `pandas.DataFrame` instead
+                      -- an opt-in Python-only view; the dict is still the default and
+                      the cross-language contract (needs `pip install pyfsda[pandas]`).
+
+        A `pandas.DataFrame` passed as a positional/option argument is marshalled to a
+        MATLAB `table` (see `_df_to_table_var`), independent of the `frames` flag.
+
+        Execution runs through the MATLAB workspace so outputs the engine cannot
+        return directly -- a **table / timetable** -- can be decomposed MATLAB-side
+        into a Python dict (see `_table_to_dict`); numeric/struct/char outputs cross
+        exactly as before. A returned table -> dict has keys ``VariableNames``,
+        ``RowNames`` (or ISO ``RowTimes`` for a timetable), and ``data`` (column ->
+        ndarray / list[str]).
+        """
+        if not _IDENT_RE.match(name):
+            raise ValueError(f"unsafe / malformed function name: {name!r}")
+        pairs = dict(options or {})
+        pairs.update(kwargs)
+        for key in pairs:
+            if not _IDENT_RE.match(str(key)):
+                raise ValueError(f"unsafe / malformed option name: {key!r}")
+
+        ws = self.eng.workspace
+        in_names, opt_tokens, temp = [], [], []
+        for i, a in enumerate(args):
+            vn = f"fe_in{i}"
+            if is_dataframe(a):
+                self._df_to_table_var(a, vn)      # DataFrame -> MATLAB table
+            else:
+                ws[vn] = to_matlab(a)
+            in_names.append(vn)
+            temp.append(vn)
+        for key, value in pairs.items():
+            vn = f"fe_opt_{key}"
+            if is_dataframe(value):
+                self._df_to_table_var(value, vn)  # DataFrame option value -> MATLAB table
+            else:
+                ws[vn] = to_matlab(value)
+            opt_tokens.append(f"'{key}',{vn}")   # 'name', tempvar
+            temp.append(vn)
+
+        out_names = [f"fe_out{j}" for j in range(nargout)]
+        temp.extend(out_names)
+        rhs = ",".join(in_names + opt_tokens)
+        if nargout == 0:
+            cmd = f"{name}({rhs});"
+        elif nargout == 1:
+            cmd = f"{out_names[0]} = {name}({rhs});"
+        else:
+            cmd = f"[{','.join(out_names)}] = {name}({rhs});"
+
+        try:
+            self._eval_cmd(cmd, echo_output)
+            if nargout == 0:
+                return None
+            results = [self._marshal_var(vn) for vn in out_names]
+        finally:
+            self._clear(temp)
+        if frames:                                # opt-in: table-dicts -> DataFrames
+            results = [apply_frames(r) for r in results]
+        return results[0] if nargout == 1 else tuple(results)
+
+    def eval(self, expr: str, nargout: int = 1):
+        """Evaluate a MATLAB expression and marshal the result back generically.
+
+        Handy for building/reading values the function `call` surface does not cover
+        (e.g. a constructed nested struct, or a table). nargout=0 returns None. For
+        nargout==1 the value is bound to a workspace temp first, so a table/timetable
+        expression decomposes through the same path as `call`.
+        """
+        if nargout == 0:
+            self.eng.eval(expr, nargout=0)
+            return None
+        if nargout == 1:
+            vn = "fe_eval0"
+            try:
+                self.eng.eval(f"{vn} = ({expr});", nargout=0)
+                return self._marshal_var(vn)
+            finally:
+                self._clear([vn])
+        return from_matlab(self.eng.eval(expr, nargout=nargout))
+
+    # --- workspace execution helpers -----------------------------------------
+    def _eval_cmd(self, cmd: str, echo_output: bool = False) -> None:
+        """Run a MATLAB statement, optionally tee-ing its stdout/stderr (see call())."""
+        if echo_output:
+            out_buf, err_buf = io.StringIO(), io.StringIO()
+            self.eng.eval(cmd, nargout=0, stdout=out_buf, stderr=err_buf)
+            if out_buf.getvalue():
+                sys.stdout.write(out_buf.getvalue())
+                sys.stdout.flush()          # surface under reticulate / PythonCall too
+            if err_buf.getvalue():
+                sys.stderr.write(err_buf.getvalue())
+                sys.stderr.flush()
+        else:
+            self.eng.eval(cmd, nargout=0)
+
+    def _clear(self, names: list) -> None:
+        """Remove the bridge's `fe_*` temp variables from the MATLAB workspace."""
+        if names:
+            self.eng.eval("clear " + " ".join(names), nargout=0)
+
+    def _marshal_var(self, vn: str):
+        """Marshal one workspace variable. table/timetable -> dict (decomposed
+        MATLAB-side); a 2-D cell -> nested list (the engine only returns 1-D cells);
+        otherwise read it out and pass through `from_matlab`. If that direct read
+        fails (e.g. a struct containing a field the engine cannot convert), fall back
+        to decomposing the struct/cell field-by-field MATLAB-side."""
+        if int(self.eng.eval(f"double(istable({vn})||istimetable({vn}))", nargout=1)):
+            return self._table_to_dict(vn)
+        if int(self.eng.eval(
+                f"double(iscell({vn}) && ~isrow({vn}) && ~iscolumn({vn}))", nargout=1)):
+            return self._marshal_cell2d(vn)        # M x N cell: engine can't return it
+        try:
+            return from_matlab(self.eng.workspace[vn])
+        except Exception:
+            if int(self.eng.eval(f"double(isstruct({vn}))", nargout=1)):
+                return self._marshal_struct(vn)
+            if int(self.eng.eval(f"double(iscell({vn}))", nargout=1)):
+                return self._marshal_cell2d(vn)
+            raise
+
+    def _marshal_struct(self, vn: str) -> dict:
+        """Decompose a struct field-by-field MATLAB-side (used when the engine cannot
+        eagerly convert the whole struct -- e.g. it holds a 2-D cell or table field).
+        Each field is routed back through `_marshal_var`, so tables/2-D cells/nested
+        structs are handled recursively. The function ran once already; this only
+        re-reads its result carefully."""
+        fields = _cellstr_list(self.eng.eval(f"fieldnames({vn})", nargout=1))
+        out = {}
+        for f in fields:
+            if not _IDENT_RE.match(f):             # fieldnames are valid idents; guard anyway
+                raise ValueError(f"unsafe struct field name: {f!r}")
+            self.eng.eval(f"fe_fld = {vn}.{f};", nargout=0)
+            try:
+                out[f] = self._marshal_var("fe_fld")
+            finally:
+                self._clear(["fe_fld"])
+        return out
+
+    def _marshal_cell2d(self, vn: str) -> list:
+        """Decompose an M x N MATLAB cell into a nested Python list (the engine only
+        returns 1-by-N / M-by-1 cells). Each element is read by index and routed
+        through `_marshal_var`, so cells of matrices / structs / tables all cross."""
+        m = int(self.eng.eval(f"double(size({vn},1))", nargout=1))
+        n = int(self.eng.eval(f"double(size({vn},2))", nargout=1))
+        rows = []
+        for i in range(1, m + 1):
+            row = []
+            for j in range(1, n + 1):
+                self.eng.eval(f"fe_cel = {vn}{{{i},{j}}};", nargout=0)
+                try:
+                    row.append(self._marshal_var("fe_cel"))
+                finally:
+                    self._clear(["fe_cel"])
+            rows.append(row)
+        return rows
+
+    def _table_to_dict(self, vn: str) -> dict:
+        """Decompose a MATLAB table/timetable workspace var into a Python dict.
+
+        Columns are read by **index** (`T{:,j}`), never by interpolating their names,
+        so a column name can be anything without risk. Numeric/logical columns become
+        ndarrays (single columns flattened to 1-D); other columns (categorical /
+        string / cellstr) become list[str].
+        """
+        is_tt = int(self.eng.eval(f"double(istimetable({vn}))", nargout=1))
+        varnames = _cellstr_list(self.eng.eval(f"{vn}.Properties.VariableNames", nargout=1))
+        height = int(self.eng.eval(f"double(height({vn}))", nargout=1))
+
+        data = {}
+        for j, col in enumerate(varnames, start=1):
+            is_num = int(self.eng.eval(
+                f"double(isnumeric({vn}{{:,{j}}})||islogical({vn}{{:,{j}}}))", nargout=1))
+            if is_num:
+                arr = np.asarray(self.eng.eval(f"{vn}{{:,{j}}}", nargout=1), dtype=float)
+                data[col] = arr.reshape(-1) if (arr.ndim == 1 or arr.shape[1] == 1) else arr
+            else:
+                data[col] = _cellstr_list(
+                    self.eng.eval(f"cellstr(string({vn}{{:,{j}}}))", nargout=1))
+
+        result = {"VariableNames": varnames, "data": data, "height": height}
+        if is_tt:
+            result["RowTimes"] = _cellstr_list(
+                self.eng.eval(f"cellstr(string({vn}.Properties.RowTimes))", nargout=1))
+        else:
+            result["RowNames"] = _cellstr_list(
+                self.eng.eval(f"{vn}.Properties.RowNames", nargout=1))
+        return result
+
+    def _cellstr_to_var(self, values, vn: str) -> None:
+        """Build a MATLAB cellstr in workspace var `vn` from a Python list[str].
+
+        Each element crosses as a char scalar (a supported engine input); the cell is then
+        assembled MATLAB-side. Only the bridge's own temp names (`{vn}_e0`, ...) are ever
+        interpolated -- never the string CONTENTS -- so column/row labels are injection-safe.
+        """
+        ws = self.eng.workspace
+        elem_vars = []
+        try:
+            for k, v in enumerate(values):
+                ev = f"{vn}_e{k}"
+                ws[ev] = str(v)
+                elem_vars.append(ev)
+            self.eng.eval(f"{vn} = {{{','.join(elem_vars)}}};", nargout=0)
+        finally:
+            self._clear(elem_vars)
+
+    def _df_to_table_var(self, df, vn: str) -> None:
+        """Assemble a MATLAB `table` in workspace variable `vn` from a pandas DataFrame.
+
+        The inverse of `_table_to_dict`. Column names cross as a MATLAB cell (`fe_varnames`,
+        built by `_cellstr_to_var`) and feed `array2table(...,'VariableNames',fe_varnames)`
+        -- never string-interpolated. Explicit `VariableNames` are used verbatim (modern
+        MATLAB tables allow arbitrary variable-name text). A non-default row index becomes
+        the table's `RowNames`.
+
+        v1 supports **numeric / logical** columns only (the common FSDA design-matrix case);
+        string / categorical / datetime columns and a MultiIndex raise NotImplementedError,
+        consistent with the engine's existing struct-array / datetime limits.
+        """
+        raw = np.asarray(df.to_numpy())
+        if raw.dtype != bool and not np.issubdtype(raw.dtype, np.number):
+            raise NotImplementedError(
+                "pyfsda: DataFrame -> MATLAB table supports numeric/logical columns only in "
+                "v1; string / categorical / datetime columns are not yet marshalled.")
+        block = np.asarray(raw, dtype=float)
+        if block.ndim != 2:
+            block = block.reshape(len(df), -1)
+
+        ws = self.eng.workspace
+        ws["fe_block"] = matlab.double(block.tolist())
+        temp = ["fe_block", "fe_varnames"]
+        try:
+            self._cellstr_to_var([str(c) for c in df.columns], "fe_varnames")
+            self.eng.eval(
+                f"{vn} = array2table(fe_block,'VariableNames',fe_varnames);", nargout=0)
+            index = list(df.index)
+            if index != list(range(len(df))):        # non-default index -> RowNames
+                self._cellstr_to_var([str(i) for i in index], "fe_rownames")
+                temp.append("fe_rownames")
+                self.eng.eval(f"{vn}.Properties.RowNames = fe_rownames;", nargout=0)
+        finally:
+            self._clear(temp)
+
+    # --- diagnostics ---------------------------------------------------------
+    def which(self, name: str) -> str:
+        """Resolved path of FSDA function `name` (empty str if not found)."""
+        return str(self.eng.which(name))
+
+    def version(self) -> str:
+        """MATLAB version string."""
+        return str(self.eng.version())
+
+    # --- figures (parity with the per-routine bridges) -----------------------
+    def render_figures(self) -> None:
+        """Force any open MATLAB figures to paint."""
+        self.eng.eval("drawnow", nargout=0)
+
+    def wait_for_figures(self) -> None:
+        """Block until the user closes all open MATLAB figures.
+
+        Driven entirely MATLAB-side (uiwait), so it is immune to the terminal-stdin
+        interference seen when the engine is embedded via reticulate / PythonCall.
+        Returns immediately if no figures are open.
+        """
+        self.eng.eval(
+            "drawnow; "
+            "fh = findall(groot, 'Type', 'figure'); "
+            "while ~isempty(fh); uiwait(fh(1)); "
+            "fh = findall(groot, 'Type', 'figure'); end",
+            nargout=0,
+        )

pyfsda/frames.py

@@ -0,0 +1,91 @@
+"""Optional pandas view over FSDA table/timetable results -- Python codepath only.
+
+The generic engine returns a MATLAB ``table``/``timetable`` as a neutral dict
+``{VariableNames, RowNames/RowTimes, data, height}`` (see ``engine._table_to_dict``). That
+dict is the cross-language interchange format (R / Julia rely on it) and stays the default.
+This module layers an *opt-in* pandas view on the Python side:
+
+    * ``to_dataframe(table_dict)`` -- build a ``pandas.DataFrame`` from the dict.
+    * ``apply_frames(obj)``       -- recurse through a result, converting every table-dict.
+    * ``is_table_dict(obj)``      -- recognise the dict shape.
+    * ``is_dataframe(x)``         -- recognise a pandas DataFrame WITHOUT importing pandas.
+
+pandas is an optional dependency: it is imported lazily, only when a table actually crosses
+(``to_dataframe``). ``is_dataframe`` is duck-typed so the input path never imports pandas.
+Install the extra with ``pip install pyfsda[pandas]``.
+"""
+from __future__ import annotations
+
+_PANDAS_HINT = (
+    "pandas is required for this feature; install it with `pip install pyfsda[pandas]` "
+    "(or `pip install pandas`)."
+)
+
+
+def _require_pandas():
+    """Import pandas lazily, raising a clear, actionable error if it is missing."""
+    try:
+        import pandas as pd
+    except ImportError as exc:                      # pragma: no cover - trivial guard
+        raise ImportError(_PANDAS_HINT) from exc
+    return pd
+
+
+def is_table_dict(obj) -> bool:
+    """True if ``obj`` is a table/timetable dict emitted by ``engine._table_to_dict``."""
+    return (
+        isinstance(obj, dict)
+        and "VariableNames" in obj
+        and "data" in obj
+        and ("RowNames" in obj or "RowTimes" in obj)
+    )
+
+
+def is_dataframe(x) -> bool:
+    """True if ``x`` is a pandas DataFrame -- duck-typed, so pandas is never imported here."""
+    cls = type(x)
+    return cls.__name__ == "DataFrame" and cls.__module__.split(".", 1)[0] == "pandas"
+
+
+def to_dataframe(table_dict):
+    """Build a ``pandas.DataFrame`` from a table/timetable dict.
+
+    Columns follow ``VariableNames`` order; the index comes from ``RowTimes`` (parsed to a
+    DatetimeIndex when possible, else kept as strings) for a timetable, or from non-empty
+    ``RowNames`` for a table; otherwise the default RangeIndex is used.
+    """
+    if not is_table_dict(table_dict):
+        raise TypeError("to_dataframe expects a table/timetable dict "
+                        "{VariableNames, data, RowNames/RowTimes, ...}.")
+    pd = _require_pandas()
+    names = list(table_dict["VariableNames"])
+    data = table_dict["data"]
+    df = pd.DataFrame({col: data[col] for col in names}, columns=names)
+
+    row_times = table_dict.get("RowTimes")
+    row_names = table_dict.get("RowNames")
+    if row_times:
+        try:
+            df.index = pd.to_datetime(list(row_times))
+        except (ValueError, TypeError):
+            df.index = list(row_times)
+    elif row_names:
+        df.index = list(row_names)
+    return df
+
+
+def apply_frames(obj):
+    """Recurse through a marshalled result, converting every table-dict to a DataFrame.
+
+    Handles a bare table-dict, a ``nargout > 1`` tuple/list, and a struct dict that holds
+    table-dict fields. Non-table values are returned unchanged.
+    """
+    if is_table_dict(obj):
+        return to_dataframe(obj)
+    if isinstance(obj, dict):
+        return {k: apply_frames(v) for k, v in obj.items()}
+    if isinstance(obj, tuple):
+        return tuple(apply_frames(v) for v in obj)
+    if isinstance(obj, list):
+        return [apply_frames(v) for v in obj]
+    return obj

pyfsda-0.4.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: pyfsda
+Version: 0.4.0
+Summary: Call FSDA (MATLAB robust-statistics toolbox) routines from Python via the MATLAB Engine.
+Project-URL: Homepage, https://github.com/UniprJRC/FSDA-bridge
+Project-URL: Repository, https://github.com/UniprJRC/FSDA-bridge
+Project-URL: Issues, https://github.com/UniprJRC/FSDA-bridge/issues
+Project-URL: FSDA toolbox, https://github.com/UniprJRC/FSDA
+Author: FSDA team
+Author-email: Aldo Corbellini <aldo.corbellini@gmail.com>
+Maintainer-email: Aldo Corbellini <aldo.corbellini@gmail.com>
+License-Expression: EUPL-1.2
+License-File: LICENSE
+Keywords: forward search,fsda,matlab,matlab engine,outlier detection,robust statistics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: matlabengine
+Requires-Dist: numpy>=1.22
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# pyfsda
+
+Call [**FSDA**](https://github.com/UniprJRC/FSDA) — the MATLAB *Flexible Statistics and Data
+Analysis* toolbox for robust statistics — from **Python**, using the MATLAB Engine as the
+computational backend. FSDA runs unmodified in MATLAB; `pyfsda` is a thin, routine-agnostic bridge
+that marshals data across the boundary.
+
+Call any FSDA routine as a plain Python function — the MATLAB session starts on first use and is
+reused:
+
+```python
+import pyfsda
+
+d   = pyfsda.mahalFS(Y, MU, SIGMA)                # numeric array -> numpy ndarray
+out = pyfsda.Score(y, X, la=la, intercept=True)  # struct        -> dict  (MATLAB-style options)
+RAW, REW = pyfsda.mcd(Y, nargout=2)             # two outputs   -> tuple
+pyfsda.stop()                                     # optional; also runs automatically at exit
+```
+
+`pyfsda.<name>` works for **any** FSDA function (`from pyfsda import Score` works too). Prefer managing
+the session yourself? Use the explicit engine:
+
+```python
+from pyfsda import FsdaEngine
+
+eng = FsdaEngine.start("mahalFS")
+d   = eng.call("mahalFS", Y, MU, SIGMA)
+eng.stop()
+```
+
+## Requirements
+
+`pyfsda` does not bundle MATLAB or FSDA — it drives your local install. You need:
+
+1. **MATLAB** with the **FSDA Add-On** installed and on the MATLAB path (verify `which mahalFS`
+   inside MATLAB).
+2. **`matlabengine`** matching your MATLAB release. This is the one version constraint that matters:
+   the `matlabengine` package on PyPI is release-locked, so install the one that pairs with your
+   MATLAB — e.g. `pip install "matlabengine==26.1.*"` for **R2026a**. `pyfsda` lists `matlabengine`
+   as a dependency but deliberately does **not** pin it, so it will not clobber a matching version you
+   already have.
+3. **Python 3.9–3.13** (whatever your MATLAB release's engine supports).
+
+## Install
+
+```bash
+pip install pyfsda
+# then, if not already present, the matlabengine that matches YOUR MATLAB:
+pip install "matlabengine==26.1.*"     # example: MATLAB R2026a
+```
+
+## Verify your install
+
+Run [`examples/smoke_test.py`](examples/smoke_test.py) — it starts MATLAB and checks a few real FSDA
+routines against numpy oracles, printing `RESULT: PASS` when your MATLAB + FSDA + `matlabengine` setup
+is good:
+
+```bash
+python smoke_test.py                 # or:  python smoke_test.py /path/to/FSDA
+```
+
+For a worked, MATLAB-style example, see [`examples/score_example.py`](examples/score_example.py) — the
+Box-Cox `Score` test on the wool dataset, calling `Score(y, X, 'la', ..., 'intercept', true)` the same
+way you would in MATLAB.
+
+## What crosses the boundary
+
+`call(name, *args, nargout=1, echo_output=False, options=None, **kwargs)` marshals positional
+arguments in order and keyword arguments (and any `options` dict) as MATLAB name/value pairs. It runs
+through the MATLAB workspace so outputs the engine cannot return directly (tables, 2-D cells) are
+decoded MATLAB-side.
+
+| MATLAB value | crosses as |
+|---|---|
+| numeric / logical array | `numpy.ndarray` (natural shape, `NaN`/`Inf` preserved) |
+| `struct` | `dict` (recursed) |
+| `char` / `string` scalar | `str` |
+| `cell` | `list` |
+| `table` / `timetable` | `dict` `{VariableNames, RowNames`/`RowTimes, data, height}` |
+| 2-D `cell` | nested `list` |
+| `nargout > 1` | `tuple` of the above |
+| graphics handle (`matlab.graphics.*`) | **not marshalled** — request only data outputs |
+
+Conventions: a 1-D input crosses as a MATLAB **row** (pass an `(n, 1)` array for a column); outputs
+keep MATLAB's natural shape (no silent reshape); MATLAB indices stay **1-based**.
+
+Reserved keywords consumed by the bridge are only `nargout`, `echo_output`, `options`, and `frames`;
+every other keyword is forwarded to MATLAB (so FSDA's own `msg` option passes straight through).
+`echo_output=True` tees MATLAB's stdout/stderr to your terminal.
+
+### Optional pandas view (`pip install pyfsda[pandas]`)
+
+pandas is an **optional** dependency — `import pyfsda` works without it. When it is installed you get a
+DataFrame view over MATLAB tables, on the Python side only (the neutral dict stays the default and
+remains the cross-language contract):
+
+- **Output:** pass `frames=True` to receive `table`/`timetable` outputs as a `pandas.DataFrame`
+  (index from `RowNames`/`RowTimes`) — e.g. `out = pyfsda.univariatems(y, X, frames=True)`. The public
+  helper `pyfsda.to_dataframe(table_dict)` converts a dict you already have.
+- **Input:** pass a `pandas.DataFrame` argument and it is marshalled to a MATLAB `table`
+  (`array2table`, column names and any non-default index preserved). v1 covers numeric/logical columns;
+  string/categorical/datetime columns raise a clear `NotImplementedError`.
+
+Requesting `frames=True` (or passing a DataFrame) without pandas installed raises a clear
+`pip install pyfsda[pandas]` error.
+
+On the **first `pyfsda.<name>(...)` call**, pyfsda also prints (once, best-effort) the **latest FSDA
+release available on GitHub**, so you can check your install is current. `FsdaEngine.start()`
+additionally runs a MATLAB-side FSDA up-to-date check via FSDA's `tuna` utility (quiet unless an update
+is available). Both are gated by `check_version` — silence them with
+`pyfsda.start(check_version=False)` (or `FsdaEngine.start(check_version=False)`) before the first call.
+
+## Notes
+
+- **MATLAB engine startup is slow** — start one `FsdaEngine` and reuse it; always `stop()` explicitly.
+- Struct-arrays and `datetime`/`duration` scalars are out of scope for the generic converters.
+
+## License
+
+[EUPL-1.2](LICENSE) — consistent with FSDA's own licensing.

pyfsda-0.4.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pyfsda/__init__.py,sha256=RQjt5_8mqDYDN90IOp6QEWjBqQYYzpjSVUH1Aj-epjg,6560
+pyfsda/engine.py,sha256=WOeQm58_NC2ohzNPwA1yAWmnC8htUMaTPPLSd3JCW6s,24242
+pyfsda/frames.py,sha256=WN46KjphgjY-73eCl-BBiqT5vbsPGosr0NnmyZdeMQE,3609
+pyfsda/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyfsda-0.4.0.dist-info/METADATA,sha256=keYhCk-lZ7nYEpGsH62EGRyHetxUFnGLao14ky1W5Kc,7183
+pyfsda-0.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+pyfsda-0.4.0.dist-info/licenses/LICENSE,sha256=V_tC-80LA3zlKO2PcvHsCV1nvGgl7PFEj_Ob4f5opLQ,13792
+pyfsda-0.4.0.dist-info/RECORD,,

pyfsda-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyfsda-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,190 @@
+EUROPEAN UNION PUBLIC LICENCE v. 1.2
+EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined below) which is provided under the
+terms of this Licence. Any use of the Work, other than as authorised under this Licence is prohibited (to the extent such
+use is covered by a right of the copyright holder of the Work).
+The Work is provided under the terms of this Licence when the Licensor (as defined below) has placed the following
+notice immediately following the copyright notice for the Work:
+                          Licensed under the EUPL
+or has expressed by any other means his willingness to license under the EUPL.
+
+1.Definitions
+In this Licence, the following terms have the following meaning:
+— ‘The Licence’:this Licence.
+— ‘The Original Work’:the work or software distributed or communicated by the Licensor under this Licence, available
+as Source Code and also as Executable Code as the case may be.
+— ‘Derivative Works’:the works or software that could be created by the Licensee, based upon the Original Work or
+modifications thereof. This Licence does not define the extent of modification or dependence on the Original Work
+required in order to classify a work as a Derivative Work; this extent is determined by copyright law applicable in
+the country mentioned in Article 15.
+— ‘The Work’:the Original Work or its Derivative Works.
+— ‘The Source Code’:the human-readable form of the Work which is the most convenient for people to study and
+modify.
+— ‘The Executable Code’:any code which has generally been compiled and which is meant to be interpreted by
+a computer as a program.
+— ‘The Licensor’:the natural or legal person that distributes or communicates the Work under the Licence.
+— ‘Contributor(s)’:any natural or legal person who modifies the Work under the Licence, or otherwise contributes to
+the creation of a Derivative Work.
+— ‘The Licensee’ or ‘You’:any natural or legal person who makes any usage of the Work under the terms of the
+Licence.
+— ‘Distribution’ or ‘Communication’:any act of selling, giving, lending, renting, distributing, communicating,
+transmitting, or otherwise making available, online or offline, copies of the Work or providing access to its essential
+functionalities at the disposal of any other natural or legal person.
+
+2.Scope of the rights granted by the Licence
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive, sublicensable licence to do the following, for
+the duration of copyright vested in the Original Work:
+— use the Work in any circumstance and for all usage,
+— reproduce the Work,
+— modify the Work, and make Derivative Works based upon the Work,
+— communicate to the public, including the right to make available or display the Work or copies thereof to the public
+and perform publicly, as the case may be, the Work,
+— distribute the Work or copies thereof,
+— lend and rent the Work or copies thereof,
+— sublicense rights in the Work or copies thereof.
+Those rights can be exercised on any media, supports and formats, whether now known or later invented, as far as the
+applicable law permits so.
+In the countries where moral rights apply, the Licensor waives his right to exercise his moral right to the extent allowed
+by law in order to make effective the licence of the economic rights here above listed.
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to any patents held by the Licensor, to the
+extent necessary to make use of the rights granted on the Work under this Licence.
+
+3.Communication of the Source Code
+The Licensor may provide the Work either in its Source Code form, or as Executable Code. If the Work is provided as
+Executable Code, the Licensor provides in addition a machine-readable copy of the Source Code of the Work along with
+each copy of the Work that the Licensor distributes or indicates, in a notice following the copyright notice attached to
+the Work, a repository where the Source Code is easily and freely accessible for as long as the Licensor continues to
+distribute or communicate the Work.
+
+4.Limitations on copyright
+Nothing in this Licence is intended to deprive the Licensee of the benefits from any exception or limitation to the
+exclusive rights of the rights owners in the Work, of the exhaustion of those rights or of other applicable limitations
+thereto.
+
+5.Obligations of the Licensee
+The grant of the rights mentioned above is subject to some restrictions and obligations imposed on the Licensee. Those
+obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or trademarks notices and all notices that refer to
+the Licence and to the disclaimer of warranties. The Licensee must include a copy of such notices and a copy of the
+Licence with every copy of the Work he/she distributes or communicates. The Licensee must cause any Derivative Work
+to carry prominent notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the Original Works or Derivative Works, this
+Distribution or Communication will be done under the terms of this Licence or of a later version of this Licence unless
+the Original Work is expressly distributed only under this version of the Licence — for example by communicating
+‘EUPL v. 1.2 only’. The Licensee (becoming Licensor) cannot offer or impose any additional terms or conditions on the
+Work or Derivative Work that alter or restrict the terms of the Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative Works or copies thereof based upon both
+the Work and another work licensed under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause, ‘Compatible Licence’ refers to the licences listed
+in the appendix attached to this Licence. Should the Licensee's obligations under the Compatible Licence conflict with
+his/her obligations under this Licence, the obligations of the Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the Work, the Licensee will provide
+a machine-readable copy of the Source Code or indicate a repository where this Source will be easily and freely available
+for as long as the Licensee continues to distribute or communicate the Work.
+Legal Protection: This Licence does not grant permission to use the trade names, trademarks, service marks, or names
+of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6.Chain of Authorship
+The original Licensor warrants that the copyright in the Original Work granted hereunder is owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each Contributor warrants that the copyright in the modifications he/she brings to the Work are owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each time You accept the Licence, the original Licensor and subsequent Contributors grant You a licence to their contributions
+to the Work, under the terms of this Licence.
+
+7.Disclaimer of Warranty
+The Work is a work in progress, which is continuously improved by numerous Contributors. It is not a finished work
+and may therefore contain defects or ‘bugs’ inherent to this type of development.
+For the above reason, the Work is provided under the Licence on an ‘as is’ basis and without warranties of any kind
+concerning the Work, including without limitation merchantability, fitness for a particular purpose, absence of defects or
+errors, accuracy, non-infringement of intellectual property rights other than copyright as stated in Article 6 of this
+Licence.
+This disclaimer of warranty is an essential part of the Licence and a condition for the grant of any rights to the Work.
+
+8.Disclaimer of Liability
+Except in the cases of wilful misconduct or damages directly caused to natural persons, the Licensor will in no event be
+liable for any direct or indirect, material or moral, damages of any kind, arising out of the Licence or of the use of the
+Work, including without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, loss
+of data or any commercial damage, even if the Licensor has been advised of the possibility of such damage. However,
+the Licensor will be liable under statutory product liability laws as far such laws apply to the Work.
+
+9.Additional agreements
+While distributing the Work, You may choose to conclude an additional agreement, defining obligations or services
+consistent with this Licence. However, if accepting obligations, You may act only on your own behalf and on your sole
+responsibility, not on behalf of the original Licensor or any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against such Contributor by
+the fact You have accepted any warranty or additional liability.
+
+10.Acceptance of the Licence
+The provisions of this Licence can be accepted by clicking on an icon ‘I agree’ placed under the bottom of a window
+displaying the text of this Licence or by affirming consent in any other similar way, in accordance with the rules of
+applicable law. Clicking on that icon indicates your clear and irrevocable acceptance of this Licence and all of its terms
+and conditions.
+Similarly, you irrevocably accept this Licence and all of its terms and conditions by exercising any rights granted to You
+by Article 2 of this Licence, such as the use of the Work, the creation by You of a Derivative Work or the Distribution
+or Communication by You of the Work or copies thereof.
+
+11.Information to the public
+In case of any Distribution or Communication of the Work by means of electronic communication by You (for example,
+by offering to download the Work from a remote location) the distribution channel or media (for example, a website)
+must at least provide to the public the information requested by the applicable law regarding the Licensor, the Licence
+and the way it may be accessible, concluded, stored and reproduced by the Licensee.
+
+12.Termination of the Licence
+The Licence and the rights granted hereunder will terminate automatically upon any breach by the Licensee of the terms
+of the Licence.
+Such a termination will not terminate the licences of any person who has received the Work from the Licensee under
+the Licence, provided such persons remain in full compliance with the Licence.
+
+13.Miscellaneous
+Without prejudice of Article 9 above, the Licence represents the complete agreement between the Parties as to the
+Work.
+If any provision of the Licence is invalid or unenforceable under applicable law, this will not affect the validity or
+enforceability of the Licence as a whole. Such provision will be construed or reformed so as necessary to make it valid
+and enforceable.
+The European Commission may publish other linguistic versions or new versions of this Licence or updated versions of
+the Appendix, so far this is required and reasonable, without reducing the scope of the rights granted by the Licence.
+New versions of the Licence will be published with a unique version number.
+All linguistic versions of this Licence, approved by the European Commission, have identical value. Parties can take
+advantage of the linguistic version of their choice.
+
+14.Jurisdiction
+Without prejudice to specific agreement between parties,
+— any litigation resulting from the interpretation of this License, arising between the European Union institutions,
+bodies, offices or agencies, as a Licensor, and any Licensee, will be subject to the jurisdiction of the Court of Justice
+of the European Union, as laid down in article 272 of the Treaty on the Functioning of the European Union,
+— any litigation arising between other parties and resulting from the interpretation of this License, will be subject to
+the exclusive jurisdiction of the competent court where the Licensor resides or conducts its primary business.
+
+15.Applicable Law
+Without prejudice to specific agreement between parties,
+— this Licence shall be governed by the law of the European Union Member State where the Licensor has his seat,
+resides or has his registered office,
+— this licence shall be governed by Belgian law if the Licensor has no seat, residence or registered office inside
+a European Union Member State.
+
+
+                                                         Appendix
+
+‘Compatible Licences’ according to Article 5 EUPL are:
+— GNU General Public License (GPL) v. 2, v. 3
+— GNU Affero General Public License (AGPL) v. 3
+— Open Software License (OSL) v. 2.1, v. 3.0
+— Eclipse Public License (EPL) v. 1.0
+— CeCILL v. 2.0, v. 2.1
+— Mozilla Public Licence (MPL) v. 2
+— GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+— Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for works other than software
+— European Union Public Licence (EUPL) v. 1.1, v. 1.2
+— Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong Reciprocity (LiLiQ-R+).
+
+The European Commission may update this Appendix to later versions of the above licences without producing
+a new version of the EUPL, as long as they provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+All other changes or additions to this Appendix require the production of a new EUPL version.