gemss 1.0.1__tar.gz

gemss-1.0.1/.github/semantic-release-templates/.release_notes.md.j2

@@ -0,0 +1,38 @@
+{# Release notes for the current version only. #}
+{%- set type_groups = {
+  "✨ Changes": ["feat", "fix"],
+  "⚡ Performance": ["perf"],
+  "🧹 Refactors": ["refactor"],
+  "📚 Docs": ["docs"],
+  "🧪 Tests": ["test"],
+  "🛠️ Chore": ["chore", "build", "ci"]
+} -%}
+
+## {{ version }}
+{%- set authors = [] -%}
+{%- for group_title, types in type_groups.items() %}
+{%- set group_commits = [] -%}
+{%- for commit_type in types -%}
+{%- for commit in release.elements.get(commit_type, []) -%}
+{%- set _ = group_commits.append(commit) -%}
+{%- endfor -%}
+{%- endfor -%}
+{%- if group_commits %}
+### {{ group_title }}
+{%- for commit in group_commits %}
+{%- set pr_url = commit.linked_merge_request | pull_request_url -%}
+- {{ commit.descriptions | join(" ") }}{% if commit.linked_merge_request %} ({% if pr_url %}[{{ commit.linked_merge_request }}]({{ pr_url }}){% else %}{{ commit.linked_merge_request }}{% endif %}){% endif %}
+{%- set author_name = commit.commit.author.name -%}
+{%- if author_name and author_name not in authors -%}
+{%- set _ = authors.append(author_name) -%}
+{%- endif -%}
+{%- endfor %}
+{%- endif %}
+{%- endfor %}
+
+{%- if authors %}
+### 👥❤️ Authors
+{%- for author in authors %}
+- {{ author }}
+{%- endfor %}
+{%- endif %}

gemss-1.0.1/.github/versionrc

@@ -0,0 +1,21 @@
+# Convco / conventional commits config (see https://convco.github.io/configuration/)
+# Used by: PR title check (convco check) only. Changelog is generated by python-semantic-release.
+
+# Allowed commit types. Add/remove as needed.
+types:
+  - type: feat
+  - type: fix
+  - type: docs
+  - type: refactor
+  - type: perf
+  - type: test
+  - type: build
+  - type: ci
+  - type: chore
+
+# Allowed scopes (enumerated). Convco uses a regex: list scopes as (scope1|scope2|...).
+# The ? makes scope optional so "feat: add X" (no scope) also passes.
+scopeRegex: "^(gemss)?$"
+
+# Max length of the first line (type + scope + description). 0 = no limit.
+lineLength: 100

gemss-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, reopened, edited, synchronize]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-python: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check gemss
+
+      - name: Format
+        run: uv run ruff format gemss --check
+
+      - name: Test
+        run: uv run pytest

gemss-1.0.1/.github/workflows/pr-title.yml

@@ -0,0 +1,27 @@
+name: PR Title
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, reopened, edited, synchronize]
+
+env:
+  CONVCO_VERSION: v0.4.2
+
+jobs:
+  validate:
+    runs-on: ubuntu-slim
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install convco
+        run: |
+          curl -sSfL "https://github.com/convco/convco/releases/download/${{ env.CONVCO_VERSION }}/convco-ubuntu.zip" \
+            | zcat \
+            > /usr/local/bin/convco
+          chmod +x /usr/local/bin/convco
+      - name: Check PR Title is Conventional
+        run: |
+          echo "${{ github.event.pull_request.title }}" \
+            | convco check \
+              --from-stdin \
+              --config .github/versionrc

gemss-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,152 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  build-dist:
+    runs-on: ubuntu-slim
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-python: true
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-preflight
+          path: dist/
+
+  test-built-package:
+    runs-on: ubuntu-slim
+    needs: build-dist
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-preflight
+          path: dist
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-python: true
+
+      - name: Create virtualenv
+        run: uv venv
+
+      - name: Install built wheel
+        run: uv pip install dist/*.whl
+
+      - name: Smoke test
+        run: uv run python -c "import gemss; print(gemss.__version__)"
+
+  release:
+    runs-on: ubuntu-slim
+    needs: test-built-package
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.outputs.outputs.released }}
+      version: ${{ steps.outputs.outputs.version }}
+      tag: ${{ steps.outputs.outputs.tag }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-python: true
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run semantic-release version
+        id: psr
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run semantic-release version --no-changelog
+
+      - name: Set job outputs
+        id: outputs
+        run: |
+          version=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ -n "$(ls -A dist 2>/dev/null)" ]; then
+            echo "released=true" >> $GITHUB_OUTPUT
+          else
+            echo "released=false" >> $GITHUB_OUTPUT
+          fi
+          echo "version=$version" >> $GITHUB_OUTPUT
+          echo "tag=v$version" >> $GITHUB_OUTPUT
+
+      - name: Upload dist artifact
+        if: steps.outputs.outputs.released == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-slim
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+          enable-cache: true
+          cache-python: true
+
+      - name: Publish GitHub release notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: uv run semantic-release publish
+
+      - name: Publish to PyPI
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          for f in dist/*.whl dist/*.tar.gz; do
+            [ -f "$f" ] || continue
+            uv publish "$f" --token "$PYPI_TOKEN"
+          done

gemss-1.0.1/.gitignore

@@ -0,0 +1,37 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Project specific
+*.html
+*.parquet
+
+# IDEs and editors
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Ignore notebook results
+notebooks/results/
+notebooks/*.txt
+
+# Ignore logs
+scripts/results/logs/
+
+# Ignore data
+data/
+
+# Ignore private files and select folders
+private/
+notebooks/private/
+
+# Ignore running marimo files
+app/__marimo__/*
+app/results/*

gemss-1.0.1/.python-version

@@ -0,0 +1 @@
+3.13

gemss-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Katerina Henclova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gemss-1.0.1/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: gemss
+Version: 1.0.1
+Summary: GEMSS: Gaussian Ensemble for Multiple Sparse Solutions.
+Project-URL: Repository, https://github.com/kat-er-ina/gemss
+Author-email: Katerina Henclova <katerina.henclova@datamole.ai>, Marek Nevole <nevole.marek@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: alternative-feature-selection,bayesian,feature-selection,interpretability,machine-learning,predictive-multiplicity,rashomon-effect,sparse-regression,variational-inference
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.13
+Requires-Dist: ipywidgets>=8.0.0
+Requires-Dist: jupyter<2.0.0,>=1.0.0
+Requires-Dist: marimo>=0.19.6
+Requires-Dist: numpy>=1.23.0
+Requires-Dist: pandas<3.0.0,>=2.0.0
+Requires-Dist: plotly>=5.15.0
+Requires-Dist: pyarrow>=22.0.0
+Requires-Dist: scikit-learn<2.0.0,>=1.3.0
+Requires-Dist: scipy
+Requires-Dist: shap>=0.48.0
+Requires-Dist: tabpfn>=1.1.0
+Requires-Dist: torch<3.0.0,>=2.0.0
+Requires-Dist: tqdm>=4.65.0
+Description-Content-Type: text/markdown
+
+# GEMSS: Gaussian Ensemble for Multiple Sparse Solutions
+
+This repository implements Bayesian sparse feature selection using variational inference with Gaussian mixture models. The main objective is to recover all sparse feature subsets (supports) that explain the response in high-dimensional regression or classification tasks.
+
+**To make this tool accessible by non-coders (typically domain experts), we provide a [user-friendly application](./app/README.md) for the entire exploratory GEMSS workflow.**
+
+## Motivation
+
+In many real-world problems, e.g. in life sciences, datasets with far more features than samples are common because collecting new data points is costly or impractical. In these situations, there are often several distinct, sparse combinations of features that can explain the observed outcomes, each corresponding to a different underlying mechanism or hypothesis. Moreover, in many cases, the quality of a combination of predictors can be assessed only ex-post by utilizing advanced domain knowledge.
+
+Traditional feature selection methods typically identify only a single solution to a classification or regression problem, overlooking the ambiguity and the potential for multiple valid interpretations. This project addresses that gap by providing a Bayesian framework that systematically recovers all plausible sparse solutions, enabling a more complete understanding of the data and supporting the exploration and comparison of alternative explanatory hypotheses.
+
+
+## When to use GEMSS
+
+Instead of finding just one "best" set of features, GEMSS discovers **several most likely feature combinations** that predict your target variable comparably well. This is valuable when:
+
+- You have precious few samples and many more features.
+- Multiple underlying mechanisms might explain your data.
+- You are striving for an interpretable model.
+- You want to engineer a multitude of nonlinear and combined features from your original set for exploratory purposes.
+- Your features are correlated.
+- When there is domain knowledge to be mined (a human in the loop).
+
+
+### When NOT to use GEMSS
+
+- When the desired number of features you are looking for exceeds approximately 10-20.
+- Inside automated modeling pipelines.
+
+
+## Features
+
+GEMSS provides a comprehensive framework for Bayesian feature selection with the following capabilities:
+
+* **Multiple sparse solutions:** Recovers diverse sparse feature sets rather than a single solution
+* **Missing data:** Native handling without imputation
+* **Flexible priors:** Structured spike-and-slab (default), Student-t, vanilla spike-and-slab
+* **Variational inference:** PyTorch-based optimization
+* **Diversity regularization:** Optional Jaccard penalty for enforcing solution diversity
+* **Visualization:** Interactive plots and comprehensive diagnostics
+* **Modular configuration:** JSON-based dataset/algorithm/postprocessing settings
+* **Batch experiments:** Parameter sweeps and tiered validation suites
+
+
+## Citation
+
+If you use GEMSS in your research, please cite the [technical report](./technical_report.pdf):
+
+```bibtex
+@misc{GEMSS2026,
+  author = {Henclova, Katerina and Smidl, Vaclav},
+  title = {GEMSS: A Variational Bayesian Method for Discovering Multiple Sparse Solutions in Classification and Regression Problems},
+  year = {2026},
+  note = {arXiv preprint arXiv:XXXX.XXXXX}
+}
+```
+
+
+## Repository structure
+
+The repository is organized into core packages, interactive notebooks, batch experiment scripts, and configuration files:
+
+```
+gemss/
+  technical_report.pdf       # Preprint paper on GEMSS
+  app/                       # Interactive marimo app
+    gemss_explorer_noncommercial.py   # GEMSS explorer app with non-commercial TabPFN modeling add-on
+    gemss_explorer_unlimited.py       # GEMSS explorer app for unlimited use
+    results/                          # App outputs
+  data/                      # User datasets
+  notebooks/                 # Interactive demos and analysis
+    demo.ipynb               # End-to-end synthetic demo
+    explore_custom_dataset.ipynb      # Custom data workflow
+    tabpfn_evaluation_example.ipynb   # TabPFN evaluation demo
+    tabpfn_evaluate_custom_dataset_results.ipynb # Evaluate saved solutions with TabPFN
+    analyze_experiment_results/       # Experiment analysis (development)
+    results/                          # Artifacts from the notebook runs
+  scripts/                   # Batch experiments
+    run_experiment.py        # Single experiment
+    run_sweep.ps1            # Parameter sweeps
+    run_tiers.ps1            # Tiered benchmark suite
+    experiment_parameters.json    # 128-experiment design
+    results/                 # Outputs and logs from the scripted experiments
+  gemss/                     # Core package
+    config/                  # JSON configuration files
+    data_handling/           # Data generation and preprocessing
+    feature_selection/       # Variational inference core
+    postprocessing/          # Solution extraction and evaluation
+    diagnostics/             # Performance diagnostics (WIP)
+    experiment_assessment/   # Result analysis utilities
+    utils/                   # Persistence and visualization
+```
+
+## Package installation
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management. `uv` replaces tools like `pip`.
+
+### 1. Install uv
+If you do not have `uv` installed, run one of the following commands:
+
+**macOS/Linux:**
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**Windows:**
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### 2. Set up the environment
+
+Navigate to the repository root and sync the environment. This command will create a virtual environment and install all dependencies (including the `gemss` package itself) defined in `pyproject.toml`.
+
+```bash
+uv sync
+```
+
+⚠️ **Troubleshooting: important for Windows users:** `uv` is incompatible with the Windows Store Python distribution due to file system restrictions.
+
+If `uv sync` fails with an error like `Failed to build ... Failed to create temporary virtualenv ... The file cannot be accessed by the system. (os error 1920)`, this indicates that `uv` is trying to use the wrong version of Python. 
+
+To resolve this issue:
+
+1. **Check which Python installations you have:**
+   ```powershell
+   Get-Command python -All | Select-Object Source
+   ```
+
+2. **Install Python 3.13 using uv** (if not already installed):
+   ```powershell
+   uv python install 3.13
+   ```
+
+3. **Find the uv-managed Python path:**
+   ```powershell
+   uv python list
+   ```
+   Look for a path like `C:\Users\<YourUser>\AppData\Roaming\uv\python\cpython-3.13.11-windows-x86_64-none\python.exe`
+
+4. **Run uv sync with the correct Python:**
+   ```powershell
+   uv sync --python C:\Users\<YourUser>\AppData\Roaming\uv\python\cpython-<YourVersion>-windows-x86_64-none\python.exe
+   ```
+
+Alternatively, uninstall the Windows Store Python and install Python 3.13 from [python.org](https://www.python.org/downloads/), then run `uv sync` without the `--python` flag.
+
+### 3. Register the Jupyter kernel (optional)
+
+**Note:** This step is only required if you plan to use notebooks. The marimo app doesn't need kernel registration.
+
+To run Jupyter notebooks with the correct Python environment, register the kernel:
+
+```bash
+uv run python -m ipykernel install --user --name=gemss --display-name="Python (gemss)"
+```
+
+This makes the environment available. When opening a notebook, select "Python (gemss)" from the kernel picker.
+
+To verify the kernel is registered, run:
+
+```bash
+uv run jupyter kernelspec list
+```
+
+## Quick start
+
+GEMSS can be applied to both custom datasets and synthetic data for validation and benchmarking.
+
+### **GEMSS Explorer:** an interactive application (recommended)
+
+The easiest way to use GEMSS is through the interactive marimo app:
+
+```bash
+uv run marimo run app/gemss_explorer_unlimited.py      # Commercial use allowed
+uv run marimo run app/gemss_explorer_noncommercial.py  # Includes TabPFN modeling
+```
+
+The app provides a complete guided workflow from data upload through solution recovery and evaluation.
+
+**For detailed documentation, data requirements, and workflow overview, see [app/README.md](app/README.md).**
+
+### Jupyter notebooks
+
+For more control and customization, use the Jupyter notebooks:
+
+- [notebooks/demo.ipynb](notebooks/demo.ipynb) — complete walkthrough with synthetic data
+- [notebooks/explore_custom_dataset.ipynb](notebooks/explore_custom_dataset.ipynb) — custom data workflow
+- [notebooks/README.md](notebooks/README.md) — detailed documentation
+
+Launch notebooks with:
+
+```bash
+uv run jupyter notebook notebooks/demo.ipynb
+```
+
+## Proof-of-concept experiments
+
+A comprehensive experimental framework validates GEMSS across diverse data scenarios, from clean baseline conditions to challenging high-dimensional and noisy settings. One can review and replicate these experiments.
+
+There are 128 experiments organized in 7 tiers:
+
+* **Tier 1:** Baseline (18): clean data, n < p
+* **Tier 2:** High-dimensional (9): p ≥ 1000, n << p
+* **Tier 3:** Sample-rich (14): n ≥ p
+* **Tier 4:** Robustness (22): noise and missing data
+* **Tier 5:** Jaccard penalty (28): diversity effects
+* **Tier 6:** Regression (29): continuous response
+* **Tier 7:** Class imbalance (8): unbalanced labels
+
+Experiments are grouped into **47 test cases** addressing specific research questions.
+
+### Running experiments
+
+In order to use correct Python dependencies, it is recommended that scripts are run using `uv run python` instead of the `python` command.
+
+```bash
+# Single experiment
+uv run python scripts/run_experiment.py
+```
+
+**Batch experiments (PowerShell):** for the PowerShell scripts, it is often easier to activate the environment first:
+
+```bash
+# Activate environment (Windows)
+.venv\Scripts\activate.ps1
+```
+
+Then run:
+
+```bash
+# Parameter sweeps (custom parameter setting)
+.\scripts\run_sweep.ps1
+
+# The benchmark (128 experiments)
+.\scripts\run_tiers.ps1                          # Full suite
+.\scripts\run_tiers.ps1 -tiers @("1","4")        # Selected tiers
+```
+
+### Result analysis
+
+* [notebooks/analyze_experiment_results/tier_level_analysis.ipynb](notebooks/analyze_experiment_results/tier_level_analysis.ipynb) — tier-level performance
+* [notebooks/analyze_experiment_results/analysis_per_testcase.ipynb](notebooks/analyze_experiment_results/analysis_per_testcase.ipynb) — cross-tier research questions
+
+
+**For more details, see the dedicated documentation:** [scripts/README.md](scripts/README.md)
+
+
+## License
+
+The GEMSS algorithm is licensed under the MIT License.
+
+The optional add-on for modeling, [TabPFN](https://huggingface.co/Prior-Labs/tabpfn_2_5), is used in compliance with its non-commercial [license](https://huggingface.co/Prior-Labs/tabpfn_2_5#licensing).