forestplotx 1.0.1__tar.gz → 1.1.0__tar.gz

forestplotx-1.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: forestplotx
+Version: 1.1.0
+Summary: Publication-ready forest plots for regression model outputs in Python.
+Author-email: Shervin Taheripour <shervintaheripour@fastmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shervin-taheripour/forestplotx
+Project-URL: Repository, https://github.com/shervin-taheripour/forestplotx
+Project-URL: Issues, https://github.com/shervin-taheripour/forestplotx/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# forestplotx
+
+`forestplotx` creates publication-style forest plots that combine a clean text table with a forest panel, with deterministic formatting for common regression outputs.
+
+## Features
+
+- Publication-style table + forest composition
+- Supports `binom`, `gamma`, `linear`, and `ordinal` model outputs
+- One or two outcomes per plot
+- Deterministic internal layout presets for stable output
+- Readable log-axis handling in both `decimal` and `power10` styles
+- Optional footer text for manuscript-style notes
+- Visible column-header and x-axis label overrides
+
+**Note:** For `logit`/`log` links, `exponentiate=None` applies model-based exponentiation with a warning; set `exponentiate=False` if your data is already on effect scale.
+Displayed CI values in the table use bracket notation: `[low,high]`.
+
+## API Reference
+
+### `forest_plot()`
+
+```python
+fig, axes = fpx.forest_plot(
+    df,                              # DataFrame with model output
+    outcomes=None,                   # list[str], max 2; auto-detected if None
+    save=None,                       # File path to save (e.g. "plot.png")
+    model_type="binom",              # "binom" | "gamma" | "linear" | "ordinal"
+    link=None,                       # Override default link function
+    exponentiate=None,               # None=auto by link, True=force, False=disable
+    table_only=False,                # Render table without forest panel
+    legend_labels=None,              # list[str] override for legend entries
+    point_colors=None,               # list[str], up to 2 hex codes for outcome markers
+    column_labels=None,              # dict override for table column labels
+    x_label_override=None,           # Override forest x-axis label
+    footer_text=None,                # Italic footer (wrapped/capped internally)
+    tick_style="decimal",            # "decimal" or "power10"
+    clip_outliers=False,             # Opt-in clipping of extreme CI-driven axis outliers
+    clip_quantiles=(0.02, 0.98),     # Retained for API compatibility
+    base_decimals=2,                 # Decimal places for effect / CI values
+    show=True,                       # Call plt.show(); set False for programmatic use
+    show_general_stats=True,         # Show n / N / Freq columns
+    bold_override=None,              # Manual bold control per predictor/outcome
+)
+```
+
+**Returns:** `(fig, axes)` — matplotlib Figure and axes tuple. When `show=False`, the figure is returned without displaying, allowing further customization before calling `plt.show()` manually.
+When `exponentiate=None`, auto exponentiation for log/logit links emits a warning so users can verify input scale.
+
+### Layout Behavior (v1)
+
+`forest_plot()` uses fixed internal layout presets (including internal font size) for:
+
+1. `show_general_stats=True` + two outcomes
+2. `show_general_stats=True` + one outcome
+3. `show_general_stats=False` + two outcomes
+4. `show_general_stats=False` + one outcome
+
+This is intentional to keep output stable and publication-ready across common use cases.
+`base_decimals` is capped at 3 internally to prevent table collisions in dense layouts.
+For small row counts, figure height uses a tighter internal heuristic to reduce excessive whitespace.
+Long footer text is wrapped and capped to 3 lines with ellipsis for overflow protection.
+Within each layout case, deterministic pressure tiers are applied internally (`standard`, `expanded`, `max`) based on the final rendered string widths.
+Predictor labels are truncated (with warning) when they exceed layout-specific caps:
+1. `show_general_stats=True` + two outcomes: 21 chars
+2. `show_general_stats=True` + one outcome: 24 chars
+3. `show_general_stats=False` + two outcomes: 26 chars
+4. `show_general_stats=False` + one outcome: 25 chars
+When general stats are shown, large `n`/`N` values are compacted (e.g., `9.9k`) to preserve column readability.
+Compaction activates only when counts reach `>= 1,000` and uses a shared unit across both `n` and `N` (`k`, `M`, `B`, `T`) for consistent within-row formatting.
+Very large values beyond display range are capped as `>999T` with a warning.
+Effect / CI display uses the same compact unit family (`k`, `M`, `B`, `T`) once values reach `>= 1,000`, followed by deterministic decimal trimming to keep tables readable.
+Rows are fully grayed only when all displayed outcomes are missing; if at least one outcome is valid, only the missing outcome triplet (`effect`, `95% CI`, `p`) is blanked and gray-marked.
+
+### Title Handling
+
+`forest_plot()` intentionally does not include a `title` parameter in v1.
+This is by design for publication workflows where figure titles/captions are managed in the manuscript rather than embedded inside the plot image.
+If needed for slides or reports, add a title externally on the returned matplotlib figure object.
+
+### Exponentiation Safety
+
+- Use `exponentiate=None` (default) for model/link-based automatic handling.
+- Use `exponentiate=False` if your input is already on effect scale (e.g., OR/Ratio, not log-coefficients).
+- Use `exponentiate=True` only when input is definitely on log scale and needs transformation.
+- Read warnings: they include auto-exponentiation context and column mapping (effect column + `CI_low`/`CI_high` combined into `95% CI`).
+
+### Axis Behavior
+
+- Log-axis limits are data-driven after optional clipping; they are not forced symmetric around the reference value.
+- `clip_outliers=True` uses magnitude-based clipping centered on the median CI bounds, which works much better for small samples with one extreme interval.
+- `tick_style="decimal"` uses readable decimal ticks:
+  - dense near-reference ticks for moderate spans
+  - `1-2-5` progression for wider spans
+  - compact notation for very large tick labels when needed
+- `tick_style="power10"` keeps readable power-of-ten labels for very wide ratio ranges.
+
+### Label Overrides
+
+Use `column_labels` to override visible table headers without changing the underlying model type:
+
+```python
+fig, axes = fpx.forest_plot(
+    df,
+    model_type="gamma",
+    exponentiate=False,
+    column_labels={
+        "effect": "IRR",
+        "ci": "95% CI",
+        "p": "P",
+        "n": "Cases",
+        "N": "Total",
+        "Freq": "Share",
+    },
+    x_label_override="IRR",
+)
+```
+
+Supported `column_labels` keys:
+- `effect`
+- `ci`
+- `p`
+- `n`
+- `N`
+- `Freq`
+
+### `normalize_model_output()`
+
+```python
+clean_df, config = fpx.normalize_model_output(
+    df, model_type="binom", link=None, exponentiate=None
+)
+```
+
+Standardizes columns, applies exponentiation policy, and returns axis metadata.
+`config` includes `exponentiated` and `renamed_columns` for transparency.
+
+## Examples
+
+### Category grouping
+
+```python
+df["category"] = ["Demographics", "Demographics", "Clinical", "Clinical"]
+
+fig, axes = fpx.forest_plot(df, model_type="binom")
+```
+
+### Dual outcomes
+
+```python
+# DataFrame with two outcomes per predictor
+fig, axes = fpx.forest_plot(
+    df_two_outcomes,
+    model_type="binom",
+    outcomes=["Mortality", "Readmission"],
+    legend_labels=["30-day mortality", "90-day readmission"],
+)
+```
+
+### Custom marker colors
+
+```python
+fig, axes = fpx.forest_plot(
+    df_two_outcomes,
+    model_type="binom",
+    outcomes=["Mortality", "Readmission"],
+    point_colors=["#2C5F8A", "#D4763A"],
+)
+```
+
+### Linear model
+
+```python
+fig, axes = fpx.forest_plot(df_linear, model_type="linear")
+```

forestplotx-1.1.0/README.md

@@ -0,0 +1,174 @@
+# forestplotx
+
+`forestplotx` creates publication-style forest plots that combine a clean text table with a forest panel, with deterministic formatting for common regression outputs.
+
+## Features
+
+- Publication-style table + forest composition
+- Supports `binom`, `gamma`, `linear`, and `ordinal` model outputs
+- One or two outcomes per plot
+- Deterministic internal layout presets for stable output
+- Readable log-axis handling in both `decimal` and `power10` styles
+- Optional footer text for manuscript-style notes
+- Visible column-header and x-axis label overrides
+
+**Note:** For `logit`/`log` links, `exponentiate=None` applies model-based exponentiation with a warning; set `exponentiate=False` if your data is already on effect scale.
+Displayed CI values in the table use bracket notation: `[low,high]`.
+
+## API Reference
+
+### `forest_plot()`
+
+```python
+fig, axes = fpx.forest_plot(
+    df,                              # DataFrame with model output
+    outcomes=None,                   # list[str], max 2; auto-detected if None
+    save=None,                       # File path to save (e.g. "plot.png")
+    model_type="binom",              # "binom" | "gamma" | "linear" | "ordinal"
+    link=None,                       # Override default link function
+    exponentiate=None,               # None=auto by link, True=force, False=disable
+    table_only=False,                # Render table without forest panel
+    legend_labels=None,              # list[str] override for legend entries
+    point_colors=None,               # list[str], up to 2 hex codes for outcome markers
+    column_labels=None,              # dict override for table column labels
+    x_label_override=None,           # Override forest x-axis label
+    footer_text=None,                # Italic footer (wrapped/capped internally)
+    tick_style="decimal",            # "decimal" or "power10"
+    clip_outliers=False,             # Opt-in clipping of extreme CI-driven axis outliers
+    clip_quantiles=(0.02, 0.98),     # Retained for API compatibility
+    base_decimals=2,                 # Decimal places for effect / CI values
+    show=True,                       # Call plt.show(); set False for programmatic use
+    show_general_stats=True,         # Show n / N / Freq columns
+    bold_override=None,              # Manual bold control per predictor/outcome
+)
+```
+
+**Returns:** `(fig, axes)` — matplotlib Figure and axes tuple. When `show=False`, the figure is returned without displaying, allowing further customization before calling `plt.show()` manually.
+When `exponentiate=None`, auto exponentiation for log/logit links emits a warning so users can verify input scale.
+
+### Layout Behavior (v1)
+
+`forest_plot()` uses fixed internal layout presets (including internal font size) for:
+
+1. `show_general_stats=True` + two outcomes
+2. `show_general_stats=True` + one outcome
+3. `show_general_stats=False` + two outcomes
+4. `show_general_stats=False` + one outcome
+
+This is intentional to keep output stable and publication-ready across common use cases.
+`base_decimals` is capped at 3 internally to prevent table collisions in dense layouts.
+For small row counts, figure height uses a tighter internal heuristic to reduce excessive whitespace.
+Long footer text is wrapped and capped to 3 lines with ellipsis for overflow protection.
+Within each layout case, deterministic pressure tiers are applied internally (`standard`, `expanded`, `max`) based on the final rendered string widths.
+Predictor labels are truncated (with warning) when they exceed layout-specific caps:
+1. `show_general_stats=True` + two outcomes: 21 chars
+2. `show_general_stats=True` + one outcome: 24 chars
+3. `show_general_stats=False` + two outcomes: 26 chars
+4. `show_general_stats=False` + one outcome: 25 chars
+When general stats are shown, large `n`/`N` values are compacted (e.g., `9.9k`) to preserve column readability.
+Compaction activates only when counts reach `>= 1,000` and uses a shared unit across both `n` and `N` (`k`, `M`, `B`, `T`) for consistent within-row formatting.
+Very large values beyond display range are capped as `>999T` with a warning.
+Effect / CI display uses the same compact unit family (`k`, `M`, `B`, `T`) once values reach `>= 1,000`, followed by deterministic decimal trimming to keep tables readable.
+Rows are fully grayed only when all displayed outcomes are missing; if at least one outcome is valid, only the missing outcome triplet (`effect`, `95% CI`, `p`) is blanked and gray-marked.
+
+### Title Handling
+
+`forest_plot()` intentionally does not include a `title` parameter in v1.
+This is by design for publication workflows where figure titles/captions are managed in the manuscript rather than embedded inside the plot image.
+If needed for slides or reports, add a title externally on the returned matplotlib figure object.
+
+### Exponentiation Safety
+
+- Use `exponentiate=None` (default) for model/link-based automatic handling.
+- Use `exponentiate=False` if your input is already on effect scale (e.g., OR/Ratio, not log-coefficients).
+- Use `exponentiate=True` only when input is definitely on log scale and needs transformation.
+- Read warnings: they include auto-exponentiation context and column mapping (effect column + `CI_low`/`CI_high` combined into `95% CI`).
+
+### Axis Behavior
+
+- Log-axis limits are data-driven after optional clipping; they are not forced symmetric around the reference value.
+- `clip_outliers=True` uses magnitude-based clipping centered on the median CI bounds, which works much better for small samples with one extreme interval.
+- `tick_style="decimal"` uses readable decimal ticks:
+  - dense near-reference ticks for moderate spans
+  - `1-2-5` progression for wider spans
+  - compact notation for very large tick labels when needed
+- `tick_style="power10"` keeps readable power-of-ten labels for very wide ratio ranges.
+
+### Label Overrides
+
+Use `column_labels` to override visible table headers without changing the underlying model type:
+
+```python
+fig, axes = fpx.forest_plot(
+    df,
+    model_type="gamma",
+    exponentiate=False,
+    column_labels={
+        "effect": "IRR",
+        "ci": "95% CI",
+        "p": "P",
+        "n": "Cases",
+        "N": "Total",
+        "Freq": "Share",
+    },
+    x_label_override="IRR",
+)
+```
+
+Supported `column_labels` keys:
+- `effect`
+- `ci`
+- `p`
+- `n`
+- `N`
+- `Freq`
+
+### `normalize_model_output()`
+
+```python
+clean_df, config = fpx.normalize_model_output(
+    df, model_type="binom", link=None, exponentiate=None
+)
+```
+
+Standardizes columns, applies exponentiation policy, and returns axis metadata.
+`config` includes `exponentiated` and `renamed_columns` for transparency.
+
+## Examples
+
+### Category grouping
+
+```python
+df["category"] = ["Demographics", "Demographics", "Clinical", "Clinical"]
+
+fig, axes = fpx.forest_plot(df, model_type="binom")
+```
+
+### Dual outcomes
+
+```python
+# DataFrame with two outcomes per predictor
+fig, axes = fpx.forest_plot(
+    df_two_outcomes,
+    model_type="binom",
+    outcomes=["Mortality", "Readmission"],
+    legend_labels=["30-day mortality", "90-day readmission"],
+)
+```
+
+### Custom marker colors
+
+```python
+fig, axes = fpx.forest_plot(
+    df_two_outcomes,
+    model_type="binom",
+    outcomes=["Mortality", "Readmission"],
+    point_colors=["#2C5F8A", "#D4763A"],
+)
+```
+
+### Linear model
+
+```python
+fig, axes = fpx.forest_plot(df_linear, model_type="linear")
+```

{forestplotx-1.0.1 → forestplotx-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "forestplotx"
-version = "1.0.1"
+version = "1.1.0"
 description = "Publication-ready forest plots for regression model outputs in Python."
 readme = "README.md"
 license = "MIT"

{forestplotx-1.0.1 → forestplotx-1.1.0}/src/forestplotx/__init__.py

@@ -1,7 +1,7 @@
 from .plot import forest_plot
 from ._normalize import _normalize_model_output as normalize_model_output
 
-__version__ = "1.0.1"
+__version__ = "1.1.0"
 
 __all__ = [
     "forest_plot",

{forestplotx-1.0.1 → forestplotx-1.1.0}/src/forestplotx/_axes_config.py

@@ -119,18 +119,6 @@ def configure_forest_axis(
         if not len(finite_lo) or not len(finite_hi):
             return ax
 
-        if clip_outliers:
-            q_low, q_high = clip_quantiles
-            q_low = float(q_low)
-            q_high = float(q_high)
-            if not (0.0 <= q_low < q_high <= 1.0):
-                raise ValueError("clip_quantiles must satisfy 0 <= low < high <= 1.")
-            data_min = float(np.quantile(finite_lo, q_low))
-            data_max = float(np.quantile(finite_hi, q_high))
-        else:
-            data_min = float(np.min(finite_lo))
-            data_max = float(np.max(finite_hi))
-
         ax.set_xscale("log" if use_log else "linear")
 
         if use_log:
@@ -154,12 +142,11 @@ def configure_forest_axis(
                     UserWarning,
                     stacklevel=2,
                 )
+            positive_lo = finite_lo[finite_lo > 0]
+            positive_hi = finite_hi[finite_hi > 0]
+            positive_eff = finite_eff[finite_eff > 0]
             positive_values = np.concatenate(
-                [
-                    finite_lo[finite_lo > 0],
-                    finite_hi[finite_hi > 0],
-                    finite_eff[finite_eff > 0],
-                ]
+                [positive_lo, positive_hi, positive_eff]
             )
             positive_candidates = [*positive_values.tolist(), ref_val]
             if not positive_candidates:
@@ -167,27 +154,113 @@ def configure_forest_axis(
                     "Log-scaled forest axis requires positive effect/CI values."
                 )
 
-            pmin = min(positive_candidates)
-            pmax = max(positive_candidates)
+            if clip_outliers and len(positive_values):
+                clip_factor = 10.0
+
+                if len(positive_lo):
+                    lo_baseline = float(np.median(positive_lo))
+                    lo_threshold = lo_baseline / clip_factor if lo_baseline > 0 else 0.0
+                    lo_inliers = positive_lo[positive_lo >= lo_threshold]
+                    clipped_pmin = float(np.min(lo_inliers)) if len(lo_inliers) else float(np.min(positive_lo))
+                else:
+                    clipped_pmin = float(np.min(positive_values))
+
+                if len(positive_hi):
+                    hi_baseline = float(np.median(positive_hi))
+                    hi_threshold = hi_baseline * clip_factor
+                    hi_inliers = positive_hi[positive_hi <= hi_threshold]
+                    clipped_pmax = float(np.max(hi_inliers)) if len(hi_inliers) else float(np.max(positive_hi))
+                else:
+                    clipped_pmax = float(np.max(positive_values))
+
+                pmin = min(clipped_pmin, ref_val)
+                pmax = max(clipped_pmax, ref_val)
+            else:
+                pmin = min(positive_candidates)
+                pmax = max(positive_candidates)
             target_ticks = max(int(num_ticks), 3)
-            if target_ticks % 2 == 0:
-                target_ticks -= 1
-            n_side_target = max((target_ticks - 1) // 2, 1)
-
-            span_decades = max(abs(math.log10(pmin / ref_val)), abs(math.log10(pmax / ref_val)))
-            axis_span_decades = span_decades * 1.15
-            # Keep very tight ranges readable around the reference line.
-            axis_span_decades = max(axis_span_decades, 0.01)
-            raw_step = axis_span_decades / n_side_target
-            step_decades = _nice_log_step(raw_step)
-            n_side = max(1, int(axis_span_decades / step_decades))
-            exponents = np.arange(-n_side, n_side + 1, dtype=float) * step_decades
-            ticks = ref_val * np.power(10.0, exponents)
-            axis_ratio = 10 ** axis_span_decades
-            xmin = ref_val / axis_ratio
-            xmax = ref_val * axis_ratio
+            log_min = math.log10(pmin)
+            log_max = math.log10(pmax)
+            span_decades = max(log_max - log_min, 0.0)
+            pad_decades = max(0.08, min(0.25, span_decades * 0.08))
+            axis_log_min = log_min - pad_decades
+            axis_log_max = log_max + pad_decades
+            axis_span_decades = axis_log_max - axis_log_min
+
+            raw_step = axis_span_decades / max(target_ticks - 1, 1)
+            if span_decades > 3:
+                step_decades = max(1.0, _nice_log_step(raw_step))
+            else:
+                step_decades = _nice_log_step(raw_step)
+
+            tick_start = math.ceil(axis_log_min / step_decades) * step_decades
+            tick_end = math.floor(axis_log_max / step_decades) * step_decades
+            if tick_end < tick_start:
+                tick_logs = np.array([axis_log_min, 0.0, axis_log_max], dtype=float)
+            else:
+                tick_logs = np.arange(
+                    tick_start,
+                    tick_end + 0.5 * step_decades,
+                    step_decades,
+                )
+                if not np.any(np.isclose(tick_logs, 0.0, atol=1e-9)):
+                    tick_logs = np.sort(np.append(tick_logs, 0.0))
+
+            xmin = 10 ** axis_log_min
+            xmax = 10 ** axis_log_max
             ax.set_xlim(xmin, xmax)
-            ticks_in = ticks[(ticks >= xmin) & (ticks <= xmax)]
+            ticks_in = np.power(10.0, tick_logs)
+            ticks_in = ticks_in[(ticks_in >= xmin) & (ticks_in <= xmax)]
+            ticks_in = np.unique(np.asarray(ticks_in, dtype=float))
+
+            tick_data_min = max(pmin, np.nextafter(0.0, 1.0))
+            tick_data_max = pmax
+            moderate_decimal_span = (
+                tick_style == "decimal"
+                and pmin >= 0.2
+                and pmax <= 10.0
+                and span_decades <= 1.4
+            )
+            if moderate_decimal_span:
+                readable_ticks = np.array(
+                    [0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0, 1.2, 1.5, 2.0, 3.0, 4.0, 5.0, 7.0, 10.0],
+                    dtype=float,
+                )
+                ticks_in = readable_ticks[(readable_ticks >= tick_data_min) & (readable_ticks <= tick_data_max)]
+                if len(ticks_in) > 8:
+                    keep = []
+                    for idx, tick in enumerate(ticks_in):
+                        if idx % 2 == 0 or math.isclose(tick, 1.0, abs_tol=1e-9):
+                            keep.append(tick)
+                    ticks_in = np.array(sorted(set(keep)), dtype=float)
+            elif tick_style == "decimal":
+                decade_min = int(math.floor(axis_log_min))
+                decade_max = int(math.ceil(axis_log_max))
+                readable_ticks = []
+                for decade in range(decade_min, decade_max + 1):
+                    base = 10.0 ** decade
+                    for mult in (1.0, 2.0, 5.0):
+                        tick = mult * base
+                        if tick_data_min <= tick <= tick_data_max:
+                            readable_ticks.append(tick)
+                if readable_ticks:
+                    ticks_in = np.array(sorted(set(readable_ticks)), dtype=float)
+                    if not np.any(np.isclose(ticks_in, ref_val, atol=1e-9)) and tick_data_min <= ref_val <= tick_data_max:
+                        ticks_in = np.array(sorted(np.append(ticks_in, ref_val)), dtype=float)
+                    if len(ticks_in) > 9:
+                        min_log_gap = axis_span_decades / 7.0
+                        keep = [float(ticks_in[0])]
+                        for tick in ticks_in[1:-1]:
+                            if math.isclose(tick, ref_val, abs_tol=1e-9):
+                                keep.append(float(tick))
+                                continue
+                            if math.log10(float(tick)) - math.log10(float(keep[-1])) >= min_log_gap:
+                                keep.append(float(tick))
+                        keep.append(float(ticks_in[-1]))
+                        if tick_data_min <= ref_val <= tick_data_max and not any(math.isclose(t, ref_val, abs_tol=1e-9) for t in keep):
+                            keep.append(ref_val)
+                        ticks_in = np.array(sorted(set(keep)), dtype=float)
+
             if len(ticks_in) < 3:
                 ticks_in = np.array([xmin, ref_val, xmax], dtype=float)
             ax.xaxis.set_major_locator(FixedLocator(ticks_in))
@@ -195,25 +268,48 @@ def configure_forest_axis(
             if tick_style == "power10":
 
                 def _power10_formatter(x: float, _pos: int) -> str:
-                    exp = math.log10(x / ref_val)
-                    rounded = round(exp, 2)
-                    if math.isclose(rounded, 0.0, abs_tol=1e-9):
-                        rounded = 0.0
-                    exp_txt = f"{rounded:.2f}".rstrip("0").rstrip(".")
-                    if math.isclose(ref_val, 1.0):
-                        return rf"$10^{{{exp_txt}}}$"
-                    return rf"${_format_decimal(ref_val)}\times10^{{{exp_txt}}}$"
+                    exp = round(math.log10(x), 6)
+                    if math.isclose(exp, round(exp), abs_tol=1e-9):
+                        exp_txt = str(int(round(exp)))
+                    else:
+                        exp_txt = f"{exp:.2f}".rstrip("0").rstrip(".")
+                    return rf"$10^{{{exp_txt}}}$"
 
                 ax.xaxis.set_major_formatter(FuncFormatter(_power10_formatter))
             else:
-                decimals = max(2, _decimals_from_ticks(ticks_in))
-                ax.xaxis.set_major_formatter(
-                    FuncFormatter(lambda x, _pos, d=decimals: f"{x:.{d}f}")
-                )
+                decimals = _decimals_from_ticks(ticks_in)
+
+                def _decimal_log_formatter(x: float, _pos: int, d: int = decimals) -> str:
+                    abs_x = abs(float(x))
+                    if abs_x >= 1e12:
+                        return _format_decimal(x / 1e12, precision=1).rstrip("0").rstrip(".") + "T"
+                    if abs_x >= 1e9:
+                        return _format_decimal(x / 1e9, precision=1).rstrip("0").rstrip(".") + "B"
+                    if abs_x >= 1e6:
+                        return _format_decimal(x / 1e6, precision=1).rstrip("0").rstrip(".") + "M"
+                    if abs_x >= 1e3:
+                        return _format_decimal(x / 1e3, precision=1).rstrip("0").rstrip(".") + "k"
+                    if abs_x >= 10:
+                        return _format_decimal(x, precision=0)
+                    return _format_decimal(x, precision=max(d + 1, 1))
+
+                ax.xaxis.set_major_formatter(FuncFormatter(_decimal_log_formatter))
 
             ax.xaxis.set_minor_locator(NullLocator())
             ax.xaxis.set_minor_formatter(NullFormatter())
         else:
+            if clip_outliers:
+                q_low, q_high = clip_quantiles
+                q_low = float(q_low)
+                q_high = float(q_high)
+                if not (0.0 <= q_low < q_high <= 1.0):
+                    raise ValueError("clip_quantiles must satisfy 0 <= low < high <= 1.")
+                data_min = float(np.quantile(finite_lo, q_low))
+                data_max = float(np.quantile(finite_hi, q_high))
+            else:
+                data_min = float(np.min(finite_lo))
+                data_max = float(np.max(finite_hi))
+
             if clip_outliers:
                 q_high = float(clip_quantiles[1])
                 # Linear outliers are visually dominant; keep clipping robust by capping