--- license: apache-2.0 pipeline_tag: feature-extraction library_name: transformers language: - en datasets: - ShuaiAnwo/PoreDNA_S1_HG002_MOD_250F701901011_A50 - ShuaiAnwo/PoreDNA_S0_HG002_UMD_250F601844011_A50 - ShuaiAnwo/PoreDNA_S0_HG002_MOD_250F701586013_A50 - ShuaiAnwo/PoreDNA_S0_HG002_MOD_250F701586014_A50 - ShuaiAnwo/PoreRNA_S0_HEK293T_MOD_250NC02303011_A50 - ShuaiAnwo/PoreRNA_S0_HEK293T_MOD_250NC02106021_A50 tags: - nanopore - nanopore-sequencing - signal-processing - neural-codec - residual-fsq - finite-scalar-quantization - vector-quantization - representation-learning - feature-extraction - foundation-model - biological-signals - genomics - bioinformatics - transformers - pytorch --- # PoreCodec-RSQF42C12A **PoreCodec-RSQf42C12A** is a lightweight neural codec for nanopore electrical signals. It converts continuous ionic current measurements into compact hierarchical discrete token sequences using a convolutional encoder followed by a production-oriented **Residual Finite Scalar Quantization (Residual FSQ)** module. Unlike traditional VQ-VAE based codecs, PoreCodec employs deterministic finite scalar quantization with exhaustive codebooks stored directly inside the model checkpoint, eliminating codebook collapse while enabling efficient constant-time decoding. The resulting discrete representations are designed to serve as the interface between raw nanopore signals and transformer-based foundation models. --- # Highlights - Production-ready neural codec for nanopore signals - Lightweight fully convolutional encoder/decoder - Residual Finite Scalar Quantization (Residual FSQ) - Exhaustive codebooks stored inside safetensors - Constant-time O(1) decoding lookup - Hierarchical discrete token generation - HuggingFace AutoModel compatible - End-to-end signal reconstruction - Foundation-model friendly discrete representation --- # Architecture ``` Raw Nanopore Signal │ ▼ CNN Encoder │ ▼ 512-D Latent Features │ ▼ Linear Projection │ ▼ Residual Finite Scalar Quantization │ ├──────────────► Hierarchical Token IDs │ ▼ Quantized Latent Features │ ▼ Linear Projection │ ▼ CNN Decoder │ ▼ Reconstructed Signal ``` The model consists of three major components: ## CNN Encoder The encoder extracts local electrical signal patterns through a deep one-dimensional convolutional network. | Property | Value | |-----------|------:| | Input channels | 1 | | Output channels | 512 | | Downsampling factor | ×4 | | Receptive field | 33 samples | The encoder transforms raw nanopore current measurements into compact latent representations while preserving local temporal structures. --- ## Residual Finite Scalar Quantization Instead of learning vector codebooks as in conventional VQ-VAE methods, PoreCodec performs deterministic residual scalar quantization over a finite Cartesian lattice. Each residual stage quantizes the reconstruction error produced by previous stages, progressively refining the latent representation. Unlike learned vector quantizers: - no codebook collapse - no dead entries - deterministic encoding - stable optimization - exact reconstruction lookup All exhaustive codebooks are precomputed and stored directly inside the model checkpoint, allowing constant-time lookup during decoding. ### Quantization Configuration | Parameter | Value | |-----------|------:| | Levels | 15 15 15 15 | | Codebook size | 50625 | | Residual quantizers | 2 | --- ## Hierarchical Tokens Each latent position produces multiple residual quantization indices ``` Latent Vector ↓ Residual Quantizer 1 ↓ Residual Quantizer 2 ↓ Level Indices ↓ Unified Token IDs ``` Different hierarchy depths may be selected: | layer | Description | |-------:|-------------| | 1 | First residual quantizer | | 2 | First two residual quantizers | | 0 | All available quantizers | Higher layers generally provide improved reconstruction quality at the expense of larger token vocabulary. --- # Signal Preprocessing The accompanying FeatureExtractor performs automatic preprocessing before inference. Pipeline: 1. Physical boundary correction 2. Spike removal 3. Median-MAD normalization 4. Optional median filtering 5. Smooth nonlinear clipping Available preprocessing strategies: ### apple (default) - Error repair - Spike removal - Median-MAD normalization - Median filtering - Smooth clipping ### mongo - Error repair - Spike removal - Median-MAD normalization - Smooth clipping --- # Quick Start ```python import numpy as np from transformers import AutoFeatureExtractor, AutoModel model_name = "ShuaiAnwo/pore-codec-rsqf42c12a-517" feature_extractor = AutoFeatureExtractor.from_pretrained( model_name, trust_remote_code=True, ) model = AutoModel.from_pretrained( model_name, trust_remote_code=True, ) model.eval() raw_signal = np.random.normal( loc=70, scale=8, size=1855, ).astype(np.float32) signal = feature_extractor( raw_signal, return_tensors="pt", )["signal"] token_ids = model.encode_signal( signal, layer=2, ) reconstructed = model.decode_token( token_ids, layer=2, ) ``` --- # API ## encode_signal Convert normalized nanopore signals into discrete token IDs. ```python token_ids = model.encode_signal(signal, layer=2) ``` Returns ``` [B, N] ``` --- ## decode_token Reconstruct signals directly from token IDs. ```python reconstructed = model.decode_token( token_ids, layer=2, ) ``` --- ## forward Complete end-to-end codec inference. ```python reconstruction, level_indices = model(signal) ``` Returns - reconstructed signal - hierarchical residual indices --- ## tokenize_indices Convert hierarchical residual indices into unified token IDs. ```python token_ids = model.tokenize_indices( level_indices, layer=2, ) ``` --- ## decode_indices Reconstruct signals directly from residual indices. ```python signal = model.decode_indices( level_indices, layer=2, ) ``` --- # Model Configuration | Parameter | Value | |-----------|------:| | CNN output dimension | 512 | | Downsampling factor | ×4 | | Receptive field | 33 | | FSQ Levels | 15 15 15 15 | | Residual Quantizers | 2 | | Codebook Size | 50625 | | Data Type | float32 | --- # Applications PoreCodec may be used for - Nanopore signal tokenization - Neural signal compression - Foundation models for nanopore sequencing - Biological representation learning - Retrieval and indexing of nanopore reads - Token-based pretraining - Generative modeling over nanopore signals --- # Advantages over Conventional VQ | Residual FSQ | Conventional VQ | |--------------|-----------------| | Deterministic | Learned codebook | | No codebook collapse | Possible collapse | | No dead entries | Dead vectors possible | | Stable optimization | Sensitive training | | O(1) lookup | Embedding search | | Exhaustive finite lattice | Learned embeddings | --- # Limitations This model is designed for nanopore electrical current signals after preprocessing by the accompanying FeatureExtractor. It is not intended for direct basecalling or DNA sequence prediction. --- # Citation If you use PoreCodec in your research, please cite: ```bibtex @misc{jiao2026porecodec, title={PoreCodec: Residual Finite Scalar Quantization for Nanopore Signal Tokenization}, author={Shuai Jiao}, year={2026} } ``` --- # License Released under the Apache-2.0 License.