AutoSquareParser

AutoSquareParser detects rectangular (square-pulse) blockade events — the signature of protein or polymer translocations through nanopores. It identifies regions where current drops below a threshold fraction of the open-channel baseline.

from ionique.parsers import AutoSquareParser

parser = AutoSquareParser(
    threshold_baseline=0.7,
    expected_conductance=1.9,
)
trace.parse(parser, newrank="event", at_child_rank="vstep")

Parameters

Parameter	Default	Description
`threshold_baseline`	`0.7`	Fraction of baseline current that defines an event. A value of 0.7 means any region below 70% of baseline is considered a blockade.
`expected_conductance`	`1.9`	Expected open-channel conductance in nS. Used to validate that the baseline is reasonable.
`conductance_tolerance`	`1.2`	Multiplicative tolerance for conductance validation.
`wrap_padding`	`50`	Number of context samples to include before and after each detected event (stored in `unique_features["wrap"]`).
`rules`	`[]`	List of callable rules for post-filtering events. Each rule takes a segment dict and returns `True` to keep it.

The parser also requires eff_sampling_freq and voltage to be available (passed automatically when parsing within a TraceFile tree).

Parameter sensitivity

threshold_baseline

The most important parameter. Lower values require deeper blockades to trigger detection; higher values detect shallower events (but may pick up noise).

# Sensitive: detect shallow blockades
parser = AutoSquareParser(threshold_baseline=0.9)

# Strict: only detect deep blockades
parser = AutoSquareParser(threshold_baseline=0.5)

expected_conductance

Used to validate that the open-channel baseline is physically reasonable. Set this to match your nanopore’s conductance (typically 1–5 nS for solid- state pores).

Using rules for post-filtering

The rules parameter accepts lambda functions that filter events after detection. Each rule receives a dictionary with event properties and returns True to keep the event:

parser = AutoSquareParser(
    threshold_baseline=0.7,
    expected_conductance=1.9,
    rules=[
        lambda ev: ev["frac"] < 0.9,        # blockade must be >10% of baseline
        lambda ev: (ev["end"] - ev["start"]) > 50,  # minimum 50 samples
    ],
)

Full example

from ionique.parsers import AutoSquareParser

parser = AutoSquareParser(
    threshold_baseline=0.7,
    expected_conductance=1.9,
    wrap_padding=100,
)

trace.parse(parser, newrank="event", at_child_rank="vstep")

events = trace.traverse_to_rank("event")
print(f"Detected {len(events)} blockade events")

for ev in events[:5]:
    baseline = ev.unique_features.get("baseline", None)
    frac = ev.unique_features.get("frac", None)
    print(f"  [{ev.start}:{ev.end}] baseline={baseline:.3f}, I/I0={frac:.3f}")

Per-event features

AutoSquareParser stores additional metadata in each event’s unique_features:

Key	Description
`baseline`	Open-channel current before the blockade (nA).
`mean`	Mean current during the blockade (nA).
`frac`	Fractional blockade depth: `mean / baseline`.
`wrap`	Context window around the event (numpy array with padding).