.. _ionique:

ionique: Nanopore Signal Analysis
==================================

.. |version| replace:: |release|

**Version**: |release|

ionique is a Python framework for processing ionic current data from nanopore
experiments. It provides a unified workflow for loading raw traces, filtering
noise, detecting translocation events, and extracting features — all built
around a flexible tree-based segment hierarchy.

.. code-block:: python

   from ionique.io import EDHReader
   from ionique.datatypes import TraceFile
   from ionique.parsers import AutoSquareParser, SpeedyStatSplit
   from ionique.utils import Filter, extract_features

   # Load a nanopore recording
   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)
   filt(trace.current)

   # Detect blockade events in each voltage step
   detector = AutoSquareParser(threshold_baseline=0.7, expected_conductance=1.9)
   trace.parse(detector, newrank="event", at_child_rank="vstep")

   # Segment sub-states within each event
   splitter = SpeedyStatSplit(sampling_freq=100000, min_width=50)
   trace.parse(splitter, newrank="state", at_child_rank="event")

   # Extract features to a DataFrame
   df = extract_features(trace, "event", ["mean", "std", "duration"])

Key capabilities:

- **File I/O** — Read ``.edh``, ``.opt``, and ``.abf`` formats with automatic
  unit scaling and voltage-step detection.
- **Signal preprocessing** — Lowpass/highpass/bandpass filtering, clock-tone
  removal, and edge trimming.
- **Event detection** — Parsers for finding translocation events: spike
  detection (SpikeParser), square-pulse analysis (AutoSquareParser), and
  threshold-based rules (lambda_event_parser).
- **Sub-state segmentation** — SpeedyStatSplit resolves multi-level current
  states within detected events using variance-based recursive splitting.
- **Segment tree** — Hierarchical data model (file → voltage step → event)
  with recursive parsing, feature lookup, and memory-efficient MetaSegments.
- **Feature extraction** — Export segment statistics to pandas DataFrames with
  custom computed columns.
- **Visualization** — Quick trace plotting with ``qp_trace()`` and interactive
  Panel/Bokeh dashboards.


.. toctree::
   :maxdepth: 2
   :caption: Getting Started

   installation

.. toctree::
   :maxdepth: 2
   :caption: User Guide

   getting_started
   data_input
   concepts
   signal_preprocess
   parsers_guide
   signal_analysis
   visualization
   tutorial

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   api_reference


Indices and tables
==================

* :ref:`genindex`
* :ref:`search`