Skip to content

Commit 355b844

Browse files
committed
Polish README: remove emoji, tighten prose and section titles
Replace blockquote opener with clean prose paragraphs; remove sales-y image caption phrasing; rename "What's in the box" to "API overview" and "Outputs" to "Example outputs"; consolidate duplicate validation section; replace validation section arrow-links with flowing prose.
1 parent b271c7a commit 355b844

1 file changed

Lines changed: 28 additions & 38 deletions

File tree

README.md

Lines changed: 28 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -14,17 +14,21 @@
1414

1515
</div>
1616

17-
> R has `gtsummary`, `tableone`, and `flextable`. Python doesn't — or didn't.
18-
> PySofra turns datasets, fitted models, and summary statistics into
19-
> **publication-ready tables** across HTML · Markdown · LaTeX · DOCX ·
20-
> PPTX · XLSX · PNG from a single immutable object.
17+
PySofra is a statistical reporting framework for Python. It produces the
18+
table types standard in clinical and epidemiological manuscripts —
19+
baseline-characteristics tables (Table 1), regression summaries,
20+
Kaplan–Meier tables — from a single immutable object across seven output
21+
formats: HTML, Markdown, LaTeX, DOCX, PPTX, XLSX, and PNG.
22+
23+
The R ecosystem has `gtsummary`, `tableone`, and `flextable`. Python did
24+
not — until now.
2125

2226
<div align="center">
2327
<img src="https://raw.githubusercontent.com/jturner-uofl/pysofra/main/assets/readme/table_one.png"
2428
alt="Baseline characteristics table by treatment arm — clinical theme, p-values, SMDs, Overall column"
2529
width="820">
2630
<br>
27-
<sub><em>Baseline-characteristics Table 1, by treatment arm. JAMA theme. <strong>One call.</strong></em></sub>
31+
<sub><em>Baseline-characteristics Table 1, stratified by treatment arm. Clinical theme. p-values, standardised mean differences, and an Overall column added as single-line modifiers.</em></sub>
2832
</div>
2933

3034
---
@@ -55,8 +59,9 @@ Nominal 95% CIs from survey-weighted logistic regression attain **94.2% and 93.8
5559
empirical coverage** in a 1,000-replicate Monte Carlo study with known truth.
5660

5761
Every contract runs in CI on every push.
58-
[→ Read the full audit](https://jturner-uofl.github.io/pysofra/notebooks/jss_case_study.html) ·
59-
[→ Reproduce it yourself](AUDITOR.md)
62+
The [full audit notebook](https://jturner-uofl.github.io/pysofra/notebooks/jss_case_study.html)
63+
is pre-executed and readable without installing anything;
64+
see [AUDITOR.md](AUDITOR.md) for the single-command reproduction recipe.
6065

6166
---
6267

@@ -129,17 +134,17 @@ pooled = ps.pool(fits) # list of per-imputation model fits
129134

130135
## Why PySofra
131136

132-
| | R ecosystem | PySofra | Python alternatives |
133-
|---|---|---|---|
134-
| **Table 1 (auto stats)** | `tableone`, `gtsummary` | | `tableone` (partial) |
135-
| **Regression table** | `gtsummary` | ||
136-
| **Survival (KM) summary** | `gtsummary` | ||
137-
| **Survey-weighted Table 1** | `gtsummary` + `survey` | ||
138-
| **MI pooling built-in** | manual `mice` coordination | ||
139-
| **Word + LaTeX + 5 more formats** | separate packages | ||
140-
| **Byte-deterministic output** || ||
141-
| **Safety diagnostics in table** || ||
142-
| **Machine-precision validation** || ||
137+
| Feature | R ecosystem | PySofra | Python alternatives |
138+
|---------|-------------|---------|---------------------|
139+
| Table 1 — baseline characteristics | `tableone`, `gtsummary` | Yes | `tableone` (partial) |
140+
| Regression table | `gtsummary` | Yes ||
141+
| Survival (KM) summary | `gtsummary` | Yes ||
142+
| Survey-weighted Table 1 | `gtsummary` + `survey` | Yes ||
143+
| Multiple-imputation pooling | manual `mice` coordination | Yes ||
144+
| Word + LaTeX + five more formats | separate packages | Yes ||
145+
| Byte-deterministic output || Yes ||
146+
| Safety diagnostics embedded in table || Yes ||
147+
| Machine-precision numerical validation || Yes ||
143148

144149
**One immutable object, seven output formats.** Build a `SofraTable` once; render to
145150
HTML, Markdown, LaTeX, DOCX, PPTX, XLSX, or PNG. Output is byte-identical across
@@ -161,28 +166,28 @@ a console warning that disappears in batch output.
161166

162167
---
163168

164-
## Outputs
169+
## Example outputs
165170

166171
<table>
167172
<tr>
168173
<td width="50%" valign="top" align="center">
169174
<img src="https://raw.githubusercontent.com/jturner-uofl/pysofra/main/assets/readme/regression_forest.png"
170175
alt="Adjusted odds ratios with inline forest plot" width="100%">
171176
<br>
172-
<sub><em>Adjusted ORs + inline forest plot</em><br><code>tbl_regression(fit).with_forest_plot()</code></sub>
177+
<sub><em>Adjusted odds ratios with inline forest plot</em><br><code>tbl_regression(fit).with_forest_plot()</code></sub>
173178
</td>
174179
<td width="50%" valign="top" align="center">
175180
<img src="https://raw.githubusercontent.com/jturner-uofl/pysofra/main/assets/readme/survival_km.png"
176-
alt="Kaplan–Meier survival table with embedded KM curve" width="100%">
181+
alt="Kaplan–Meier survival table with embedded survival curve" width="100%">
177182
<br>
178-
<sub><em>KM table + inline survival curve</em><br><code>tbl_survival(...).with_km_plot()</code></sub>
183+
<sub><em>Kaplan–Meier table with embedded survival curve</em><br><code>tbl_survival(...).with_km_plot()</code></sub>
179184
</td>
180185
</tr>
181186
</table>
182187

183188
---
184189

185-
## What's in the box
190+
## API overview
186191

187192
**Builders**
188193

@@ -275,21 +280,6 @@ Quality bar at this release:
275280

276281
---
277282

278-
## Independently verifying PySofra
279-
280-
Reviewers, sceptics, and downstream users: see [**AUDITOR.md**](AUDITOR.md) for
281-
the single-command recipe that downloads NHANES from the CDC, runs the full
282-
54-step audit notebook, and prints:
283-
284-
```
285-
AUDIT COMPLETE — 52/52 contracts passed | pysofra 0.1.0 | <UTC>
286-
```
287-
288-
The [pre-executed notebook](https://jturner-uofl.github.io/pysofra/notebooks/jss_case_study.html)
289-
is available for read-only review without installing anything.
290-
291-
---
292-
293283
## Citation
294284

295285
If you use PySofra in academic work, cite the software via the

0 commit comments

Comments
 (0)