starlibpy 0.3.0b2__tar.gz

starlibpy-0.3.0b2/ACKNOWLEDGMENTS.md

@@ -0,0 +1,11 @@
+# Acknowledgments
+
+Starlibpy is built on the Python scientific ecosystem. The project acknowledges
+the authors, maintainers, and contributors of Python, NumPy, pandas, SciPy,
+statsmodels, Patsy, scikit-learn, Matplotlib, Jinja2, lifelines,
+scikit-posthocs, PyYAML, openpyxl, python-docx, Pillow, webcolors, and PyArrow.
+
+Attribution to an upstream project does not imply that its authors created,
+reviewed, endorsed, or assume responsibility for Starlibpy. Statistical and
+clinical users remain responsible for verifying that the chosen method matches
+their protocol, estimand, data-generating process, and applicable guidance.

starlibpy-0.3.0b2/AUTHORS.md

@@ -0,0 +1,17 @@
+# Authors and contributors
+
+## Project creator and principal author
+
+**Dr. M.A. Melzi, MD**
+
+Creator of **Starlibpy — Statistical Tools for Academic Research Library**;
+author of its scientific architecture, public API, integration logic, result-object
+system, reporting conventions, and Starlibpy-specific implementation.
+
+## Future contributors
+
+Contributors should be listed by contribution type: source code, statistical
+validation, clinical review, documentation, testing, translations, or maintenance.
+Upstream-library authors retain authorship of their respective projects and are
+credited separately in `ACKNOWLEDGMENTS.md`, `REFERENCES.bib`, and
+`THIRD_PARTY_LICENSES.md`.

starlibpy-0.3.0b2/BUILD_MANIFEST.md

@@ -0,0 +1,58 @@
+# Build manifest
+
+**Project:** Starlibpy — Statistical Tools for Academic Research Library
+**Version:** 0.3.0b2
+**Project author:** Dr. M.A. Melzi, MD
+**Recommended import:** `import starlibpy as slp`
+
+## Source composition
+
+| Item | Count |
+|---|---:|
+| Python source files | 77 |
+| Source lines | 22251 |
+| Root-level public API symbols | 364 |
+| Public functions declared by submodules | 364 |
+| Public classes declared by submodules | 59 |
+| Public constants declared by submodules | 57 |
+| Test files | 12 |
+| Executable examples | 3 |
+| Automated tests passing | 95 |
+
+## Packaged submodules
+
+- `starlibpy.agreement`
+- `starlibpy.anova`
+- `starlibpy.association`
+- `starlibpy.assumptions`
+- `starlibpy.clinical`
+- `starlibpy.colors`
+- `starlibpy.comparisons`
+- `starlibpy.data`
+- `starlibpy.descriptive`
+- `starlibpy.design`
+- `starlibpy.diagnostic`
+- `starlibpy.effect_sizes`
+- `starlibpy.equivalence`
+- `starlibpy.estimation`
+- `starlibpy.longitudinal`
+- `starlibpy.multiplicity`
+- `starlibpy.plugins`
+- `starlibpy.regression`
+- `starlibpy.reporting`
+- `starlibpy.resampling`
+- `starlibpy.results`
+- `starlibpy.survival`
+
+## Distribution contents
+
+- PEP 517/518 `pyproject.toml` configuration;
+- MIT license and third-party license inventory;
+- `CITATION.cff`, authorship, acknowledgments and references;
+- source package under `src/starlibpy`;
+- typed marker `py.typed`;
+- automated tests and executable examples;
+- architecture, API, dependency, extension, migration and status documents;
+- wheel and source distribution generated from this tree.
+
+Cryptographic hashes are provided separately in `SHA256SUMS.txt`.

starlibpy-0.3.0b2/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.3.0b2 — 2026-08-26
+
+Publication-candidate cleanup of the 0.3.0 beta architecture.
+
+### Changed
+
+- Replaced root and internal star imports with explicit public APIs.
+- Preserved the 364-symbol root API used by `import starlibpy as slp`.
+- Centralized the build version in `starlibpy._version`.
+- Modernized imports, annotations, UTC handling, and code formatting.
+- Removed unused imports and resolved all Ruff warnings.
+- Raised the minimum setuptools build backend to 77.0.3 for PEP 639 license metadata support.
+
+### Validation
+
+- `python -m ruff check src tests`: passed.
+- `python -m ruff format --check src tests`: passed.
+- `python -m pytest -q`: 95 tests passed.
+- `python -m pip check`: no broken requirements.
+
+## 0.3.0b1 — 2026-08-24
+
+Complete architectural replacement of the former flat package.
+
+### Added
+
+- Canonical identity: **Starlibpy — Statistical Tools for Academic Research Library**.
+- Recommended import: `import starlibpy as slp`.
+- Typed scientific result objects (`StarResult`, `StarTable`, `StarFigure`).
+- Study and analysis design objects with validation and provenance.
+- Data profiling, quality checks, missing-data analysis, preparation, and audit.
+- Descriptive statistics, estimation, assumptions, test recommendation, comparisons,
+  correlations, ANOVA, longitudinal models, regression, diagnostic accuracy,
+  survival, agreement, multiplicity, resampling, equivalence, and non-inferiority.
+- Clinical adverse-event analyses and an explicitly experimental target-lesion
+  RECIST 1.1 component.
+- Automatic publication-table and plot rendering.
+- Accessible color palettes, contrast validation, themes, and palette generation.
+- Plugin registry and `starlibpy.plugins` entry-point loading for complementary modules.
+- Optional dependency groups and reproducibility metadata.
+- Deprecation wrappers for selected former public names.
+
+### Changed
+
+- Calculation, rendering, and export are separate responsibilities.
+- Optional analysis engines no longer prevent package import.
+- Numerical outputs remain unrounded until the reporting layer.
+
+### Removed from the stable API
+
+- Implicit printing, plotting, or file writing from statistical functions.
+- Silent outlier deletion.
+- Duplicate statistical primitives and versioned public function names.

starlibpy-0.3.0b2/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use Starlibpy, cite this software and the upstream scientific libraries used by your analysis."
+title: "Starlibpy: Statistical Tools for Academic Research Library"
+type: software
+version: "0.3.0b2"
+date-released: 2026-08-26
+authors:
+  - family-names: Melzi
+    given-names: M. A.
+    name-suffix: MD
+license: MIT
+repository-code: "https://github.com/mamelzi/starlibpy"
+url: "https://github.com/mamelzi/starlibpy"
+abstract: >-
+  Starlibpy is a modular Python library for study-design specification,
+  data quality, statistical analysis, diagnostics, scientific visualization,
+  and publication-ready reporting in academic, clinical, epidemiological,
+  and biomedical research.
+keywords:
+  - statistics
+  - academic research
+  - biomedical research
+  - clinical research
+  - epidemiology
+  - survival analysis
+  - diagnostic accuracy

starlibpy-0.3.0b2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr. M.A. Melzi, MD
+
+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.

starlibpy-0.3.0b2/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md LICENSE CITATION.cff AUTHORS.md ACKNOWLEDGMENTS.md REFERENCES.bib THIRD_PARTY_LICENSES.md CHANGELOG.md TEST_REPORT.md BUILD_MANIFEST.md VERSION
+recursive-include docs *.md *.py
+recursive-include examples *.py
+recursive-include src/starlibpy py.typed
+
+recursive-include tests *.py

starlibpy-0.3.0b2/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: starlibpy
+Version: 0.3.0b2
+Summary: Statistical Tools for Academic Research Library
+Author: Dr. M.A. Melzi, MD
+Maintainer: Dr. M.A. Melzi, MD
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mamelzi/starlibpy
+Project-URL: Repository, https://github.com/mamelzi/starlibpy
+Project-URL: Issues, https://github.com/mamelzi/starlibpy/issues
+Project-URL: Changelog, https://github.com/mamelzi/starlibpy/blob/main/CHANGELOG.md
+Keywords: statistics,academic research,biomedical research,clinical research,epidemiology,survival analysis,diagnostic accuracy,publication reporting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
+Requires-Dist: scipy>=1.11
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: patsy>=0.5.6
+Provides-Extra: data
+Requires-Dist: scikit-learn>=1.3; extra == "data"
+Requires-Dist: openpyxl>=3.1; extra == "data"
+Requires-Dist: PyYAML>=6.0; extra == "data"
+Requires-Dist: pyarrow>=14; extra == "data"
+Provides-Extra: plotting
+Requires-Dist: matplotlib>=3.8; extra == "plotting"
+Provides-Extra: diagnostic
+Requires-Dist: scikit-learn>=1.3; extra == "diagnostic"
+Provides-Extra: reporting
+Requires-Dist: matplotlib>=3.8; extra == "reporting"
+Requires-Dist: Jinja2>=3.1; extra == "reporting"
+Requires-Dist: openpyxl>=3.1; extra == "reporting"
+Requires-Dist: python-docx>=1.1; extra == "reporting"
+Requires-Dist: Pillow>=10; extra == "reporting"
+Requires-Dist: webcolors>=24; extra == "reporting"
+Provides-Extra: survival
+Requires-Dist: lifelines>=0.29; extra == "survival"
+Provides-Extra: posthoc
+Requires-Dist: scikit-posthocs>=0.9; extra == "posthoc"
+Provides-Extra: full
+Requires-Dist: scikit-learn>=1.3; extra == "full"
+Requires-Dist: matplotlib>=3.8; extra == "full"
+Requires-Dist: Jinja2>=3.1; extra == "full"
+Requires-Dist: openpyxl>=3.1; extra == "full"
+Requires-Dist: python-docx>=1.1; extra == "full"
+Requires-Dist: Pillow>=10; extra == "full"
+Requires-Dist: webcolors>=24; extra == "full"
+Requires-Dist: PyYAML>=6.0; extra == "full"
+Requires-Dist: pyarrow>=14; extra == "full"
+Requires-Dist: lifelines>=0.29; extra == "full"
+Requires-Dist: scikit-posthocs>=0.9; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: hypothesis>=6; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# Starlibpy
+
+**Statistical Tools for Academic Research Library**
+
+**Project author:** Dr. M.A. Melzi, MD  
+**Recommended import:** `import starlibpy as slp`  
+**Release:** `0.3.0b2` — publication-candidate beta
+
+**Repository:** https://github.com/mamelzi/starlibpy
+**Issues:** https://github.com/mamelzi/starlibpy/issues
+
+Starlibpy is a modular Python library for study-design specification, data
+profiling and quality control, statistical analysis, diagnostic checking,
+scientific visualization, and publication-ready reporting. It is intended for
+academic, clinical, epidemiological, and biomedical research.
+
+## Design principles
+
+1. **The design precedes the test.** `StudyDesign` represents the protocol;
+   `AnalysisDesign` represents one statistical question.
+2. **Methods are explainable.** Assumptions, requested method, selected method,
+   fallback, population, exclusions, effect size, confidence interval, and
+   warnings remain attached to the result.
+3. **Analyses return typed objects.** Statistical functions return a
+   `StarResult` subclass rather than printing or plotting implicitly.
+4. **Calculation and presentation are separate.** `render_table()` and
+   `plot_result()` convert results to publication outputs without recalculating
+   statistics.
+5. **Optional functionality stays optional.** Missing plotting, export,
+   survival, or post-hoc dependencies never block the core package import.
+6. **Extensions are first-class.** Third-party modules can register analyses,
+   result types, table renderers, and plot renderers.
+
+## Installation
+
+```bash
+pip install starlibpy
+```
+
+Common optional groups:
+
+```bash
+pip install "starlibpy[data]"
+pip install "starlibpy[plotting]"
+pip install "starlibpy[diagnostic]"
+pip install "starlibpy[reporting]"
+pip install "starlibpy[survival]"
+pip install "starlibpy[full]"
+```
+
+Install this source distribution locally:
+
+```bash
+python -m pip install .
+```
+
+## Quick start
+
+```python
+import pandas as pd
+import starlibpy as slp
+
+cohort = pd.DataFrame(
+    {
+        "patient_id": [1, 2, 3, 4, 5, 6],
+        "group": ["control"] * 3 + ["intervention"] * 3,
+        "age": [51, 63, 58, 49, 54, 61],
+        "response": [0, 0, 1, 1, 1, 1],
+    }
+)
+
+profile = slp.profile_dataset(cohort)
+
+description = slp.describe_continuous(
+    cohort,
+    columns=["age"],
+    random_state=2026,
+)
+
+comparison = slp.compare_continuous(
+    data=cohort,
+    outcome="age",
+    group="group",
+    method="auto",
+    random_state=2026,
+)
+
+publication_table = slp.render_table(comparison, template="journal")
+figure = slp.plot_result(comparison, kind="group_comparison")
+```
+
+The raw analysis table remains available:
+
+```python
+comparison.get_table()
+comparison.list_outputs()
+comparison.metadata
+comparison.warnings
+```
+
+## Modules
+
+| Module | Purpose |
+|---|---|
+| `starlibpy.design` | Protocol, variables, endpoints, analysis structure, provenance |
+| `starlibpy.data` | Profiling, validation, missingness, audit, preparation, imputation |
+| `starlibpy.descriptive` | Continuous, categorical, binary, count, date summaries and Table 1 |
+| `starlibpy.estimation` | Confidence intervals and elementary estimands |
+| `starlibpy.assumptions` | Assumption checks and explainable method recommendation |
+| `starlibpy.comparisons` | One-sample, independent, paired, categorical, rate, and post-hoc tests |
+| `starlibpy.association` | Pearson, Spearman, Kendall, partial and categorical association |
+| `starlibpy.anova` | ANOVA, ANCOVA, repeated-measures, mixed, non-parametric, contrasts |
+| `starlibpy.longitudinal` | Linear mixed models, GEE, covariance comparison, trajectories |
+| `starlibpy.regression` | Linear, robust, logistic, count, ordinal, multinomial models |
+| `starlibpy.diagnostic` | Diagnostic accuracy, ROC, PR, threshold, calibration, validation |
+| `starlibpy.survival` | Time-to-event preparation, KM, log-rank, Cox, RMST, extensions |
+| `starlibpy.agreement` | Kappa, ICC, Bland–Altman, concordance, repeatability |
+| `starlibpy.effect_sizes` | Standardized and design-specific effect sizes |
+| `starlibpy.multiplicity` | Family definition and p-value adjustment |
+| `starlibpy.resampling` | Bootstrap, permutation, exact, cluster and stratified resampling |
+| `starlibpy.equivalence` | Equivalence and non-inferiority analyses |
+| `starlibpy.clinical` | Adverse events and experimental target-lesion RECIST 1.1 |
+| `starlibpy.colors` | Accessible palettes, contrast, conversion, generation, themes |
+| `starlibpy.reporting` | Publication tables, plots, captions, reports, exports |
+| `starlibpy.plugins` | Complementary analysis and result-type registry |
+
+## Documentation map
+
+- `docs/ARCHITECTURE.md` — processing layers and result contracts;
+- `docs/API_OVERVIEW.md` — common user entry points;
+- `docs/API_INVENTORY.md` — generated inventory of the full public API;
+- `docs/DEPENDENCIES.md` — backend, attribution, and citation policy;
+- `docs/EXTENSIONS.md` — complementary-module and plugin contract;
+- `docs/IMPLEMENTATION_STATUS.md` — stable, experimental, and extension areas;
+- `docs/MIGRATION.md` — replacement of the former flat package;
+- `TEST_REPORT.md` — automated validation and coverage summary.
+
+## Method-selection modes
+
+Analysis functions support an explicit method or an automatic workflow. The
+canonical modes are:
+
+- `auto`: select and document a compatible method;
+- `parametric`: request a parametric method;
+- `nonparametric`: request a rank/exact alternative;
+- `robust`: request Welch, robust covariance, bootstrap, or another robust method;
+- `exact`: request an exact method where available.
+
+A method is not selected solely from a normality-test p-value. The analysis
+structure, estimand, independence, group count, sample size, variance behavior,
+residuals, influential observations, and method-specific assumptions are taken
+into account where implemented.
+
+## Tables, figures, and colors
+
+```python
+table = result.table(template="journal", theme="journal_bw")
+figure = result.plot(kind=result.default_plot, theme="default")
+
+slp.list_table_templates()
+slp.list_plot_templates()
+slp.list_themes()
+slp.list_palettes()
+```
+
+Custom palette:
+
+```python
+slp.register_palette(
+    "institution",
+    ["#12355B", "#E4572E", "#17B890"],
+)
+
+slp.validate_palette_contrast(
+    slp.get_palette("institution"),
+    background="#FFFFFF",
+)
+```
+
+## Complementary modules and plugins
+
+An installed package may expose an entry point in the group
+`starlibpy.plugins`. Its registration callable can add analyses and result
+classes:
+
+```python
+from starlibpy.plugins import register_analysis
+
+def register():
+    register_analysis("my_special_analysis", my_special_analysis)
+```
+
+A plugin can also use `register_table_renderer()` and
+`register_plot_renderer()` to make its results publication-ready.
+
+## Clinical and scientific limitations
+
+- Starlibpy assists analysis; it does not replace a statistical analysis plan,
+  domain review, or clinical adjudication.
+- Automatic recommendations remain recommendations and are stored with their
+  rationale and limitations.
+- The RECIST component in this beta is explicitly restricted to target-lesion
+  SLD rules. Full RECIST 1.1 assessment also requires non-target lesion, nodal,
+  new-lesion, confirmation, and clinical rules not completely represented by
+  SLD alone.
+- Fine–Gray regression and Gray's test require a registered competing-risks
+  plugin in this beta. Starlibpy does not silently substitute a different test.
+
+## Scientific and clinical disclaimer
+
+Starlibpy supports academic, methodological, epidemiological, biomedical, and clinical research workflows. Its outputs must be interpreted in light of the study design, data quality, statistical assumptions, uncertainty, and applicable scientific or regulatory guidance. The library does not replace independent statistical review, clinical judgment, regulatory validation, or protocol-specific adjudication.
+
+## Migration from the former flat package
+
+Selected old names remain in `starlibpy.legacy` with a `DeprecationWarning`.
+The new API uses stable snake-case names and typed result objects. See
+`docs/MIGRATION.md`.
+
+## Citation
+
+Use the release metadata in `CITATION.cff`:
+
+> Melzi, M.A. *Starlibpy: Statistical Tools for Academic Research Library*.
+> Version 0.3.0b2.
+
+Also cite the scientific libraries and original methods directly used by your
+analysis. A reusable bibliography is supplied in `REFERENCES.bib`.
+
+## License
+
+MIT License. See `LICENSE` and `THIRD_PARTY_LICENSES.md`.