Bolster API docs and some black formatting.

Author: Eli

vtools/functions/blend.py

@@ -1,4 +1,3 @@
-
 import pandas as pd
 import numpy as np
 from vtools import to_timedelta
@@ -7,6 +6,7 @@
 
 __all__ = ["ts_blend"]
 
+
 def _blend_output_index(series):
     """
     Determine the working index for ts_blend.
@@ -42,6 +42,7 @@ def _blend_output_index(series):
 
     return regular_index_from_valid_extent(series, output_freq)
 
+
 def _distance_to_gap(hi_col: pd.Series, mode: str = "count") -> pd.Series:
     """
     Distance to nearest gap (NaN) in hi_col.
@@ -95,7 +96,9 @@ def _distance_to_gap(hi_col: pd.Series, mode: str = "count") -> pd.Series:
     if mode == "freq":
         freq = idx.freq
         if freq is None:
-            raise ValueError("Time-based blending requires a regular index with .freq set.")
+            raise ValueError(
+                "Time-based blending requires a regular index with .freq set."
+            )
         # counts * freq → Timedelta
         return dist_s * to_timedelta(freq)
 
@@ -127,9 +130,13 @@ def _normalize_blend_length(blend_length, index):
     # Timedelta-like: e.g. '2h', '30min'
     td = pd.to_timedelta(blend_length)
     if not isinstance(index, (pd.DatetimeIndex, pd.PeriodIndex)):
-        raise ValueError("Time-based blend_length requires a DatetimeIndex or PeriodIndex.")
+        raise ValueError(
+            "Time-based blend_length requires a DatetimeIndex or PeriodIndex."
+        )
     if index.freq is None:
-        raise ValueError("Time-based blend_length requires a regular index with a .freq attribute.")
+        raise ValueError(
+            "Time-based blend_length requires a regular index with a .freq attribute."
+        )
     if td <= pd.Timedelta(0):
         return None, None
 
@@ -166,8 +173,16 @@ def _blend_two(
     cols = sorted(set(aligned_hi.columns) | set(aligned_lo.columns))
 
     for col in cols:
-        hi_col = aligned_hi[col] if col in aligned_hi.columns else pd.Series(index=idx, dtype=float)
-        lo_col = aligned_lo[col] if col in aligned_lo.columns else pd.Series(index=idx, dtype=float)
+        hi_col = (
+            aligned_hi[col]
+            if col in aligned_hi.columns
+            else pd.Series(index=idx, dtype=float)
+        )
+        lo_col = (
+            aligned_lo[col]
+            if col in aligned_lo.columns
+            else pd.Series(index=idx, dtype=float)
+        )
 
         hi_nan = hi_col.isna()
         lo_nan = lo_col.isna()
@@ -214,8 +229,7 @@ def _blend_two(
         lo_vals = lo_col[near_gap].astype(float)
 
         blended_vals = (
-            w_hi.to_numpy() * hi_vals.to_numpy()
-            + w_lo.to_numpy() * lo_vals.to_numpy()
+            w_hi.to_numpy() * hi_vals.to_numpy() + w_lo.to_numpy() * lo_vals.to_numpy()
         )
 
         # IMPORTANT: use .loc with a boolean mask, not .at, so we never hit
@@ -235,6 +249,7 @@ def _blend_two(
 
 __all__ = ["ts_blend"]
 
+
 def _blend_output_index(series):
     """
     Determine the working index for ts_blend.
@@ -270,6 +285,7 @@ def _blend_output_index(series):
 
     return regular_index_from_valid_extent(series, output_freq)
 
+
 def _distance_to_gap(hi_col: pd.Series, mode: str = "count") -> pd.Series:
     """
     Distance to nearest gap (NaN) in hi_col.
@@ -323,7 +339,9 @@ def _distance_to_gap(hi_col: pd.Series, mode: str = "count") -> pd.Series:
     if mode == "freq":
         freq = idx.freq
         if freq is None:
-            raise ValueError("Time-based blending requires a regular index with .freq set.")
+            raise ValueError(
+                "Time-based blending requires a regular index with .freq set."
+            )
         # counts * freq → Timedelta
         return dist_s * to_timedelta(freq)
 
@@ -355,9 +373,13 @@ def _normalize_blend_length(blend_length, index):
     # Timedelta-like: e.g. '2h', '30min'
     td = pd.to_timedelta(blend_length)
     if not isinstance(index, (pd.DatetimeIndex, pd.PeriodIndex)):
-        raise ValueError("Time-based blend_length requires a DatetimeIndex or PeriodIndex.")
+        raise ValueError(
+            "Time-based blend_length requires a DatetimeIndex or PeriodIndex."
+        )
     if index.freq is None:
-        raise ValueError("Time-based blend_length requires a regular index with a .freq attribute.")
+        raise ValueError(
+            "Time-based blend_length requires a regular index with a .freq attribute."
+        )
     if td <= pd.Timedelta(0):
         return None, None
 
@@ -394,8 +416,16 @@ def _blend_two(
     cols = sorted(set(aligned_hi.columns) | set(aligned_lo.columns))
 
     for col in cols:
-        hi_col = aligned_hi[col] if col in aligned_hi.columns else pd.Series(index=idx, dtype=float)
-        lo_col = aligned_lo[col] if col in aligned_lo.columns else pd.Series(index=idx, dtype=float)
+        hi_col = (
+            aligned_hi[col]
+            if col in aligned_hi.columns
+            else pd.Series(index=idx, dtype=float)
+        )
+        lo_col = (
+            aligned_lo[col]
+            if col in aligned_lo.columns
+            else pd.Series(index=idx, dtype=float)
+        )
 
         hi_nan = hi_col.isna()
         lo_nan = lo_col.isna()
@@ -442,8 +472,7 @@ def _blend_two(
         lo_vals = lo_col[near_gap].astype(float)
 
         blended_vals = (
-            w_hi.to_numpy() * hi_vals.to_numpy()
-            + w_lo.to_numpy() * lo_vals.to_numpy()
+            w_hi.to_numpy() * hi_vals.to_numpy() + w_lo.to_numpy() * lo_vals.to_numpy()
         )
 
         # IMPORTANT: use .loc with a boolean mask, not .at, so we never hit
@@ -454,12 +483,9 @@ def _blend_two(
 
     return out
 
+
 @align_inputs_strict(seq_arg=0, names_kw="names")
-def ts_blend(
-    series,
-    names=None,
-    blend_length=None
-):
+def ts_blend(series, names=None, blend_length=None):
     """
     Blend multiple time series together, using higher priority where possible,
     but ramping in lower-priority data near gaps in the higher-priority series.
@@ -507,7 +533,9 @@ def ts_blend(
     # If any DataFrame is present, normalize all to DataFrame
     any_df = any(isinstance(s, pd.DataFrame) for s in series)
     if any_df:
-        series = [s.to_frame(name=s.name) if isinstance(s, pd.Series) else s for s in series]
+        series = [
+            s.to_frame(name=s.name) if isinstance(s, pd.Series) else s for s in series
+        ]
 
     all_df = all(isinstance(s, pd.DataFrame) for s in series)
     any_series = any(isinstance(s, pd.Series) for s in series)
@@ -523,17 +551,17 @@ def ts_blend(
                     )
     elif any_df and any_series:
         if names is None:
-            df_cols = {c for s in series if isinstance(s, pd.DataFrame) for c in s.columns}
+            df_cols = {
+                c for s in series if isinstance(s, pd.DataFrame) for c in s.columns
+            }
             for s in series:
                 if isinstance(s, pd.Series) and s.name not in df_cols:
                     raise ValueError(
                         "Mixed Series and DataFrames require Series names to match DataFrame columns."
                     )
 
     # Build working index according to frequency policy.
-    full_index = _blend_output_index(
-        series
-    )
+    full_index = _blend_output_index(series)
 
     # Normalize blend_length against the working index
     blend_mode, blend_L = _normalize_blend_length(blend_length, full_index)
@@ -557,4 +585,4 @@ def ts_blend(
     elif isinstance(blended, pd.Series):
         blended = blended.to_frame()
 
-    return blended
+    return blended

vtools/functions/error_detect.py

@@ -119,10 +119,10 @@ def bounds_test(ts, bounds):
     if bounds is not None:
         lo, hi = bounds
         if lo is not None:
-            anomaly |= (ts < lo)
+            anomaly |= ts < lo
         if hi is not None:
-            anomaly |= (ts > hi)
-            
+            anomaly |= ts > hi
+
     return anomaly
 
 
@@ -136,6 +136,7 @@ def median_test(ts, level=4, filt_len=7, quantiles=(0.005, 0.095), copy=True):
         as_anomaly=True,
     )
 
+
 def choose_npartitions(
     nrows,
     *,
@@ -169,6 +170,7 @@ def choose_npartitions(
     max_safe = max(1, nrows // min_partition_size)
     return max(1, min(proposed, max_safe))
 
+
 def median_test_oneside(
     ts,
     scale=None,
@@ -186,7 +188,7 @@ def median_test_oneside(
         vals = ts[::-1]
     else:
         vals = ts
-        
+
     if isinstance(vals, pd.Series):
         vals = vals.to_frame(name="ts")
     elif isinstance(vals, pd.DataFrame):
@@ -342,7 +344,6 @@ def median_test_twoside(
 
     vals = ts_out.to_numpy()
 
-
     def mseq(flen):
         halflen = flen // 2
         a = np.arange(0, halflen)
@@ -482,7 +483,9 @@ def steep_then_nan(
         elif gap_aggregation == "all":
             near_t = near.all(axis=1)
         else:
-            raise ValueError(f"gap_aggregation must be 'any' or 'all', got {gap_aggregation!r}")
+            raise ValueError(
+                f"gap_aggregation must be 'any' or 'all', got {gap_aggregation!r}"
+            )
     else:
         near_t = near
 
@@ -523,6 +526,7 @@ def steep_then_nan(
     warnings.resetwarnings()
     return ts_out
 
+
 def despike(arr, n1=2, n2=20, block=10, *, as_anomaly=False):
     """Detect and optionally remove isolated spikes using overlapping-window statistics.