texgisa-survival 2.2.0__tar.gz

texgisa_survival-2.2.0/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: Test source candidate
+on: [push, pull_request]
+jobs:
+  tests:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.11', '3.12']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install ".[dev,recipes,baselines]" build
+      - run: python -m pytest tests --override-ini="addopts="
+      - run: python -m build

texgisa_survival-2.2.0/.github/workflows/release.yml

@@ -0,0 +1,91 @@
+name: Release
+
+# Publishes to PyPI with Trusted Publishing (no API token stored in GitHub).
+# One-time setup on pypi.org and test.pypi.org: add a "pending publisher" for
+#   owner: Kunjoe7, repository: texgisa-survival, workflow: release.yml,
+#   environment: pypi (PyPI) / testpypi (TestPyPI)
+#
+# - Manual run (Actions tab -> Release -> Run workflow): build, test, upload to TestPyPI
+# - Publishing a GitHub release (tag vX.Y.Z): build, test, upload to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check --strict dist/*
+      - name: Check that the tag matches the package version
+        if: github.event_name == 'release'
+        run: |
+          VERSION=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v${VERSION}" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != v${VERSION}"; exit 1; }
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  test-wheel:
+    needs: build
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Install the built wheel and run the tests against it
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          WHEEL=$(ls dist/*.whl)
+          python -m pip install "${WHEEL}[recipes,baselines]" pytest
+          mv src src_unused   # make sure the installed wheel is tested, not the source tree
+          python -m pytest tests -q --override-ini="addopts="
+
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    needs: test-wheel
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: github.event_name == 'release'
+    needs: test-wheel
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

texgisa_survival-2.2.0/API_REFERENCE.md

@@ -0,0 +1,11 @@
+# Current API
+
+`SurvivalRecipe(recipe="RefineCDF", dataset="custom", config_id=0, config=None, random_state=271, threads=1)` implements `fit(X,time,event)`, `predict_risk(X)`, `predict_survival(X,times=None)`, `predict_time(X)`, `explain(X,integration_steps=20,time_samples=None)` and `save(path)`.
+
+Pandas column names/order must match at prediction. NumPy inputs receive x0,x1,... column names. Features must be finite numeric values; explicit category encoding belongs to the caller. Named domain rules validate their required feature names. No test outcomes are accepted by prediction methods. The reference for TEXGI and all internal transformations are fitted on training subsets.
+
+`metadata_` records fitting/stopping/calibration row indices, epoch selection, calibration, prior diagnostics and output semantics. `config_` records the effective configuration. `feature_names_in_`, `n_features_in_` and `time_grid_` expose input/grid metadata. Recipe save files contain model objects and must be treated as trusted-code artifacts.
+
+`available_recipes()` lists8 callable own variants. `backends.runner.available_methods()` lists20 public-package/author-array routes plus3 author CLI routes. `fit_predict` returns a dictionary rather than falsely promising every native estimator implements every prediction type. `run_author_cli` accepts an original author checkout, argv and an optional interpreter/log path; exceptions preserve author failures. Source code is never modified by the runner.
+
+The inherited `TexGISa` class remains available at package root. Its legacy constructor and rule methods are defined in `api.py`; current benchmark numbers correspond to `SurvivalRecipe`, not a default legacy estimator.

texgisa_survival-2.2.0/BACKENDS.md

@@ -0,0 +1,25 @@
+# Existing-method backends
+
+Native inputs: finite numeric fitting matrix, observed durations, binary event indicator, and query matrix. No user innovation modules are fed into a baseline.
+
+| Route | Provider | Outputs | Dependency/runtime |
+|---|---|---|---|
+| Cox, Weibull, Lognormal, Loglogistic | lifelines | native risk, survival and median | baselines extra |
+| Coxnet, RandomSurvivalForest, GradientBoostingCox | scikit-survival | native risk and survival | baselines extra |
+| DeepSurv, CoxTime, CoxCC, DeepHit, LogisticHazard, PCHazard, PMF, MTLR, NMTLR | pycox | estimator-specific risk and/or native curve | baselines extra |
+| HarrellNMSE, HarrellNMAE, UnoNMSE, UnoNMAE | original ICDM2021 source | scalar time and negative-time risk, no curve | separate NumPy1.x interpreter; author_source argument |
+| DRO | author run_dro_cox_split.py | original CLI outputs/files | run_author_cli; original formats/environment |
+| Kernet | author demo_tuna_kernet.py | original CLI outputs/files | run_author_cli; teacher/config files as upstream requires |
+| SODEN | author main.py | original CLI outputs/files | run_author_cli; original formats/environment |
+
+`fit_predict(...,python_executable=...,author_source=...)` isolates original scalar-time code. The6 original ICDM2021 source hashes are verified before import. No missing NumPy aliases are injected. Author source: https://github.com/yanlirock/local_global_survival at commit2eee054ccbf8b8ab9750c79d640ce72ef8f836d1.
+
+Classical public configurations use `pen` and Cox `l1`; Coxnet uses `alpha,l1_ratio`; RSF uses `n_estimators,max_depth,min_samples_leaf`; boosted Cox uses `n_estimators,learning_rate,max_depth,min_samples_leaf,subsample`. Neural configurations use the frozen `native_configs.json` keys, including hidden/dropout/lr/wd/batch/epochs/patience and model-specific bins/alpha/sigma. Defaults are the first saved configuration, not an automatic test-selected best model.
+
+Native arrays are not clipped or repaired. Deriving a common evaluation metric from them is a separate operation. Infinities or unsupported outputs remain visible. Author CLI data adapters in the companion reproduction directory document the exact experimental IO changes; they do not alter author losses, networks or optimizers. A method's upstream data-format requirements remain part of the contract.
+
+Optional libraries are installed from their distributions; they are not relicensed as MIT by this wrapper. Keep GPL-licensed dependency terms and any upstream author-source terms when redistributing combined works. This archive does not bundle those author implementations.
+
+## Method provenance
+
+The original scalar-time objectives are described by Wang, Li and Chignell, "Combining Ranking and Point-wise Losses for Training Deep Survival Analysis Models," ICDM2021,689–698, DOI10.1109/ICDM51629.2021.00080. Survival kernets: Chen, JMLR25(40):1–78,2024, https://jmlr.org/papers/v25/22-0667.html . Sample-split DRO: Hu and Chen, JMLR25(246):1–85,2024, https://jmlr.org/papers/v25/23-0888.html . Package-specific method documentation remains the authority for each native estimator.

texgisa_survival-2.2.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changes
+
+## 2.2.0 (2026-11-12)
+
+- Add `skills/texgisa-prior-finder`, a step-by-step procedure for finding expert priors
+  (important-feature lists and directional rules) in published sources, with provenance and a
+  final review by a domain expert.
+- Add `SurvivalRecipe`, the tuned default configuration of TexGISa, with separate
+  `predict_risk`, `predict_survival`, `predict_time` and `explain` outputs.
+- Add `backends.runner`: one call (`fit_predict`) to 20 established survival models from
+  lifelines, scikit-survival, pycox and the original ICDM 2021 code, each run unchanged in its own
+  process; `run_author_cli` runs DRO, survival kernets and SODEN through their authors' programs.
+- Keep fitted preprocessing, training partitions and calibration diagnostics with the model.
+- Benchmark records, configurations and summaries in `benchmarks/`.
+
+## 2.1.0
+
+- Benchmark scripts and per-fold results in `benchmarks/`; defaults set from nested
+  cross-validation.
+
+## 2.0.1
+
+- Attribution priors now back-propagate to the network (`create_graph=True`).
+- Fix the sign of `concordance_index`, rule thresholds on standardized features,
+  save/load, and the Brier-score column alignment.
+- Fix `MySATrainer` on recent PyTorch releases.
+
+## 2.0.0
+
+- First public release on GitHub.

texgisa_survival-2.2.0/CITATION.cff

@@ -0,0 +1,62 @@
+cff-version: 1.2.0
+title: "texgisa-survival: Interpretable and Interactive Deep Discrete-Time Survival Analysis"
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file, and cite the method paper below.
+type: software
+authors:
+  - family-names: Qin
+    given-names: Xinyu
+    affiliation: Baylor University
+    email: Xinyu_Qin1@baylor.edu
+  - family-names: Yu
+    given-names: Ruiheng
+    affiliation: Florida State University
+    email: ry26@fsu.edu
+  - family-names: Li
+    given-names: Yan
+    affiliation: University of Toronto
+  - family-names: Wang
+    given-names: Lu
+    affiliation: Baylor University
+    email: Lu_Wang@baylor.edu
+repository-code: 'https://github.com/Kunjoe7/texgisa-survival'
+url: 'https://github.com/Kunjoe7/texgisa-survival'
+abstract: >-
+  A PyTorch library for discrete-time deep survival analysis with
+  time-dependent feature attributions computed against extreme baselines
+  (TEXGI) and attribution priors that let domain experts shape training.
+keywords:
+  - survival analysis
+  - deep learning
+  - explainable AI
+  - interactive machine learning
+license: MIT
+version: 2.2.0
+date-released: 2026-11-12
+preferred-citation:
+  type: conference-paper
+  authors:
+    - family-names: Qin
+      given-names: Xinyu
+    - family-names: Yu
+      given-names: Ruiheng
+    - family-names: Khayati
+      given-names: Armin
+    - family-names: Qiu
+      given-names: Zixiao
+    - family-names: Zou
+      given-names: Gengyi
+    - family-names: Li
+      given-names: Yan
+    - family-names: Wang
+      given-names: Lu
+  title: >-
+    Interpretable and Interactive Deep Survival Analysis with
+    Time-dependent EXtreme Gradient Integration
+  collection-title: >-
+    2025 IEEE International Conference on Data Mining (ICDM)
+  year: 2025
+  start: 673
+  end: 682
+  doi: 10.1109/ICDM65498.2025.00075

texgisa_survival-2.2.0/CONTRIBUTING.md

@@ -0,0 +1,327 @@
+# Contributing to DHAI Survival
+
+First off, thank you for considering contributing to DHAI Survival! It's people like you that make DHAI Survival such a great tool for the survival analysis community.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [How Can I Contribute?](#how-can-i-contribute)
+- [Development Setup](#development-setup)
+- [Style Guidelines](#style-guidelines)
+- [Commit Messages](#commit-messages)
+- [Pull Request Process](#pull-request-process)
+- [Community](#community)
+
+## Code of Conduct
+
+Contributors should communicate respectfully and describe reproducible technical issues. Use the [public issue tracker](https://github.com/Kunjoe7/texgisa-survival/issues) for project discussions.
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork locally
+3. Create a new branch for your contribution
+4. Make your changes
+5. Push to your fork and submit a pull request
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues as you might find that you don't need to create one. When you are creating a bug report, please include as many details as possible:
+
+- **Use a clear and descriptive title**
+- **Describe the exact steps to reproduce the problem**
+- **Provide specific examples** to demonstrate the steps
+- **Describe the behavior you observed** and explain why it's a problem
+- **Explain the behavior you expected** to see instead
+- **Include screenshots** if relevant
+- **Include your environment details** (Python version, OS, package versions)
+
+### Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:
+
+- **Use a clear and descriptive title**
+- **Provide a detailed description** of the suggested enhancement
+- **Provide specific examples** to demonstrate the enhancement
+- **Describe the current behavior** and explain why it's insufficient
+- **Explain why this enhancement would be useful** to most users
+- **List any alternatives** you've considered
+
+### Code Contributions
+
+#### Your First Code Contribution
+
+Unsure where to begin? You can start by looking through these issues:
+
+- Issues labeled `good first issue` - issues which should be relatively simple to implement
+- Issues labeled `help wanted` - issues which need extra attention
+- Issues labeled `documentation` - improvements or additions to documentation
+
+#### Development Setup
+
+1. **Fork and clone the repository**
+   ```bash
+   git clone https://github.com/Kunjoe7/texgisa-survival.git
+   cd texgisa_survival
+   ```
+
+2. **Create a virtual environment**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install in development mode**
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+4. **Install pre-commit hooks**
+   ```bash
+   pre-commit install
+   ```
+
+5. **Create a branch for your feature**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+### Adding New Models
+
+If you're adding a new survival model:
+
+1. Create a new module in `src/texgisa_survival/models/`
+2. Inherit from the `BaseModel` class
+3. Implement required methods: `fit()`, `predict_risk()`, etc.
+4. Add comprehensive tests in `tests/test_models.py`
+5. Add documentation with examples
+6. Update the README with model description
+
+Example structure:
+```python
+from texgisa_survival.models.base import BaseModel
+
+class YourModel(BaseModel):
+    """
+    Your model description.
+    
+    Parameters
+    ----------
+    input_dim : int
+        Number of input features
+    **kwargs
+        Additional parameters
+    
+    Examples
+    --------
+    >>> model = YourModel(input_dim=10)
+    >>> model.fit(X_train, y_train, e_train)
+    >>> risk_scores = model.predict_risk(X_test)
+    """
+    
+    def __init__(self, input_dim, **kwargs):
+        super().__init__(input_dim, **kwargs)
+        # Your initialization code
+    
+    def fit(self, X, y, e, **kwargs):
+        """Fit the model"""
+        # Your training code
+    
+    def predict_risk(self, X):
+        """Predict risk scores"""
+        # Your prediction code
+```
+
+## Style Guidelines
+
+### Python Style Guide
+
+We use [PEP 8](https://www.python.org/dev/peps/pep-0008/) with the following specifications:
+
+- Line length: 100 characters
+- Use type hints where possible
+- Document all public functions with NumPy-style docstrings
+
+We enforce style using:
+- `black` for code formatting
+- `flake8` for linting
+- `mypy` for type checking
+- `isort` for import sorting
+
+Run these tools before committing:
+```bash
+black src/
+flake8 src/
+mypy src/texgisa_survival
+isort src/
+```
+
+Or use pre-commit:
+```bash
+pre-commit run --all-files
+```
+
+### Documentation Style
+
+- Use NumPy style for docstrings
+- Include type hints in function signatures
+- Provide examples in docstrings where helpful
+- Keep documentation up-to-date with code changes
+
+Example docstring:
+```python
+def concordance_index(y_true, y_pred, e):
+    """
+    Calculate the concordance index for survival analysis.
+    
+    Parameters
+    ----------
+    y_true : array-like, shape = [n_samples]
+        True survival times
+    y_pred : array-like, shape = [n_samples]
+        Predicted risk scores
+    e : array-like, shape = [n_samples]
+        Event indicators (1 if event occurred, 0 if censored)
+    
+    Returns
+    -------
+    float
+        Concordance index between 0 and 1
+    
+    Examples
+    --------
+    >>> c_index = concordance_index([1, 2, 3], [0.5, 0.3, 0.1], [1, 1, 0])
+    >>> print(f"C-index: {c_index:.3f}")
+    C-index: 1.000
+    """
+```
+
+## Testing
+
+### Writing Tests
+
+- Write tests for any new functionality
+- Ensure all tests pass before submitting PR
+- Aim for high test coverage (>90%)
+- Use pytest for testing
+
+Run tests:
+```bash
+pytest tests/
+```
+
+Run tests with coverage:
+```bash
+pytest tests/ --cov=texgisa_survival --cov-report=html
+```
+
+### Test Structure
+
+```python
+import pytest
+from texgisa_survival.your_module import your_function
+
+class TestYourFunction:
+    def test_normal_case(self):
+        """Test normal operation"""
+        result = your_function(input_data)
+        assert result == expected_output
+    
+    def test_edge_case(self):
+        """Test edge cases"""
+        with pytest.raises(ValueError):
+            your_function(invalid_input)
+    
+    @pytest.mark.parametrize("input,expected", [
+        (1, 2),
+        (2, 4),
+        (3, 6),
+    ])
+    def test_multiple_cases(self, input, expected):
+        """Test multiple cases"""
+        assert your_function(input) == expected
+```
+
+## Commit Messages
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+- `feat:` A new feature
+- `fix:` A bug fix
+- `docs:` Documentation only changes
+- `style:` Changes that don't affect code meaning
+- `refactor:` Code change that neither fixes a bug nor adds a feature
+- `perf:` Code change that improves performance
+- `test:` Adding missing tests or correcting existing tests
+- `build:` Changes that affect the build system or dependencies
+- `ci:` Changes to CI configuration files and scripts
+- `chore:` Other changes that don't modify src or test files
+
+Examples:
+```
+feat: add TexGISa model for interpretable survival analysis
+fix: correct concordance index calculation for tied events
+docs: update installation instructions for Windows users
+test: add integration tests for model comparison
+```
+
+## Pull Request Process
+
+1. **Ensure your code follows the style guidelines**
+2. **Update documentation** for any changed functionality
+3. **Add tests** for new functionality
+4. **Ensure all tests pass** locally
+5. **Update the CHANGELOG.md** with your changes
+6. **Create a pull request** with a clear title and description
+
+### PR Checklist
+
+- [ ] Code follows project style guidelines
+- [ ] Tests added/updated and passing
+- [ ] Documentation updated
+- [ ] CHANGELOG.md updated
+- [ ] Commit messages follow conventions
+- [ ] PR has descriptive title and description
+- [ ] All CI checks passing
+
+### PR Review Process
+
+1. At least one maintainer review required
+2. All CI checks must pass
+3. No merge conflicts
+4. Discussions resolved
+
+## Release Process
+
+Releases are managed by maintainers following semantic versioning:
+
+1. Update version in `pyproject.toml`
+2. Update CHANGELOG.md
+3. Create git tag
+4. GitHub Actions automatically publishes to PyPI
+
+## Community
+
+### Getting Help
+
+- GitHub Issues for bug reports and feature requests
+- GitHub Discussions for general questions
+- Email: the public issue tracker at https://github.com/Kunjoe7/texgisa-survival/issues
+
+### Acknowledgments
+
+Contributors will be acknowledged in:
+- The AUTHORS file
+- Release notes
+- Project documentation
+
+## Questions?
+
+Feel free to contact the maintainers if you have any questions about contributing. We're here to help and look forward to your contributions!
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

texgisa_survival-2.2.0/EXTENSIONS_SINCE_ICDM.md

@@ -0,0 +1,3 @@
+# Software changes since the method publication
+
+Relative to the method described by Qin et al. (ICDM2025), the review candidate adds a fitted multi-output recipe interface, explicit risk/curve/point semantics, eight experiment-backed own-model recipes, two calibration choices, train-only split/epoch/config provenance, and isolated optional baseline/author-CLI invocation. The legacy estimator and TEXGI functions remain available. Benchmark replay and table reconstruction are supplied separately. These are source-verified software capabilities, not a claim that all changes were independently isolated in accuracy ablations.

texgisa_survival-2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DHAI Lab
+
+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.

texgisa_survival-2.2.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md LICENSE CHANGELOG.md CITATION.cff
+include SCIENTIFIC_NOTES.md API_REFERENCE.md BACKENDS.md CONTRIBUTING.md EXTENSIONS_SINCE_ICDM.md
+recursive-include .github/workflows *.yml
+recursive-include tests *.py
+recursive-include examples *.py
+recursive-include benchmarks *.py *.json *.md
+recursive-include skills *.md
+global-exclude *.py[cod] __pycache__ *.pt *.pkl