do-attribution 0.0.2__tar.gz → 0.0.3__tar.gz

{do_attribution-0.0.2/do_attribution.egg-info → do_attribution-0.0.3}/PKG-INFO

@@ -1,22 +1,21 @@
 Metadata-Version: 2.4
 Name: do-attribution
-Version: 0.0.2
+Version: 0.0.3
 Summary: Unified multi-touch attribution library (Markov chain + Shapley value).
 Author-email: Aaron Goodin <goodinaaron@causalscience.com>
 License-Expression: MIT
 Keywords: attribution,marketing,markov,shapley,multi-touch,analytics,incrementality
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Science/Research
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy>=1.21.0
-Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=2.0.2
+Requires-Dist: pandas>=3.1.1
 Provides-Extra: viz
 Requires-Dist: matplotlib>=3.3.0; extra == "viz"
 Requires-Dist: networkx>=2.5; extra == "viz"
@@ -41,7 +40,7 @@ closed-form Markov, exact Shapley, temporal attribution, and explicit
 calibration from external lift-test evidence.**
 
 ![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
-![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
+![Python: 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
 
 `do-attribution` has two explicit layers:
 
@@ -59,7 +58,7 @@ allocation models:
 - an **absorbing-Markov-chain removal-effect** model
   (`MarkovAttribution`, orders 1+, four removal strategies), and
 - a **cooperative-game Shapley-value** model (`ShapleyAttribution`, exact
-  factorial weights over the observed coalition lattice).
+  Shapley values of a coalition game built from the observed channel sets).
 
 The calibration layer applies caller-supplied lift-test evidence after a
 static or temporal attribution fit. Direct adjustments to tested entities,
@@ -94,11 +93,22 @@ chronological epochs.
   `"fail_refit"` (signed effects), `"detour"` (signed effects), or
   `"redirect_to_null"` — four operational meanings of "remove this channel",
   selected explicitly instead of implied.
-- **Exact Shapley values.** Per-channel values use the exact factorial weight
-  `w(s, n) = s!·(n−s−1)!/n!`. Raw signed values and the coalition value
-  function are always returned; normalized shares are returned when the raw
-  values admit a valid share vector, and reported as unavailable when they
-  do not.
+- **Exact Shapley values.** The default cumulative coalition game credits a
+  coalition with every conversion on journeys whose channels it contains, so
+  the Shapley values are a non-negative allocation of all observed
+  conversions. They are exact — no sampling — and equal the factorial-weight
+  definition `w(s, n) = s!·(n−s−1)!/n!`. Raw values and the observed
+  coalition table are always returned; normalized shares are returned when
+  the raw values admit a valid share vector, and reported as unavailable
+  when they do not. The legacy exact-set game remains available through
+  `characteristic_function="exact"`.
+- **Optional observation weights.** `ShapleyAttribution.fit` and
+  `CompareAttribution.fit` accept per-journey `weights=` — frequency counts,
+  sampling weights, or any other nonnegative weight — under the same rules
+  as `MarkovAttribution.fit`. Weighted coalition totals are kept as
+  fractions, zero-weight journeys are excluded, and a weighted comparison
+  fits Markov and Shapley on the same weighted journeys. A fit without
+  weights is unchanged.
 - **Conservation and contract guarantees.** When normalized attribution is
   available its shares are finite, lie on `[0, 1]`, and sum to 1, and
   attributed conversions conserve the observed total. When it is not,
@@ -110,10 +120,10 @@ chronological epochs.
   or a natural-language `summary(output_format="report")` — plain Python
   strings with bounded, distilled detail tables (signed removal effects, top
   transitions and drop-offs, top coalitions, path diagnostics).
-- **Flat DataFrame export.** Temporal models expose
+- **Flat DataFrame export.** Static and temporal models expose
   `to_dataframes() -> dict[str, pd.DataFrame]`: flat, string-keyed,
-  Parquet/SQL-ready tables for attribution, raw model values, and sample
-  diagnostics — no text parsing, no `MultiIndex`, no lazy refits.
+  Parquet/SQL-ready tables for attribution, raw model values, and fit or
+  sample diagnostics — no text parsing, no `MultiIndex`, no lazy refits.
 - **Visualization.** `plot_attribution`, `plot_removal_effects`,
   `plot_transition_graph`, `plot_coalition_values`,
   `plot_attribution_comparison`, and `plot_epoch_recommendation` each return
@@ -127,8 +137,9 @@ chronological epochs.
   adjustments, residual allocation, evidence schedules, epoch-level
   reductions, and provenance explicitly separate.
 - **Calibration diagnostics.** One static adjustment-decomposition plot and
-  six temporal diagnostics show evidence alignment, ratio construction,
-  direct adjustments, residual allocation, entity mix, and evidence strength.
+  seven temporal diagnostics show evidence alignment, ratio construction,
+  experiment-reported evidence uncertainty, direct adjustments, residual
+  allocation, entity mix, and calibration-policy comparisons.
 - **Reproducible outputs.** Deterministic model fits, deterministic
   renderers, and deterministic tie ordering — identical inputs always
   produce identical reports, tables, and figures.
@@ -155,7 +166,7 @@ pip install "do-attribution[viz]"
 pip install "do-attribution[temporal,viz]"
 ```
 
-Requires Python **3.10 or newer**.
+Requires Python 3.11 or newer, NumPy 2.0.2 or newer, and pandas 3.1.1 or newer.
 
 ---
 
@@ -223,30 +234,47 @@ Removal effects (raw, signed) vs normalized shares
 +---------+----------------+--------+
 ```
 
-The Shapley model is a drop-in alternative on the same inputs. Note that
-`attribution` may be `None` — always check before indexing it:
+The Shapley model is a drop-in alternative on the same inputs:
 
 ```python
 from do_attribution import ShapleyAttribution
 
 shapley = ShapleyAttribution(conversion_labels=["Purchase"]).fit(journeys, conversions)
 
-if shapley["attribution"] is None:
-    print(shapley["normalization_status"], shapley["normalization_reason"])
-    # unavailable near_cancellation
-    print({ch: round(v, 4) for ch, v in shapley["shapley_values"].items()})
-    # {'Direct': -0.5833, 'Email': 0.25, 'Search': -0.0833, 'Social': 0.4167}
-else:
-    print({ch: round(share, 4) for ch, share in shapley["attribution"].items()})
+print(shapley["normalization_status"])
+# available
+print({ch: round(share, 4) for ch, share in shapley["attribution"].items()})
+# {'Direct': 0.1429, 'Email': 0.3095, 'Search': 0.1667, 'Social': 0.381}
+print({ch: round(v, 4) for ch, v in shapley["shapley_values"].items()})
+# {'Direct': 1.0, 'Email': 2.1667, 'Search': 1.1667, 'Social': 2.6667}
 ```
 
-On this dataset no journey touches all four channels, so `v(N) = 0`, the raw
-values cancel to float residue, and no valid share vector exists. The model
-reports that rather than dividing by the residue. The raw signed values are
-still returned — they are diagnostics on the game's own scale, not shares.
+Each converting journey splits its conversion equally among the distinct
+channels it touched, so the raw values sum to the seven observed conversions
+and the shares are those values divided by seven. `attribution` is `None`
+when normalization is unavailable — for the default game, only when no
+conversion can be credited to a channel — so code that must handle that case
+should check `normalization_status` before indexing it.
 
 Lists, NumPy arrays, and pandas Series all work as path and conversion
-inputs.
+inputs. Both must be one-dimensional: a bare string, a scalar, or a nested or
+two-dimensional container raises instead of being read as a collection of
+journeys. Each conversion outcome must be exactly `0` or `1`. Integers,
+booleans, and the exact numeric values `0.0` / `1.0` are accepted in any of
+those containers. The canonical strings `"0"` and `"1"` (text or bytes)
+remain accepted as well; no other spelling (`" 1"`, `"01"`, `"1.0"`,
+`"true"`) is. Every `fit` entry point — static, temporal (`fit` and
+`fit_by_epoch`), and `CompareAttribution` — and the `validate_data` /
+`to_int_array` helpers check the supplied values before integer conversion
+and raise a `ValueError` naming the position and the original value for a
+fractional, out-of-range, missing (`None`, `NaN`, `pd.NA`), or non-finite
+outcome.
+
+> **Compatibility — binary outcomes:** this enforces the existing
+> binary-outcome contract. Earlier releases cast outcomes to integers before
+> checking them, so `[0.9, 1.9]` was silently fitted as `[0, 1]`. Callers
+> passing probabilities or fractional counts must supply valid `0`/`1`
+> journey outcomes rather than relying on truncation.
 
 ---
 
@@ -263,6 +291,19 @@ identifies candidate temporal boundaries.
 | <img src="https://raw.githubusercontent.com/8139CAUSAL/do_attribution/main/examples/images/ga4_model_comparison.png" width="420" alt="GA4 Markov vs Shapley comparison chart"> | <img src="https://raw.githubusercontent.com/8139CAUSAL/do_attribution/main/examples/images/ga4_markov_epoch_recommendation.png" width="420" alt="GA4 epoch recommendation diagnostic plot"> |
 | `plot_attribution_comparison` — Markov and Shapley attribution on the same journeys | `plot_epoch_recommendation` — candidate and retained epoch boundaries on the conversion-rate signal |
 
+The calibration example starts from the experiment. One figure follows the
+randomized outcomes into the calibration: what each arm converted, the
+estimated lift with its 95% confidence interval beside the matched attribution
+estimate, and the calibration ratio of each epoch. The December ratio is
+marked as interpolated because no experiment ran in that month. The interval
+belongs to the experimental lift only; calibration does not propagate the
+standard error, so no ratio and no calibrated estimate carries one.
+
+| |
+| :---: |
+| <img src="https://raw.githubusercontent.com/8139CAUSAL/do_attribution/main/examples/images/calibration_experimental_evidence.png" width="860" alt="Experimental lift evidence and its translation into attribution calibration: arm outcomes, lift with 95% confidence interval versus matched MTA estimate, and calibration ratios across time"> |
+| `plot_experimental_evidence` in `examples/calibration_workflow.py` — randomized outcomes, estimated lift versus matched attribution, and observed versus interpolated calibration ratios |
+
 Calibration diagnostics keep experimental evidence, constructed calibration
 ratios, direct adjustments, and policy-based residual allocation visually
 distinct.
@@ -271,8 +312,8 @@ distinct.
 | :---: | :---: |
 | <img src="https://raw.githubusercontent.com/8139CAUSAL/do_attribution/main/examples/images/calibration_static_effects.png" width="420" alt="Static calibration effects"> | <img src="https://raw.githubusercontent.com/8139CAUSAL/do_attribution/main/examples/images/calibration_temporal_epoch_alignment.png" width="420" alt="Temporal epoch and experiment alignment"> |
 | Decomposes the calibrated estimate into original attribution, direct test adjustment, and residual allocation | Shows where experimental evidence falls on caller-defined epochs without redefining the epoch boundaries |
-| <img src="https://raw.githubusercontent.com/8139CAUSAL/do_attribution/main/examples/images/calibration_temporal_ratio_schedule.png" width="420" alt="Temporal ratio schedule"> | <img src="https://raw.githubusercontent.com/8139CAUSAL/do_attribution/main/examples/images/calibration_temporal_residual_allocation.png" width="420" alt="Temporal residual allocation"> |
-| Distinguishes observed experimental anchors from constructed epoch-level calibration ratios | Shows the required residual adjustment and its policy-based allocation across eligible recipients |
+| <img src="https://raw.githubusercontent.com/8139CAUSAL/do_attribution/main/examples/images/calibration_temporal_residual_allocation.png" width="420" alt="Temporal residual allocation"> | |
+| Shows the required residual adjustment and its policy-based allocation across eligible recipients | |
 
 ---
 
@@ -295,6 +336,28 @@ residual allocation, or calibrated total.
 Calibrated point outputs therefore do not supply confidence intervals,
 posterior uncertainty, or uncertainty-adjusted calibration ratios.
 
+The standard error is displayed wherever the evidence itself is displayed,
+as the experiment's reported uncertainty about its own observed lift:
+
+- `summary()` (static and temporal) prints an
+  `Observed lift ± standard error` line under each evidence record, for
+  example `360.00 ± 25.00 (standard error reported by the experiment;
+  calibration does not use it)`. A record without one prints
+  `360.00; no uncertainty supplied`.
+- The temporal `to_dataframes()["evidence"]` table carries `observed_lift`,
+  `standard_error`, and `uncertainty_status` beside each record;
+  `uncertainty_status` reads `standard error reported by the experiment` or
+  `no uncertainty supplied`, so a missing value is never an implied zero.
+- `plot_evidence_uncertainty()` draws each evidence record's observed lift
+  on a lift axis with a horizontal ±1 standard-error bar, and labels a record
+  without one `no uncertainty supplied`. `plot_ratio_schedule()` draws the
+  same reported error on its observed anchors, divided by the matched
+  attribution estimate so it sits on the ratio axis. Constructed schedule
+  values, effective ratios, and calibrated estimates never carry a bar.
+
+Changing `standard_error` changes those annotations only; every calibrated
+number, schedule, and provenance record is identical.
+
 `AttributionCalibration` applies that evidence to caller-approved static
 attribution estimates. `TemporalAttributionCalibration` applies dated
 evidence to estimates on a caller-supplied, authoritative epoch grid; the
@@ -315,15 +378,15 @@ the calibration notebook:
 from do_attribution import AttributionCalibration, LiftTestEvidence
 
 attributed_conversions = {
-    "Experimental Media": 1149.1519,
-    "Organic Search": 760.3327,
-    "Referral": 672.0069,
-    "Direct": 591.4872,
-    "Other": 193.9282,
-    "Paid Search": 41.3767,
-    "Organic Social": 7.8723,
-    "Affiliate": 7.6895,
-    "Email": 2.1544,
+    "Experimental Media": 1037.8436,
+    "Referral": 912.5517,
+    "Organic Search": 834.4344,
+    "Direct": 391.0936,
+    "Other": 198.3367,
+    "Paid Search": 40.5804,
+    "Email": 7.1016,
+    "Organic Social": 2.5363,
+    "Affiliate": 1.5218,
 }
 
 evidence = LiftTestEvidence(
@@ -412,12 +475,27 @@ legacy_refit["population_diagnostics"]["A"]["transformed_journey_count"]  # 4
 Raw effects from `fail`, `fail_refit`, and `detour` are diagnostics rather
 than probabilities. Signed effects from `fail_refit` or `detour` do not
 necessarily define a probability distribution and must not be interpreted as
-percentages. The model normalizes raw effects only when they satisfy the
-shared finite, nonnegative, bounded, unit-sum contract. If signed effects
-cancel at or below the scale-aware tolerance, `attribution` is `None`;
+percentages. Every strategy, `redirect_to_null` included, normalizes its raw
+effects through the same shared contract, and only when they satisfy its
+finite, nonnegative, bounded, unit-sum rules. `fit` always returns
 `normalization_status`, `normalization_reason`, and the raw-sum, magnitude,
-denominator, and cancellation-ratio diagnostics explain why while
-`removal_effects` remain available.
+denominator, and cancellation-ratio diagnostics. If signed effects cancel at
+or below the scale-aware tolerance, or every effect is zero (no journey
+converts, or stripping `conversion_labels` leaves no converting journey with
+a channel), `attribution` is `None` and those diagnostics explain why while
+`removal_effects` and `total_conversion_probability` remain available.
+
+> **Compatibility — `redirect_to_null`:** earlier releases substituted an
+> equal share per channel, with a `Total removal effect is 0` warning, when
+> every removal effect was zero, and did not return the normalization
+> diagnostics. Such a fit now returns `attribution=None` with
+> `normalization_reason="zero_raw_magnitude"` and no warning; temporal
+> epochs and `CompareAttribution` columns built from it hold missing shares
+> instead of equal ones. Callers that assumed `redirect_to_null` always
+> returned a dictionary need the availability check the other strategies
+> already require: test `normalization_status` (or `attribution is None`)
+> before indexing. Removal-effect mathematics, and the shares of any fit
+> with a nonzero effect, are unchanged.
 
 Higher orders (`order=2`, `order=3`, …) use sliding tuples as states; short
 paths are left-padded with `START`. `fit` returns `attribution`,
@@ -426,36 +504,64 @@ paths are left-padded with `START`. `fit` returns `attribution`,
 
 ### Shapley coalition attribution
 
-`ShapleyAttribution` uses the value function *v(S) = conversions on paths
-whose unique channel set is exactly S* and exact factorial weights. `fit`
-returns `attribution`, raw signed `shapley_values`, and the observed
-`value_function`:
+`ShapleyAttribution` builds a coalition game from the observed coalition
+table *R(T) = conversions on paths whose unique channel set is exactly T*,
+which `fit` returns as `value_function` alongside `attribution` and the raw
+`shapley_values`:
 
 ```python
 shapley["value_function"]
 # {('Email', 'Social'): 2, ('Email', 'Search'): 1, ('Social',): 1, ...}
 ```
 
-Raw signed `shapley_values` and normalized `attribution` are **separate
-outputs with separate contracts**:
+`characteristic_function=` selects the game *v* the Shapley values are
+computed on:
+
+| Game | *v(S)* | Efficiency: the raw values sum to | Raw values |
+| --- | --- | --- | --- |
+| `"cumulative"` (default) | Conversions on paths whose channel set is contained in *S*: the sum of *R(T)* over observed *T ⊆ S*. | Every observed conversion. | Non-negative. Each path splits its conversion equally among its distinct channels: `phi_i = Σ R(T) / |T|` over the coalitions *T* containing *i*. |
+| `"exact"` (legacy) | *R(S)*: conversions on paths whose channel set is exactly *S*. | The conversions on paths that touch every channel, `v(N)`. | Signed. |
+
+The cumulative game is monotone and its grand coalition is worth the total
+number of conversions, so its Shapley values are an allocation of the
+conversions that were actually observed. The closed form above is exactly
+the factorial-weight Shapley definition applied to that game; it is
+evaluated in one pass over the observed coalitions rather than over the
+`2^n` coalition lattice.
+
+Raw `shapley_values` and normalized `attribution` are **separate outputs
+with separate contracts**:
 
 | Output | Contract |
 | --- | --- |
-| `shapley_values` | Always present. Signed, on the game's own scale. Not shares, percentages, or probabilities. |
+| `shapley_values` | Always present, on the game's own scale (conversions), never rescaled. Under `"cumulative"` they are non-negative and sum to the observed conversions. Under `"exact"` they are signed diagnostics — not shares, percentages, or probabilities. |
 | `attribution` | A share mapping when available, otherwise `None`. Every value is finite and in `[0, 1]`, and the values sum to 1. |
 
-Because no journey may touch every channel, the efficiency axiom forces the
-raw values to sum to `v(N) = 0` by construction. Dividing by that float
-residue produces numerically explosive output, so normalization is refused
-instead: `attribution` is `None`, a warning is emitted, and the fit still
-succeeds with its raw values and diagnostics intact.
+```python
+shapley["characteristic_function"]   # 'cumulative'
+shapley["normalization_status"]      # 'available'
+shapley["raw_sum"]                   # 7.0 — the observed conversions
+shapley["cancellation_ratio"]        # 1.0
+```
+
+Under the legacy game, when no journey touches every channel the efficiency
+axiom forces the raw values to sum to `v(N) = 0` by construction. Dividing
+by that float residue produces numerically explosive output, so
+normalization is refused instead: `attribution` is `None`, a warning is
+emitted, and the fit still succeeds with its raw values and diagnostics
+intact.
 
 ```python
-shapley["normalization_status"]      # 'available' | 'unavailable'
-shapley["normalization_reason"]      # e.g. 'near_cancellation'
-shapley["raw_sum"]                   # ~1e-17 — float residue, not a real total
-shapley["raw_magnitude"]             # 1.3333
-shapley["cancellation_ratio"]        # ~1e-17 — far below the 1e-12 threshold
+legacy = ShapleyAttribution(
+    conversion_labels=["Purchase"], characteristic_function="exact"
+).fit(journeys, conversions)
+
+legacy["normalization_status"]       # 'unavailable'
+legacy["normalization_reason"]       # 'near_cancellation'
+legacy["shapley_values"]             # {'Direct': -0.5833, 'Email': 0.25, 'Search': -0.0833, 'Social': 0.4167}
+legacy["raw_sum"]                    # ~1e-17 — float residue, not a real total
+legacy["raw_magnitude"]              # 1.3333
+legacy["cancellation_ratio"]         # ~1e-17 — far below the 1e-12 threshold
 ```
 
 The exact residue in `raw_sum` is not reproducible across summation orders,
@@ -471,6 +577,50 @@ codes are `zero_raw_magnitude`, `near_cancellation`, `nonfinite_result`,
 Attributed conversions are only defined when `attribution` is available;
 they are never derived from raw signed values.
 
+#### Observation weights
+
+`ShapleyAttribution.fit(..., weights=)` takes optional per-journey
+observation weights — frequencies when one row stands for several identical
+journeys, or survey and sampling weights. The coalition table becomes
+*R_w(T) = Σ wⱼ·Yⱼ over the journeys whose channel set is exactly T*, and
+both characteristic functions are evaluated on it as they are on *R(T)*.
+Weighted totals are floats and are never truncated to integers. Without
+`weights` nothing changes: the table holds integer counts.
+
+```python
+weights = [2.5, 1.0, 1.0, 4.0, 0.5, 0.0, 2.0, 1.5, 1.0, 3.0]
+
+weighted_model = ShapleyAttribution(conversion_labels=["Purchase"])
+weighted = weighted_model.fit(journeys, conversions, weights=weights)
+
+weighted["value_function"]
+# {('Email', 'Social'): 3.5, ('Email', 'Search'): 1.0, ('Social',): 1.0, ...}
+print({ch: round(v, 4) for ch, v in weighted["shapley_values"].items()})
+# {'Email': 2.9167, 'Search': 1.1667, 'Social': 3.4167}
+print({ch: round(share, 4) for ch, share in weighted["attribution"].items()})
+# {'Email': 0.3889, 'Search': 0.1556, 'Social': 0.4556}
+weighted["raw_sum"]                  # 7.5 — the weighted conversions
+```
+
+Weights follow the `MarkovAttribution.fit(weights=)` contract: one-dimensional,
+aligned with the journeys by position (the index labels of a pandas Series
+are ignored), finite, nonnegative, and with a positive total. Booleans count
+as `0` / `1`. A journey with zero weight is excluded before the channel list
+and the coalition table are built, so a channel seen only on zero-weight
+journeys — `Direct` above — is absent from every output. Standalone
+`MarkovAttribution` does not drop zero-weight journeys from its channel
+list. Integer frequency weights give the same result as repeating each
+journey that many times.
+
+Efficiency holds on the weighted table: under `"cumulative"` the raw values
+sum to the weighted conversions of every nonempty coalition, and under
+`"exact"` to `v_w(N)`. When no positively weighted journey converts,
+`attribution` is `None` with `normalization_reason="zero_raw_magnitude"`.
+
+[`examples/weighted_attribution.ipynb`](https://github.com/8139CAUSAL/do_attribution/blob/main/examples/weighted_attribution.ipynb)
+works through frequency weights, fractional and zero weights, and a weighted
+comparison on the GA4 journey extract.
+
 ### Side-by-side comparison
 
 ```python
@@ -479,21 +629,73 @@ from do_attribution import CompareAttribution
 comparison = CompareAttribution(conversion_labels=["Purchase"])
 comparison.fit(journeys, conversions)
 
-comparison.attribution_frame()      #           markov  shapley
-                                    # Direct  0.026316      NaN
-                                    # Email   0.394737      NaN
-                                    # Search  0.201754      NaN
-                                    # Social  0.377193      NaN
-comparison.unavailable_models()     # {'shapley': 'near_cancellation'}
+comparison.attribution_frame()      #           markov   shapley
+                                    # Direct  0.071429  0.142857
+                                    # Email   0.357143  0.309524
+                                    # Search  0.214286  0.166667
+                                    # Social  0.357143  0.380952
+comparison.unavailable_models()     # {} — every model produced a share vector
 comparison.difference_frame("markov")
 ```
 
+A model whose normalization is unavailable contributes an all-`NaN` column
+and is listed by `unavailable_models()` with its reason code.
+`shapley_characteristic_function=` selects the Shapley game.
+
 The two methods answer different statistical questions and can disagree
 materially without either being defective — `difference_frame` makes the
-disagreement explicit. `extra_models={...}` plugs any additional
-`BaseAttribution` implementation into the same aligned tables, so
-first-touch, last-touch, or any custom baseline can sit beside the two
-built-in models.
+disagreement explicit.
+
+`include_baselines=True` adds the two built-in single-touch baselines as
+fixed reference points, so that disagreement can be read against the naive
+allocations practitioners actually use. `FirstTouchAttribution` gives each
+converting journey's whole conversion to the first channel it touched,
+`LastTouchAttribution` to the last. Both are `BaseAttribution` models with
+the same `fit` / `get_attribution` / `summary` API, the same validation of
+journeys and binary outcomes, the same `conversion_labels` handling, and the
+same normalization contract: `attribution` is `None`, with
+`normalization_reason="zero_raw_magnitude"`, when no conversion can be
+credited to a channel. The raw counts are returned as
+`credited_conversions`.
+
+```python
+comparison = CompareAttribution(
+    conversion_labels=["Purchase"], include_baselines=True
+)
+comparison.fit(journeys, conversions)
+
+comparison.attribution_frame()      #           markov   shapley  first_touch  last_touch
+                                    # Direct  0.071429  0.142857     0.142857    0.142857
+                                    # Email   0.357143  0.309524     0.142857    0.428571
+                                    # Search  0.214286  0.166667     0.428571    0.000000
+                                    # Social  0.357143  0.380952     0.285714    0.428571
+comparison.difference_frame("last_touch")
+```
+
+The baselines are opt-in: without `include_baselines=True` the comparison
+holds only the `markov` and `shapley` columns, exactly as before. The
+classes can also be used on their own or passed through `extra_models`.
+`extra_models={...}` plugs any additional `BaseAttribution` implementation
+into the same aligned tables, so a custom baseline can sit beside the
+built-in ones.
+
+`CompareAttribution.fit(..., weights=)` runs a weighted comparison.
+Zero-weight journeys are dropped first, and the remaining journeys and
+weights are passed to both models, so Markov and Shapley are always fitted
+on the same weighted population and neither is fitted unweighted. The
+baselines and `extra_models` do not accept weights: a weighted fit on a
+comparison built with `include_baselines=True` or with `extra_models` raises
+`ValueError` before any model is fitted.
+
+```python
+comparison = CompareAttribution(conversion_labels=["Purchase"])
+comparison.fit(journeys, conversions, weights=weights)
+
+comparison.attribution_frame()      #           markov   shapley
+                                    # Email   0.406250  0.388889
+                                    # Search  0.187500  0.155556
+                                    # Social  0.406250  0.455556
+```
 
 ### Conversion-endpoint declaration
 
@@ -577,11 +779,48 @@ diagnostics) with the complete grids available programmatically via
 `to_dataframes()` and the `get_*` accessors. The reporting language is
 descriptive; it never labels a movement statistically significant or causal.
 
+`MarkovAttribution` and `ShapleyAttribution` export their last successful
+fit with the same `to_dataframes()` call the temporal models use. Each
+returns a channel/share table (`attribution`), the raw-value table
+(`removal_effects` or `shapley_values`), and a one-row `fit_diagnostics`
+table holding the model settings and the normalization status, reason, and
+numeric diagnostics. The Markov export also carries `conversion_probability`
+in that row and a flat `transition_matrix` edge table (`from_state`,
+`to_state`, `probability`), which is empty with the same columns unless the
+model was built with `return_transition_matrix=True`. When normalization is
+unavailable the channel rows stay in `attribution` with a missing share, so
+an absent share is never written as zero credit, while the raw-value table
+keeps the signed diagnostics. The tables are copies of a snapshot taken at
+fit time: exporting never refits, and editing a returned frame changes
+neither the model nor a later export. Calling it before `fit` raises
+`RuntimeError`.
+
+The Shapley `fit_diagnostics` row ends with three observation-weight
+columns: `weights_supplied`, `total_weight` (the sum of the weights), and
+`weighted_conversions` (the sum of weight × outcome over every supplied
+journey). An unweighted fit records `False`, its journey count, and its
+conversion count. In `summary()`, the journey count, conversion count, and
+conversion rate stay plain counts of the rows passed to `fit`; a weighted
+fit adds an `Observation weights` section with the weighted totals, and its
+coalition tables show weighted conversions without rounding them to
+integers. `Path diagnostics` likewise counts rows rather than weights, over
+the rows with positive weight. With frequency weights these row counts
+describe the rows of the frequency table, not the journeys they stand for.
+
+```python
+tables = model.to_dataframes()      # `model` is the quick-start MarkovAttribution
+list(tables)
+# ['attribution', 'removal_effects', 'fit_diagnostics', 'transition_matrix']
+
+for name, table in tables.items():
+    table.to_csv(f"markov_{name}.csv", index=False)
+```
+
 ---
 
 ## Detailed examples
 
-All six notebooks run end to end on the same GA4 journey extract
+All seven notebooks run end to end on the same GA4 journey extract
 ([`examples/ga4_attribution_journeys.csv`](https://github.com/8139CAUSAL/do_attribution/blob/v0.0.2/examples/ga4_attribution_journeys.csv))
 — a transformed journey-level
 extract created from
@@ -594,9 +833,10 @@ path, a binary conversion flag, and an anchor timestamp.
 | [`examples/basic_markov.ipynb`](https://github.com/8139CAUSAL/do_attribution/blob/v0.0.2/examples/basic_markov.ipynb) | static Markov fit, shares, removal effects, summary, transition graph |
 | [`examples/basic_shapley.ipynb`](https://github.com/8139CAUSAL/do_attribution/blob/v0.0.2/examples/basic_shapley.ipynb) | Shapley shares, raw values, coalition results, coalition plot |
 | [`examples/side_by_side.ipynb`](https://github.com/8139CAUSAL/do_attribution/blob/v0.0.2/examples/side_by_side.ipynb) | `CompareAttribution` aligned tables, differences, comparison plot |
+| [`examples/weighted_attribution.ipynb`](https://github.com/8139CAUSAL/do_attribution/blob/main/examples/weighted_attribution.ipynb) | optional `weights=`: frequency weights that reproduce the one-row-per-journey Shapley fit, fractional and zero weights, the weighted summary and export, and a weighted `CompareAttribution` on a down-sampled journey table |
 | [`examples/temporal_markov.ipynb`](https://github.com/8139CAUSAL/do_attribution/blob/v0.0.2/examples/temporal_markov.ipynb) | weekly Markov epochs, diagnostics, `to_dataframes()`, epoch recommendation |
 | [`examples/temporal_shapley.ipynb`](https://github.com/8139CAUSAL/do_attribution/blob/v0.0.2/examples/temporal_shapley.ipynb) | weekly Shapley epochs, channel trends, diagnostics, epoch recommendation |
-| [`examples/attribution_experiment_calibration.ipynb`](https://github.com/8139CAUSAL/do_attribution/blob/v0.0.2/examples/attribution_experiment_calibration.ipynb) | seeded semi-synthetic randomized campaign on the GA4 rows, matched static and temporal Markov estimates, calibration, and seven diagnostics |
+| [`examples/attribution_experiment_calibration.ipynb`](https://github.com/8139CAUSAL/do_attribution/blob/v0.0.2/examples/attribution_experiment_calibration.ipynb) | seeded semi-synthetic randomized campaign on the GA4 rows, matched static and temporal Markov estimates, calibration, the experimental-evidence figure, and seven calibration diagnostics |
 
 
 ---