pysofra 0.1.0a1__py3-none-any.whl

pysofra-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: pysofra
+Version: 0.1.0a1
+Summary: Statistical reporting and table preparation framework for Python — the missing reporting layer.
+Project-URL: Homepage, https://github.com/jturner-uofl/pysofra
+Project-URL: Documentation, https://github.com/jturner-uofl/pysofra
+Project-URL: Repository, https://github.com/jturner-uofl/pysofra
+Project-URL: Issues, https://github.com/jturner-uofl/pysofra/issues
+Author-email: Jason Turner <jason.s.turner@gmail.com>
+License: GPL-3.0-or-later
+License-File: LICENSE
+License-File: NOTICE
+Keywords: biostatistics,clinical-trials,epidemiology,flextable,gtsummary,publication,reporting,statistics,tableone,tables
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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.
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas<3,>=2.0
+Requires-Dist: python-docx>=1.1
+Requires-Dist: scipy>=1.11
+Requires-Dist: statsmodels>=0.14
+Provides-Extra: all
+Requires-Dist: lifelines<0.31,>=0.27; extra == 'all'
+Requires-Dist: matplotlib>=3.8; extra == 'all'
+Requires-Dist: polars>=0.20; extra == 'all'
+Requires-Dist: pyarrow>=15; extra == 'all'
+Requires-Dist: python-pptx>=1.0; extra == 'all'
+Requires-Dist: scikit-learn>=1.3; extra == 'all'
+Requires-Dist: xlsxwriter>=3.2; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.2; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == 'plot'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == 'polars'
+Requires-Dist: pyarrow>=15; extra == 'polars'
+Provides-Extra: pptx
+Requires-Dist: python-pptx>=1.0; extra == 'pptx'
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn>=1.3; extra == 'sklearn'
+Provides-Extra: survival
+Requires-Dist: lifelines<0.31,>=0.27; extra == 'survival'
+Requires-Dist: matplotlib>=3.8; extra == 'survival'
+Provides-Extra: xlsx
+Requires-Dist: xlsxwriter>=3.2; extra == 'xlsx'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# PySofra
+
+### The missing statistical reporting layer for Python
+
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/jturner-uofl/pysofra)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
+[![License: GPL-3.0+](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE)
+[![Style: ruff](https://img.shields.io/badge/style-ruff-purple.svg)](https://github.com/astral-sh/ruff)
+[![Types: mypy strict](https://img.shields.io/badge/types-mypy%20strict-blue.svg)](http://mypy-lang.org/)
+[![Tests: 886](https://img.shields.io/badge/tests-886%20passing-brightgreen.svg)](#status)
+
+</div>
+
+> PySofra turns datasets, fitted models, and summary statistics into
+> **publication-ready tables** — across HTML · Markdown · LaTeX · DOCX ·
+> PPTX · XLSX · PNG — from a single immutable `SofraTable` object. It
+> brings the practical workflows of R's `tableone`, `gtsummary`, and
+> `flextable` into a single coherent Pythonic API.
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/jturner-uofl/pysofra/main/assets/readme/table_one.png" alt="Baseline characteristics table by treatment arm — JAMA theme, with p-values, standardized mean differences, and Overall column" width="820">
+  <br>
+  <sub><em>Baseline characteristics, by treatment arm. <strong>One line of code.</strong></em></sub>
+</div>
+
+<table>
+<tr>
+<td width="50%" valign="top" align="center">
+  <img src="https://raw.githubusercontent.com/jturner-uofl/pysofra/main/assets/readme/regression_forest.png" alt="Adjusted odds ratios with inline forest plot" width="100%">
+  <br>
+  <sub><em>Adjusted ORs + inline forest plot</em><br><code>tbl_regression(fit).with_forest_plot()</code></sub>
+</td>
+<td width="50%" valign="top" align="center">
+  <img src="https://raw.githubusercontent.com/jturner-uofl/pysofra/main/assets/readme/survival_km.png" alt="Kaplan-Meier survival table with embedded KM curve" width="100%">
+  <br>
+  <sub><em>KM table + inline survival curve</em><br><code>tbl_survival(...).with_km_plot()</code></sub>
+</td>
+</tr>
+</table>
+
+### Why PySofra
+
+- **One immutable object, seven output formats** — build a `SofraTable` once, render to HTML / Markdown / LaTeX / DOCX / PPTX / XLSX / PNG, all byte-deterministic across processes
+- **Auto-dispatched statistical tests** — Welch, Wilcoxon, ANOVA, Kruskal–Wallis, Fisher, χ², Rao–Scott, design-adjusted *t* — picked by variable kind, overridable per-row
+- **Inline forest plots and KM curves** — embed matplotlib figures directly into the table; the same `SofraTable` renders them across every backend
+- **Statistically correct** — every numeric output validated against `scipy` / `statsmodels` / `lifelines` at machine precision (and cross-checked against R's `gtsummary` for the JSS paper)
+- **Method-chainable and immutable** — every modifier returns a new table; no in-place mutation, no global state, fully reproducible
+
+<div align="center">
+
+**[Showcase notebook](examples/pysofra_showcase.ipynb)** · [rendered HTML](examples/pysofra_showcase.html) — *47 cells, every section a side-by-side numeric proof. Start here if you have 60 seconds.*
+
+**[End-to-end tutorial](examples/pysofra_tutorial.ipynb)** · [rendered HTML](examples/pysofra_tutorial.html) — *126 cells walking every public feature on a synthetic two-arm trial.*
+
+</div>
+
+---
+
+## Quick start
+
+```python
+import numpy as np
+import pandas as pd
+import pysofra as ps
+
+# Toy two-arm trial; replace with your own DataFrame in real use.
+rng = np.random.default_rng(0)
+df = pd.DataFrame({
+    "arm":   rng.choice(["Placebo", "Treatment"], 200),
+    "age":   rng.normal(60, 10, 200).round(),
+    "bmi":   rng.normal(28, 5, 200).round(1),
+    "event": rng.binomial(1, 0.3, 200),
+})
+
+# Table 1 — baseline characteristics by treatment arm
+tbl = (
+    ps.tbl_one(df, by="arm")
+      .add_p()
+      .add_smd()
+      .add_overall()
+      .theme("clinical")
+)
+
+tbl                          # renders in Jupyter / Colab / VS Code
+tbl.to_docx("table1.docx")   # publication-quality Word
+tbl.to_html()                # standalone HTML fragment
+tbl.to_markdown()            # GitHub-flavored Markdown
+```
+
+The same workflow handles regression tables:
+
+```python
+import statsmodels.api as sm
+
+X = sm.add_constant(df[["age", "bmi"]])
+fit = sm.Logit(df["event"], X).fit(disp=False)
+
+(
+    ps.tbl_regression(fit, exponentiate=True)
+      .bold_p()
+      .theme("jama")
+      .to_docx("table2.docx")
+)
+```
+
+The full worked example from the JSS paper — baseline table by
+treatment arm, regression table with forest plot, and Kaplan-Meier
+survival summary — is in
+[`paper/replication/example_trial.py`](paper/replication/example_trial.py).
+
+---
+
+## What's in the box
+
+| Feature              | Function / object         | Status |
+|----------------------|---------------------------|--------|
+| Baseline Table 1     | `ps.tbl_one`              | MVP    |
+| Descriptive summary  | `ps.tbl_summary`          | MVP    |
+| Regression results   | `ps.tbl_regression`       | MVP    |
+| Side-by-side merge   | `ps.tbl_merge`            | MVP    |
+| Vertical stack       | `ps.tbl_stack`            | MVP    |
+| HTML / Markdown      | `.to_html` / `.to_markdown` | MVP  |
+| DOCX export          | `.to_docx`                | MVP    |
+| LaTeX export         | `.to_latex`               | MVP    |
+| PPTX export          | `.to_pptx`                | MVP (extras) |
+| Excel export         | `.to_xlsx`                | MVP    |
+| Inline forest plots  | `tbl_regression(...).with_forest_plot()` | MVP |
+| Inline KM curves     | `tbl_survival(...).with_km_plot()` | MVP |
+| Cross-backend plot embedding | DOCX/PPTX/LaTeX include the plot too | MVP |
+| Rao–Scott chi-square | weighted Table 1 auto-route | MVP |
+| `SurveyDesign` (strata + cluster + FPC) | Taylor-linearised variance | MVP |
+| Themes               | `clinical`, `jama`, `nejm`, `compact`, `minimal` | MVP |
+| Auto test selection  | t-test / ANOVA / Wilcoxon / Kruskal / χ² / Fisher | MVP |
+| Per-variable test overrides | `tests={'age': 'wilcoxon', ...}` | MVP |
+| Multiplicity adjustment | `.add_q()` — BH, BY, Bonferroni, Holm, Hommel, Šidák | MVP |
+| Multi-model regression | `tbl_regression([m1, m2], model_labels=[...])` | MVP |
+| lifelines (Cox / AFT) | `tbl_regression(cph)` | MVP |
+| sklearn (linear models) | `tbl_regression(clf)` — point estimates only | MVP |
+| Kaplan–Meier summary | `tbl_survival(df, time=, event=, by=, times=[...])` | MVP |
+| Survey-weighted Table 1 | `tbl_one(..., weights='w')` | MVP |
+| polars input | `tbl_one(pl.DataFrame(...))` | MVP |
+| Conditional formatting | `.bold_if`, `.highlight_if`, `.style_if` | MVP |
+| Sticky-header notebook tables | `.to_html(sticky_header=True)` | MVP |
+| Standardised mean differences | continuous + categorical (Yang–Dalton) | MVP |
+| Notebook rendering   | `_repr_html_` / `_repr_markdown_` / `_repr_latex_` | MVP    |
+
+---
+
+## Design principles
+
+* **Backend-agnostic tables.** A `SofraTable` is the single source of truth;
+  every renderer (HTML, Markdown, DOCX, …) reads the same object.
+* **Immutable method chaining.** Every modifier returns a new `SofraTable`.
+  No surprises, no global state.
+* **Strong defaults, explicit overrides.** Sensible journal-style output
+  out of the box; per-variable type, label, and test overrides when you
+  need them.
+* **Deterministic.** The same input always produces the same output —
+  critical for reproducible research.
+* **No magic.** No nonstandard evaluation, no metaprogramming, no
+  network calls, no telemetry.
+
+---
+
+## Installation
+
+```bash
+pip install pysofra
+```
+
+PySofra requires Python ≥ 3.11. The core install only pulls `numpy`,
+`pandas`, `scipy`, `statsmodels`, and `python-docx`. Domain extras unlock
+the features that depend on heavier optional libraries:
+
+```bash
+pip install "pysofra[survival]"   # tbl_survival + KM curves (lifelines, matplotlib)
+pip install "pysofra[plot]"       # forest plots, table-as-image (matplotlib)
+pip install "pysofra[pptx]"       # PowerPoint export (python-pptx)
+pip install "pysofra[xlsx]"       # Excel export (xlsxwriter)
+pip install "pysofra[polars]"     # accept polars DataFrames as input
+pip install "pysofra[sklearn]"    # tbl_regression on scikit-learn models
+pip install "pysofra[all]"        # everything above
+pip install "pysofra[dev]"        # testing + linting (pytest, ruff, mypy, hypothesis)
+```
+
+---
+
+## Status
+
+PySofra is in **alpha** (`0.1.0a1`). The public API surface is pinned
+by an explicit
+[API-stability test](tests/test_joss_api_stability.py) so that any
+unintended rename, removal, or signature change surfaces as a failed
+test. Quality bar at this release:
+
+* **More than 800 tests passing**, **100% line coverage**, mypy strict, ruff clean.
+* Every numeric output is validated against `scipy`, `lifelines`,
+  `statsmodels`, or a hand-computed textbook formula
+  ([test_joss_statistical_correctness.py](tests/test_joss_statistical_correctness.py)).
+* Universal invariants enforced via Hypothesis on 720 randomized
+  examples per CI run
+  ([test_joss_property_invariants.py](tests/test_joss_property_invariants.py)).
+* Renderer output is byte-deterministic — identical input always
+  produces identical HTML/Markdown/LaTeX, required for reproducible
+  publication artifacts
+  ([test_joss_renderer_consistency.py](tests/test_joss_renderer_consistency.py)).
+
+Bug reports and use-case feedback are very welcome.
+
+A **Journal of Statistical Software** paper ([`paper/paper.tex`](paper/paper.tex),
+bibliography in [`paper/paper.bib`](paper/paper.bib)) is in
+preparation. The [`paper/replication/`](paper/replication/) directory
+regenerates every numeric output and figure shown in the paper and
+includes an R cross-check script (`example_trial.R`) using
+`gtsummary` for digit-level verification. The
+[`paper/figures/`](paper/figures/) directory holds the rendered PDF
+and PNG embedded in the manuscript via `\includegraphics{}`.
+
+## Contributing
+
+Bug reports, feature requests, and pull requests are all very welcome.
+Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow, the
+quality gates, and the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+GPL-3.0-or-later. See [`LICENSE`](LICENSE).
+
+## Citation
+
+If you use PySofra in academic work, please cite the project — see
+[`CITATION.cff`](CITATION.cff).

pysofra-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,50 @@
+pysofra/__init__.py,sha256=HTn-jcTecuoxnsB6JC6DXKYz3en8rhTnn72eupwieb8,2045
+pysofra/core/__init__.py,sha256=ac1VAhSD79VagXG9r8PwdKzrLklnB__HAigkHD3ofk0,295
+pysofra/core/compose.py,sha256=7FWe1rOaX05XknJdhY37Gz1nFWzcdiYJ49sq4AS-MDo,6151
+pysofra/core/format.py,sha256=kVamfHh9n06iTx_Cg-kzI4M2ILYNAIRMaoiGlSh5b48,5112
+pysofra/core/frames.py,sha256=YjzrjmKkwydz5V0nud48kYVVcvOiVZ0xSVQIImaB5G8,2581
+pysofra/core/schema.py,sha256=OzAGpG1tHGJBD9nHP-RyYea0Qg1BwiEK_lYjlSouyOY,3501
+pysofra/core/table.py,sha256=tiQVqdPVYcvVkfCmve0QW2xixTjR9DRRF26DHK281_g,37304
+pysofra/io/__init__.py,sha256=wLrJPCvgALItN7--2eR0dXc0hbZhFnSzqqwVkgtU7yI,71
+pysofra/models/__init__.py,sha256=v9bCNwAcXrAwKeEw8DX3taWh3i412Ef4vHePr6_TVOI,156
+pysofra/models/extract.py,sha256=IOgZw-CYGo_bE9rQfNpoQavQZ2PWbV8HyIMFZYhD27Y,9671
+pysofra/models/pool.py,sha256=gYmOJSFXnyOx05_IiiSyJCG2W3fqLJM62Dv7TKkFMBE,4720
+pysofra/models/regression.py,sha256=rpTY7qr6TNIXqfDScvR5J2q_PaIJSk6YQl89dToZ6QY,19859
+pysofra/models/survival.py,sha256=EMIxUWgLLGYtCPYbGX_M32zr_bMwdqU7eIp94BUcYAo,14374
+pysofra/models/uvregression.py,sha256=KzCAFfOJkaQMYCzjyBd5KzlI1TXNniCWrNY1HooJfDo,16148
+pysofra/notebook/__init__.py,sha256=VvfVu08lD0iiwmrUAvUmm1wlaQ-Gaq112MJdogMzA0M,199
+pysofra/plot/__init__.py,sha256=rApXS8uvUL5eEJvNQdtzlVmw6S4OtRVBl00J6EVxDpI,681
+pysofra/plot/_backend.py,sha256=RL_rNqC3OWdfI-dnAlI3pAz51gI-XcrJfmDa_1z4Pgc,1276
+pysofra/plot/forest.py,sha256=zwYUF7zG8Ab-7xmKep1ju088voCNrQ6LBabMjE1vXdo,4944
+pysofra/plot/inline.py,sha256=L6-yu6Y09zwsxtP8EZoKElPy4J9zChXIqbCwbKhdcAk,6090
+pysofra/plot/km.py,sha256=LQAYhvChXYWCDQFoCLCOrBtOexUPbrcUdYthDxX9Tdo,8493
+pysofra/render/__init__.py,sha256=lbW0WougRXnglAdca2LFXtRXatJDHtQpHsDGa-yypKQ,687
+pysofra/render/_zip_determinism.py,sha256=ambrEGTzerGc0Udg3xXzMhBUiCYUp899QjwjAl_-_hg,2255
+pysofra/render/base.py,sha256=eeleWMTlhWyv5C6eZvPGxQHl8BH3z1A8mWG6N7YVudY,533
+pysofra/render/docx.py,sha256=VeYUI_5rDKKk8WkeAdvOwGpQSI8uYoV_f8i1Cv_mB_E,10713
+pysofra/render/html.py,sha256=va7e6xYKR1K1ihZlQBMnhSMOGMzG98yZqYUMbLyrln8,15464
+pysofra/render/image.py,sha256=cp6oYdPk_hGPaW5dfcd1uOiN0W2s1CLXAd7C7KfMQnE,4209
+pysofra/render/latex.py,sha256=4LonwkmwMAvJwKcbbFgD6eWoWUR07vpVpKyX3OZeqrs,8279
+pysofra/render/markdown.py,sha256=IzwwLV0lfCtZ5knuBKDvUD59f12WRQoDNLVJpBOIcsI,4158
+pysofra/render/pptx.py,sha256=cKi8VLBZ2X0G_f_XSwW1aMD8dWiwCTGYBL9WA_bRwk4,13860
+pysofra/render/xlsx.py,sha256=owTuhcwCBusJDHPgKpRp1M8YFrm4-N6CEbYrOd1zpGg,9019
+pysofra/summary/__init__.py,sha256=CYpMewe1uyZKl_1Gol8qbgEqsSR4o8nkQZADnarSCks,135
+pysofra/summary/calibrate.py,sha256=10ZL5tk0NtR-i6E_QN1TFyYtMJ9mROBZ0-1Uyybs8z4,7251
+pysofra/summary/design.py,sha256=nmNnYHVrw6HiNkN6ClAOC5ETjBc6OldDNSr1Lez7snQ,9310
+pysofra/summary/effect_size.py,sha256=mIoQzYRYeGtd4Kntsn4YNoy7xfV3A2UONRKmCZ4__ZU,7020
+pysofra/summary/extras.py,sha256=8CjPsbMVMstoon8-4ZLztwepdw-EE7XHnd5NZfJZtxU,27764
+pysofra/summary/smd.py,sha256=KOb4dmZcjGSrwv3TfAonm_a8ndcfIXmzyScBvJmlQw4,5307
+pysofra/summary/stats.py,sha256=F6C9jtSwlpNa7M_jsrx7xrQ5Qp7GMAHSE-lcHw3Uirg,4247
+pysofra/summary/tbl_cross.py,sha256=N7_G3a9-CGdOlnmLqXSKnNdl6BEKn1dT0GHdndRgFTA,12773
+pysofra/summary/tbl_one.py,sha256=ewhSsfDKiZdxW0YtV2axi8vw6nq_O9erU_1cdxoffOw,47288
+pysofra/summary/tbl_summary.py,sha256=1M8l4v5vhc7wE6PmQSPdFvaKsIDB-cWHTq1OVo9XOmM,1597
+pysofra/summary/tests.py,sha256=Of_hGxfaEFZClRYvmB2pX35OfuDOBfCxkiaCG1uR0j0,12225
+pysofra/summary/typing.py,sha256=AkdGEkm0U9BnLrebwsKEEKFv0yN1MTNYDWPpfJiSs_M,5059
+pysofra/summary/weights.py,sha256=x2VsEQsWIrmEP8aodtOhm9rH5MUuAnWTEtgdDgfNo1M,5069
+pysofra/themes/__init__.py,sha256=Uf2h6mM1fduI6i3udKBPJ9TwJqtBM5F5OHPH-DBGwRE,189
+pysofra/themes/registry.py,sha256=SXPt7Obdp07aXYmqWzKgtTmVU3UpHyrvdZro-YI_dIs,9010
+pysofra-0.1.0a1.dist-info/METADATA,sha256=dMGekVR9Xrw6DHYTeKvIGRhtOOVtPKncSqIdeK5Dmw8,13359
+pysofra-0.1.0a1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pysofra-0.1.0a1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+pysofra-0.1.0a1.dist-info/licenses/NOTICE,sha256=RfuuxugSgFLA2YBdLSF6FU_yn4Rc6Xjlmya3iE7soQE,754
+pysofra-0.1.0a1.dist-info/RECORD,,

pysofra-0.1.0a1.dist-info/WHEEL

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