Fix TraceFile(*reader) unpacking bug in docs and sampling_freq lookup

Replace broken `TraceFile(*reader)` pattern across 7 doc locations with
correct `metadata, current, voltage = Reader(...)` unpacking. Fix
`sampling_freq` initialization in datatypes.py to use dict `.get()`
instead of `getattr`, enabling automatic fallback to metadata keys.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: a-fa

README.md

@@ -18,7 +18,8 @@ from ionique.parsers import AutoSquareParser
 from ionique.utils import Filter, Trimmer, extract_features
 
 # Load and preprocess
-trace = TraceFile(*EDHReader("experiment.edh", voltage_compress=True))
+metadata, current, voltage = EDHReader("experiment.edh", voltage_compress=True)
+trace = TraceFile(current, voltage=voltage, metadata=metadata)
 Filter(cutoff_frequency=5000, filter_type="lowpass",
        sampling_frequency=trace.sampling_freq)(trace.current)
 Trimmer(samples_to_remove=500)(trace)

docs/_build/doc_example_fixes.md

@@ -9,3 +9,11 @@ Fixes for incorrect API usages found in documentation code examples.
 | `docs/parsers_guide.rst` | 128 | `parser.to_json("my_parser.json")` | `parser.to_json(filename="my_parser.json")` | `to_json()` takes `filename` as keyword arg, not positional. |
 | `docs/parsers_guide.rst` | 132 | `restored = Parser.from_json(json_str)` | Removed; added note that `from_json` is not yet implemented | `from_json` returns `None` (stub). Showing it as working is misleading. |
 | `docs/parsers/other_parsers.rst` | 202 | `IVCurveParser(voltage=voltage_array)` | `IVCurveParser(voltage_array)` | `voltage` is a positional argument in the constructor. |
+| `src/ionique/datatypes.py` | 183 | `getattr(self.unique_features,"sampling_freq",...)` | `self.unique_features.get("sampling_freq", self.metadata.get(...))` | `getattr` doesn't find dict keys; use `.get()` for dict fallback chain. |
+| `README.md` | 21 | `TraceFile(*EDHReader(...))` | Unpack reader, pass named params | `*reader` unpacks `(metadata, current, voltage)` into wrong positional args. |
+| `docs/index.rst` | 19–20 | `reader = ...; trace = TraceFile(*reader)` | Unpack reader, pass named params | Same `*reader` unpacking bug. |
+| `docs/getting_started.rst` | 24–25 | `reader = ...; trace = TraceFile(*reader)` | Unpack reader, pass named params | Same `*reader` unpacking bug. |
+| `docs/data_input.rst` | 117–120 | `TraceFile(*reader)` + misleading shorthand | Single correct `TraceFile(current, voltage=voltage, ...)` call | Removed broken pattern and misleading "shorthand" comment. |
+| `docs/tutorial.rst` | 27 | `trace = TraceFile(*reader)` | Unpack reader, pass named params | Same `*reader` unpacking bug. |
+| `docs/tutorial.rst` | 222 | `TraceFile(*EDHReader(...))` | Unpack reader, pass named params | Same `*reader` unpacking bug. |
+| `docs/signal_analysis.rst` | 131 | `trace = TraceFile(*reader)` | Unpack reader, pass named params | Same `*reader` unpacking bug. |

docs/data_input.rst

@@ -114,9 +114,6 @@ Creating a TraceFile
 
    from ionique.datatypes import TraceFile
 
-   trace = TraceFile(*reader)
-
-   # Shorthand: unpack reader directly
    trace = TraceFile(current, voltage=voltage, metadata=metadata)
 
 When ``voltage`` contains step boundaries (from ``voltage_compress=True``),

docs/getting_started.rst

@@ -21,8 +21,8 @@ Minimal workflow
    from ionique.utils import Filter, Trimmer, extract_features
 
    # 1. Load an EDH file with voltage-step splitting
-   reader = EDHReader("experiment.edh", voltage_compress=True)
-   trace = TraceFile(*reader)
+   metadata, current, voltage = EDHReader("experiment.edh", voltage_compress=True)
+   trace = TraceFile(current, voltage=voltage, metadata=metadata)
 
    # 2. Filter high-frequency noise
    filt = Filter(

docs/index.rst

@@ -16,8 +16,8 @@ around a flexible tree-based segment hierarchy.
    from ionique.utils import Filter, extract_features
 
    # Load a nanopore recording
-   reader = EDHReader("experiment.edh", voltage_compress=True)
-   trace = TraceFile(*reader)
+   metadata, current, voltage = EDHReader("experiment.edh", voltage_compress=True)
+   trace = TraceFile(current, voltage=voltage, metadata=metadata)
 
    # Filter noise
    filt = Filter(cutoff_frequency=5000, filter_type="lowpass", sampling_frequency=100000)

docs/signal_analysis.rst

@@ -127,8 +127,8 @@ Combining features from multiple files
 
    all_dfs = []
    for filename in edh_files:
-       reader = EDHReader(filename, voltage_compress=True)
-       trace = TraceFile(*reader)
+       metadata, current, voltage = EDHReader(filename, voltage_compress=True)
+       trace = TraceFile(current, voltage=voltage, metadata=metadata)
        # ... filter, trim, parse ...
        df = extract_features(
            trace, "event", ["mean", "std", "duration"],

docs/tutorial.rst

@@ -23,8 +23,8 @@ metadata, current, and voltage arrays. Wrap them in a ``TraceFile``.
    from ionique.io import EDHReader
    from ionique.datatypes import TraceFile
 
-   reader = EDHReader("experiment.edh", voltage_compress=True, downsample=1)
-   trace = TraceFile(*reader)
+   metadata, current, voltage = EDHReader("experiment.edh", voltage_compress=True, downsample=1)
+   trace = TraceFile(current, voltage=voltage, metadata=metadata)
 
    print(f"Samples: {trace.n}")
    print(f"Sampling freq: {trace.sampling_freq} Hz")
@@ -219,7 +219,8 @@ The complete pipeline:
    from ionique.utils import Filter, Trimmer, extract_features
 
    # Load
-   trace = TraceFile(*EDHReader("experiment.edh", voltage_compress=True))
+   metadata, current, voltage = EDHReader("experiment.edh", voltage_compress=True)
+   trace = TraceFile(current, voltage=voltage, metadata=metadata)
 
    # Preprocess
    Filter(cutoff_frequency=5000, filter_type="lowpass",

src/ionique/datatypes.py

@@ -180,7 +180,9 @@ def __init__(self, current: np.ndarray, voltage=None, rank="file", parent=None,
         self.end = len(self.current)
         self.metadata = metadata
         self.uuid = None
-        self.sampling_freq = getattr(self.unique_features,"sampling_freq",getattr(self.metadata,"eff_sampling_freq",getattr(self.metadata,"Sampling Frequency (SR)",None)))
+        self.sampling_freq = self.unique_features.get("sampling_freq",
+            self.metadata.get("eff_sampling_freq",
+                self.metadata.get("Sampling Frequency (SR)", None)))
         self.time = np.arange(self.start, self.end) / self.sampling_freq
 
         # If voltage data exists, create MetaSegment instance for each voltage step