pyfsda 0.4.0__tar.gz

pyfsda-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,86 @@
+name: build & publish
+
+# Two kinds of runner, for a reason:
+#
+#  * build (GitHub-hosted): always builds + metadata-checks the distribution and runs the
+#    marshalling UNIT tests best-effort (they need only the `matlabengine` client, which may or
+#    may not install on a bare runner -- if it cannot, those tests skip themselves).
+#
+#  * integration (SELF-HOSTED): the matlab.engine tests drive real MATLAB via the MATLAB Engine
+#    API for Python. MathWorks batch licensing -- the only licensing available on GitHub-hosted
+#    runners, with or without an MLM_LICENSE_TOKEN -- does NOT license external language
+#    interfaces (Engine API for Python/Java/.NET/C/C++/Fortran). So these tests can ONLY run on a
+#    self-hosted runner whose MATLAB is licensed WITHOUT a batch token. See CONTRIBUTING.md.
+#
+# Publishing uses PyPI trusted publishing (OIDC) on a v* tag -- no API token. One-time setup:
+# register this repo + workflow as a Trusted Publisher for `pyfsda` on PyPI.
+
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+defaults:
+  run:
+    working-directory: packages/pyfsda
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel and check metadata
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*
+      - name: Unit tests (best-effort; needs the matlabengine client)
+        run: |
+          pip install --no-deps dist/*.whl
+          pip install numpy pytest
+          pip install matlabengine || echo "matlabengine unavailable on runner -> marshalling tests will skip"
+          pytest -m "not integration" -q
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: packages/pyfsda/dist/*
+
+  integration:
+    # SECURITY: a self-hosted runner executes the job on YOUR machine. Run it on push / manual
+    # dispatch ONLY -- never on `pull_request`, or an untrusted fork PR would run arbitrary code
+    # on the runner. Do not remove this guard.
+    if: github.event_name != 'pull_request'
+    runs-on: [self-hosted, macOS, pyfsda-matlab]
+    env:
+      # Optional: set repo variable PYFSDA_FSDA_ROOT if FSDA is not on the runner's default
+      # MATLAB path. Empty -> the test relies on the machine's default path.
+      PYFSDA_FSDA_ROOT: ${{ vars.PYFSDA_FSDA_ROOT }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Full test suite on the licensed MATLAB machine
+        run: |
+          rm -rf .ci-venv
+          python3 -m venv --system-site-packages .ci-venv   # inherit the machine's matlabengine
+          ./.ci-venv/bin/python -m pip install --upgrade pip
+          ./.ci-venv/bin/pip install --no-deps .            # install pyfsda; numpy/matlabengine from system
+          ./.ci-venv/bin/pip install numpy pytest
+          ./.ci-venv/bin/pytest -q                          # unit + integration (this machine has MATLAB)
+
+  publish:
+    needs: build          # a release never waits on the self-hosted integration job
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write          # OIDC token for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

pyfsda-0.4.0/.gitignore

@@ -0,0 +1,17 @@
+# Build artifacts
+/dist/
+/build/
+*.egg-info/
+.eggs/
+
+# Caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+.ci-venv/

pyfsda-0.4.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to `pyfsda` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.4.0] — unreleased
+
+### Added
+- **Optional pandas view at the Python boundary** (`pip install pyfsda[pandas]`, spec 019). pandas stays
+  optional and lazily imported — `import pyfsda` works without it, and the neutral
+  `dict {VariableNames, RowNames/RowTimes, data, height}` remains the default and the cross-language
+  contract (R and Julia surfaces are untouched).
+  - **Output:** `frames=True` returns `table`/`timetable` outputs as a `pandas.DataFrame`
+    (`pyfsda.<name>(..., frames=True)`); new public helper `pyfsda.to_dataframe(table_dict)` and
+    predicate `pyfsda.is_table_dict(obj)`.
+  - **Input:** a `pandas.DataFrame` argument is marshalled to a MATLAB `table` (`array2table`, names and
+    non-default index preserved). v1 supports numeric/logical columns; other column types raise
+    `NotImplementedError`.
+
+## [0.3.0] — unreleased
+
+### Added
+- On the **first `pyfsda.<name>(...)` call**, print (once, best-effort) the **latest FSDA release
+  available on GitHub** so you can check your install is current — a stdlib-only query of the FSDA
+  releases API, silent on any failure (offline / rate-limited), and gated by `check_version` (disable
+  with `pyfsda.start(check_version=False)`). This is separate from, and runs alongside, the existing
+  MATLAB-side `tuna` check at engine start.
+
+## [0.2.0] — unreleased
+
+### Added
+- **Functional façade:** call any FSDA routine as a top-level function, e.g.
+  `pyfsda.Score(y, X, la=..., intercept=True)` or `pyfsda.mahalFS(Y, MU, SIGMA)` — the shared MATLAB
+  session starts lazily on first use and is reused. Backed by a module-level `__getattr__`, so it
+  covers every FSDA routine with no per-function code; `from pyfsda import Score` works too.
+- Session helpers `pyfsda.start(...)`, `pyfsda.stop()`, `pyfsda.engine()`; the engine is also stopped
+  at interpreter exit. Unknown routine names raise a clear `AttributeError` (typo guard).
+
+## [0.1.0] — unreleased
+
+### Added
+- First packaged release of the generic FSDA ↔ Python bridge (`FsdaEngine`, `to_matlab`,
+  `from_matlab`), extracted from the `fsda_python_porting_test` prototype.
+- Routine-agnostic `call` / `eval` surface with generic marshalling
+  (numeric ↔ ndarray, struct ↔ dict, cell ↔ list, char ↔ str, table/timetable → dict,
+  2-D cell → nested list) via a MATLAB-workspace round-trip.
+- Best-effort FSDA up-to-date check at `start()` (FSDA `tuna`, quiet unless outdated;
+  disable with `check_version=False`).
+
+### Publishing note
+Releases are published to PyPI via GitHub Actions **trusted publishing** (OIDC) on a `v*` tag.
+One-time setup: register `pyfsda` as a Trusted Publisher on PyPI
+(project → *Publishing* → add the GitHub repo + `publish.yml` workflow).

pyfsda-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to pyfsda
+
+## Test layers
+
+| Layer | Marker | Needs MATLAB? | Where it runs |
+|---|---|---|---|
+| Marshalling unit tests (`tests/test_marshalling.py`) | *(none)* | No — only the `matlabengine` client (for `matlab.double`) | GitHub-hosted `build` job + locally |
+| Integration smoke (`tests/test_integration.py`) | `integration` | **Yes** — starts MATLAB via `matlab.engine` and calls FSDA | **Self-hosted runner only** + locally |
+
+Run locally:
+
+```bash
+pytest -m "not integration"     # unit tests
+pytest -m integration           # integration (needs MATLAB + FSDA)
+pytest                          # everything
+```
+
+## Why the integration tests need a self-hosted runner
+
+`pyfsda` drives MATLAB through the **MATLAB Engine API for Python**. MathWorks' hosted-runner
+licensing (`matlab-actions/setup-matlab`) uses **batch licensing**, which — per MathWorks —
+*does not support external language interfaces, including the MATLAB Engine APIs for Python, Java,
+.NET, COM, C, C++, and Fortran*. An `MLM_LICENSE_TOKEN` does **not** lift this: batch licensing simply
+cannot license the Engine API. The only supported path is a **self-hosted runner whose MATLAB is
+licensed without a batch token** (a normal individual/network license). Do not spend time trying to
+make the `matlab.engine` tests run on GitHub-hosted runners — it is not possible.
+
+## Registering a self-hosted runner (one time)
+
+On a machine that has a **normally-licensed MATLAB**, FSDA, a matching `matlabengine`, and Python:
+
+1. GitHub → repo **Settings → Actions → Runners → New self-hosted runner**; follow the install steps.
+2. Apply the labels the `integration` job targets: **`self-hosted`, `macOS`, `pyfsda-matlab`**
+   (adjust `macOS` if your runner is Linux/Windows, and update `runs-on` in
+   `.github/workflows/publish.yml` to match).
+3. Run the runner **as the user who holds the MATLAB license** (so `matlab.engine` can start MATLAB
+   non-interactively).
+
+### Runner prerequisites
+- **MATLAB** licensed **without** a batch token (individual or network license).
+- **FSDA** on that MATLAB's path (verify `which mahalFS` in MATLAB). If it is *not* on the default
+  path, set a repository variable **`PYFSDA_FSDA_ROOT`** to the FSDA install/checkout dir — the job
+  forwards it to `FsdaEngine.start(fsda_root=...)`.
+- A **`python3` on `PATH`** whose `matlabengine` matches the MATLAB release
+  (e.g. `matlabengine==26.1.*` for R2026a). The job builds a `--system-site-packages` venv so it
+  inherits that `matlabengine`.
+
+## Security
+
+A self-hosted runner executes workflow code **on your machine**. The `integration` job is therefore
+gated `if: github.event_name != 'pull_request'` and runs only on `push` / `workflow_dispatch`. **Never**
+enable it for `pull_request` events on a public repository — a fork's PR could run arbitrary code on
+your runner. Keep the guard in place.
+
+## Releasing to PyPI (manual, with twine)
+
+Publishing is **irreversible**: a given version/filename can never be re-uploaded and the name is
+claimed permanently. Always validate on **TestPyPI** first.
+
+### One-time: accounts + tokens
+1. Create accounts on <https://test.pypi.org> and <https://pypi.org> and generate an **API token** on
+   each (Account settings → API tokens).
+2. Store them in `~/.pypirc` (chmod 600), never in the repo:
+
+   ```ini
+   [distutils]
+   index-servers =
+       pypi
+       testpypi
+
+   [pypi]
+   username = __token__
+   password = pypi-XXXXXXXX            # your real-PyPI token
+
+   [testpypi]
+   username = __token__
+   password = pypi-YYYYYYYY            # your TestPyPI token
+   ```
+
+### Each release
+```bash
+cd packages/pyfsda
+rm -rf dist
+python -m build                        # fresh sdist + wheel into dist/
+twine check dist/*                     # metadata + README render must PASS
+
+# 1) DRY-RUN on TestPyPI, then eyeball https://test.pypi.org/project/pyfsda/
+twine upload -r testpypi dist/*
+
+# 2) only once TestPyPI looks right: publish to real PyPI
+twine upload dist/*
+```
+
+A version can only be uploaded **once** to each index (TestPyPI included) — if you need to re-test after
+a fix, bump the version (e.g. `0.1.1`) in `src/pyfsda/__init__.py` and rebuild.

pyfsda-0.4.0/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.

pyfsda-0.4.0/PKG-INFO

@@ -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.