readabs 0.2.0__tar.gz → 0.2.2__tar.gz

{readabs-0.2.0 → readabs-0.2.2}/CHANGELOG.md

@@ -1,3 +1,26 @@
+Version 0.2.2 released 04-Jun-2026 (Canberra Australia)
+
+ - A *selector* (in `select_one()`, `select()` and `select_and_splice()` sources)
+   can now be a bare ABS Series ID string (e.g. `"A2325846C"`) as well as the
+   `{search_value: meta_column}` dict form. A string is matched exactly against
+   the metadata's Series ID column via the same `find_abs_id` machinery (so the
+   cross-table de-duplication and uniqueness guarantees are unchanged), and an
+   unknown ID raises. The two forms mix freely across sources.
+
+---
+
+Version 0.2.1 released 03-Jun-2026 (Canberra Australia)
+
+ - `splice()` and `select_and_splice()` now default to `rebase=False` — segments
+   coalesce at their raw levels and nothing is rescaled unless you opt in with
+   `rebase=True`. Rebasing is only valid for ratio-scale (index-like) series, so
+   splicing index series across a reference-period change (e.g. CPI) now needs an
+   explicit `rebase=True`.
+ - `splice()` now raises on a non-finite or non-positive rebase factor instead of
+   producing a sign-flipped or exploded back-history.
+
+---
+
 Version 0.2.0 released 03-Jun-2026 (Canberra Australia)
 
  - Added a series-splicing toolkit for joining mixed-frequency and multi-vintage

{readabs-0.2.0 → readabs-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: readabs
-Version: 0.2.0
+Version: 0.2.2
 Summary: Get ABS timeseries data in pandas DataFrames
 Project-URL: Repository, https://github.com/bpalmer4/readabs
 Project-URL: Homepage, https://github.com/bpalmer4/readabs
@@ -202,11 +202,14 @@ scaled_data, new_units = ra.recalibrate(data, "Number")
 Many ABS concepts are spread across frequencies and releases — e.g. a *monthly*
 CPI that only reaches back to 2017, a *quarterly* one back to 1948, and a
 discontinued monthly indicator covering the gap between. `splice` joins such
-segments into one continuous series, **highest priority first**: it rebases
-segments whose levels differ (e.g. an index reference-period change), prefers the
-higher-priority value where periods overlap, and leaves honest gaps where no
-source has data (no interpolation, nothing invented). A join report records every
-rebase factor and overlap so a splice can be audited rather than trusted blindly.
+segments into one continuous series, **highest priority first**: it prefers the
+higher-priority value where periods overlap and leaves honest gaps where no
+source has data (no interpolation, nothing invented). Pass `rebase=True` to
+*multiplicatively* rescale segments whose levels differ (e.g. an index
+reference-period change) onto the running result — it is off by default, because
+rebasing transforms your data and is only valid for ratio-scale (index-like)
+series. A join report records every rebase factor and overlap so a splice can be
+audited rather than trusted blindly.
 
 Four composable functions:
 
@@ -217,16 +220,26 @@ Four composable functions:
 | `splice(segments)` | Splice an iterable of series, highest priority first → `(series, report)` |
 | `select_and_splice(sources)` | `select` then `splice` for the no-transform case; checks units → `(series, unit, report)` |
 
-A *selector* is the `{search_value: column}` form used by `find_abs_id` (with
-`validate_unique=True`, so it de-duplicates on Series ID and raises on genuine
-ambiguity rather than guessing).
+A *selector* is either the `{search_value: column}` form used by `find_abs_id`
+(with `validate_unique=True`, so it de-duplicates on Series ID and raises on
+genuine ambiguity rather than guessing), **or a bare ABS Series ID string**
+(e.g. `"A2325846C"`, matched exactly) for when you already know precisely which
+series you want. The two forms mix freely across sources:
+
+```python
+series, unit, report = ra.select_and_splice([
+    (cur, cmeta, base | {"Month": mc.freq}),   # by description
+    (cur, cmeta, "A2325846C"),                 # by Series ID (quarterly All groups CPI)
+], rebase=True)
+```
 
 By default `select` **raises if the selected series carry different ABS units** —
 coherence is required to splice. Pass `require_same_units=False` to select
 different-unit series on purpose (as the unemployment example below does).
 
-**No transform — splice raw levels** (headline CPI index: new monthly over the
-discontinued indicator over the long quarterly):
+**No per-series transform — splice index levels with `rebase=True`** (headline
+CPI index: new monthly over the discontinued indicator over the long quarterly,
+rescaled across reference-period changes):
 
 ```python
 cur, cmeta = ra.read_abs_cat("6401.0")                       # monthly + long quarterly
@@ -240,11 +253,14 @@ series, unit, report = ra.select_and_splice(
         (cur, cmeta, base | {"Quarter": mc.freq}),   # quarterly back to 1948
     ],
     output="M",
+    rebase=True,   # index reference-period change -> rescale onto the running result
 )
 ```
 
 The shared `base` selector resolves the same concept in all three sources; only
-the frequency override changes.
+the frequency override changes. `rebase=True` is needed because these index
+segments sit on different reference periods — for series that already share a
+level (or aren't ratio-scale), leave it off.
 
 **With a transform — select, transform each, then splice** (year-ended inflation:
 a Y/Y change is base-invariant, so compute it per source and splice the *rates*

{readabs-0.2.0 → readabs-0.2.2}/README.md

@@ -180,11 +180,14 @@ scaled_data, new_units = ra.recalibrate(data, "Number")
 Many ABS concepts are spread across frequencies and releases — e.g. a *monthly*
 CPI that only reaches back to 2017, a *quarterly* one back to 1948, and a
 discontinued monthly indicator covering the gap between. `splice` joins such
-segments into one continuous series, **highest priority first**: it rebases
-segments whose levels differ (e.g. an index reference-period change), prefers the
-higher-priority value where periods overlap, and leaves honest gaps where no
-source has data (no interpolation, nothing invented). A join report records every
-rebase factor and overlap so a splice can be audited rather than trusted blindly.
+segments into one continuous series, **highest priority first**: it prefers the
+higher-priority value where periods overlap and leaves honest gaps where no
+source has data (no interpolation, nothing invented). Pass `rebase=True` to
+*multiplicatively* rescale segments whose levels differ (e.g. an index
+reference-period change) onto the running result — it is off by default, because
+rebasing transforms your data and is only valid for ratio-scale (index-like)
+series. A join report records every rebase factor and overlap so a splice can be
+audited rather than trusted blindly.
 
 Four composable functions:
 
@@ -195,16 +198,26 @@ Four composable functions:
 | `splice(segments)` | Splice an iterable of series, highest priority first → `(series, report)` |
 | `select_and_splice(sources)` | `select` then `splice` for the no-transform case; checks units → `(series, unit, report)` |
 
-A *selector* is the `{search_value: column}` form used by `find_abs_id` (with
-`validate_unique=True`, so it de-duplicates on Series ID and raises on genuine
-ambiguity rather than guessing).
+A *selector* is either the `{search_value: column}` form used by `find_abs_id`
+(with `validate_unique=True`, so it de-duplicates on Series ID and raises on
+genuine ambiguity rather than guessing), **or a bare ABS Series ID string**
+(e.g. `"A2325846C"`, matched exactly) for when you already know precisely which
+series you want. The two forms mix freely across sources:
+
+```python
+series, unit, report = ra.select_and_splice([
+    (cur, cmeta, base | {"Month": mc.freq}),   # by description
+    (cur, cmeta, "A2325846C"),                 # by Series ID (quarterly All groups CPI)
+], rebase=True)
+```
 
 By default `select` **raises if the selected series carry different ABS units** —
 coherence is required to splice. Pass `require_same_units=False` to select
 different-unit series on purpose (as the unemployment example below does).
 
-**No transform — splice raw levels** (headline CPI index: new monthly over the
-discontinued indicator over the long quarterly):
+**No per-series transform — splice index levels with `rebase=True`** (headline
+CPI index: new monthly over the discontinued indicator over the long quarterly,
+rescaled across reference-period changes):
 
 ```python
 cur, cmeta = ra.read_abs_cat("6401.0")                       # monthly + long quarterly
@@ -218,11 +231,14 @@ series, unit, report = ra.select_and_splice(
         (cur, cmeta, base | {"Quarter": mc.freq}),   # quarterly back to 1948
     ],
     output="M",
+    rebase=True,   # index reference-period change -> rescale onto the running result
 )
 ```
 
 The shared `base` selector resolves the same concept in all three sources; only
-the frequency override changes.
+the frequency override changes. `rebase=True` is needed because these index
+segments sit on different reference periods — for series that already share a
+level (or aren't ratio-scale), leave it off.
 
 **With a transform — select, transform each, then splice** (year-ended inflation:
 a Y/Y change is base-invariant, so compute it per source and splice the *rates*