flua 0.0.1__tar.gz

flua-0.0.1/.gitignore

@@ -0,0 +1,208 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+notebooks/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

flua-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: pytest --tb=short -q
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true

flua-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sangwook Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flua-0.0.1/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: flua
+Version: 0.0.1
+Summary: A library for structured flu sequence analysis
+Project-URL: Homepage, https://github.com/ov3rfit/flua
+Project-URL: Repository, https://github.com/ov3rfit/flua
+Project-URL: Issues, https://github.com/ov3rfit/flua/issues
+Author-email: Sangwook Kim <windaheadjp@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: biopython>=1.85
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: ipykernel>=6.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# flua
+
+> **Note:** This project is under active development. APIs may change without notice.
+
+Influenza A sequence analysis toolkit.
+
+## (Current) Features
+
+- Load and parse influenza A FASTA files
+- Automatic sequence type detection (DNA / RNA / Protein)
+- Subtype extraction from FASTA headers (e.g. H1N1, H5N1pdm09)
+- Segment identification (PB2, PB1, PA, HA, NP, NA, MP, NS)
+- Translation with alternative product generation (splicing, frameshift, alt-ORF)
+- DataFrame export for multi-sample comparative analysis
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from flua import load_fasta, groups_to_dataframe, load_multiple_fasta
+
+group = load_fasta("sample.fasta")
+print(group.subtype)  # e.g. "H1N1"
+
+groups = load_multiple_fasta(["sample1.fasta", "sample2.fasta"])
+df = groups_to_dataframe(groups, value_type="translated")
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+```

flua-0.0.1/README.md

@@ -0,0 +1,40 @@
+# flua
+
+> **Note:** This project is under active development. APIs may change without notice.
+
+Influenza A sequence analysis toolkit.
+
+## (Current) Features
+
+- Load and parse influenza A FASTA files
+- Automatic sequence type detection (DNA / RNA / Protein)
+- Subtype extraction from FASTA headers (e.g. H1N1, H5N1pdm09)
+- Segment identification (PB2, PB1, PA, HA, NP, NA, MP, NS)
+- Translation with alternative product generation (splicing, frameshift, alt-ORF)
+- DataFrame export for multi-sample comparative analysis
+
+## Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from flua import load_fasta, groups_to_dataframe, load_multiple_fasta
+
+group = load_fasta("sample.fasta")
+print(group.subtype)  # e.g. "H1N1"
+
+groups = load_multiple_fasta(["sample1.fasta", "sample2.fasta"])
+df = groups_to_dataframe(groups, value_type="translated")
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src/ tests/
+```

flua-0.0.1/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+
+# ---- Project Metadata ----
+
+[project]
+name = "flua"
+version = "0.0.1"
+description = "A library for structured flu sequence analysis"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Sangwook Kim", email = "windaheadjp@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pandas>=2.0",
+    "biopython>=1.85",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.8",
+    "pre-commit>=4.0",
+    "ipykernel>=6.0",       # Jupyter notebook support
+]
+
+[project.urls]
+Homepage = "https://github.com/ov3rfit/flua"
+Repository = "https://github.com/ov3rfit/flua"
+Issues = "https://github.com/ov3rfit/flua/issues"
+
+
+# ---- Hatch Build Settings ----
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "notebooks/",
+    "tests/",
+    ".github/",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/flua"]
+
+
+# ---- Ruff ----
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "SIM",  # flake8-simplify
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["flua"]
+
+
+# ---- Pytest ----
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+
+# ---- Coverage ----
+
+[tool.coverage.run]
+source = ["flua"]
+omit = ["tests/*", "notebooks/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true

flua-0.0.1/src/flua/__init__.py

@@ -0,0 +1,33 @@
+"""flua – Influenza A FASTA sequence analysis toolkit."""
+
+from flua.constants import ALTERNATIVE_PRODUCTS, INFLUENZA_SEGMENTS
+from flua.display import print_group_summary
+from flua.io import groups_to_dataframe, load_fasta, load_multiple_fasta
+from flua.models import AnalyzedSequence, SequenceGroup
+from flua.products import AlternativeProduct, generate_alternative_products
+from flua.seq_utils import (
+    detect_sequence_type,
+    extract_subtype,
+    identify_segment,
+    translate_sequence,
+)
+
+__all__ = [
+    # Constants
+    "ALTERNATIVE_PRODUCTS",
+    "INFLUENZA_SEGMENTS",
+    # Models
+    "AlternativeProduct",
+    "AnalyzedSequence",
+    "SequenceGroup",
+    # Functions
+    "detect_sequence_type",
+    "extract_subtype",
+    "generate_alternative_products",
+    "groups_to_dataframe",
+    "identify_segment",
+    "load_fasta",
+    "load_multiple_fasta",
+    "print_group_summary",
+    "translate_sequence",
+]

flua-0.0.1/src/flua/constants.py

@@ -0,0 +1,110 @@
+"""Constants and configuration for influenza A sequence analysis."""
+
+from __future__ import annotations
+
+# Standard influenza A segment names (8 segments).
+INFLUENZA_SEGMENTS = ["PB2", "PB1", "PA", "HA", "NP", "NA", "MP", "NS"]
+
+# IUPAC amino acid characters that never appear in DNA/RNA sequences.
+PROTEIN_ONLY_CHARS = set("FLIMSPHQEDKWRV")
+
+# ---------------------------------------------------------------------------
+# Influenza A alternative product definitions
+# ---------------------------------------------------------------------------
+# Mechanism types:
+#   "direct"     – translate the full-length sequence in frame 1
+#   "splicing"   – join exon1 + exon2, then translate
+#   "alt_orf"    – scan a specified reading frame for the first ATG
+#   "frameshift" – ribosomal frameshift: N-terminal frame 0, then +1 frame
+#
+# Coordinates are 0-based and correspond to a canonical influenza A genome.
+# Exact positions may vary slightly between strains.
+# ---------------------------------------------------------------------------
+
+ALTERNATIVE_PRODUCTS: dict[str, list[dict]] = {
+    "PB2": [
+        {
+            "name": "PB2",
+            "mechanism": "direct",
+            "description": "RNA-dependent RNA polymerase subunit PB2",
+        },
+    ],
+    "PB1": [
+        {
+            "name": "PB1",
+            "mechanism": "direct",
+            "description": "RNA-dependent RNA polymerase subunit PB1",
+        },
+        {
+            "name": "PB1-F2",
+            "mechanism": "alt_orf",
+            "description": "Pro-apoptotic mitochondrial protein from +1 ORF of PB1",
+            "scan_frame": 1,
+            "min_length_aa": 50,
+        },
+    ],
+    "PA": [
+        {
+            "name": "PA",
+            "mechanism": "direct",
+            "description": "RNA-dependent RNA polymerase subunit PA",
+        },
+        {
+            "name": "PA-X",
+            "mechanism": "frameshift",
+            "description": "Host shutoff protein via +1 ribosomal frameshift of PA",
+            "frameshift_nt": 573,  # 191 codons * 3
+            "shift": 1,
+            "x_orf_length_aa": 61,
+        },
+    ],
+    "HA": [
+        {
+            "name": "HA",
+            "mechanism": "direct",
+            "description": "Hemagglutinin",
+        },
+    ],
+    "NP": [
+        {
+            "name": "NP",
+            "mechanism": "direct",
+            "description": "Nucleoprotein",
+        },
+    ],
+    "NA": [
+        {
+            "name": "NA",
+            "mechanism": "direct",
+            "description": "Neuraminidase",
+        },
+    ],
+    "MP": [
+        {
+            "name": "M1",
+            "mechanism": "direct",
+            "description": "Matrix protein 1 (unspliced colinear transcript)",
+        },
+        {
+            "name": "M2",
+            "mechanism": "splicing",
+            "description": "Ion channel protein (spliced from MP segment)",
+            "exon1_end": 51,
+            "exon2_start": 740,
+        },
+    ],
+    "NS": [
+        {
+            "name": "NS1",
+            "mechanism": "direct",
+            "description": "Non-structural protein 1 (unspliced colinear transcript)",
+        },
+        {
+            "name": "NEP",
+            "mechanism": "splicing",
+            "description": "Nuclear export protein / NS2 (spliced from NS segment)",
+            "exon1_end": 56,
+            "exon2_start": 529,
+        },
+    ],
+}

flua-0.0.1/src/flua/display.py

@@ -0,0 +1,26 @@
+"""Human-readable display helpers."""
+
+from __future__ import annotations
+
+from flua.models import SequenceGroup
+
+
+def print_group_summary(group: SequenceGroup) -> None:
+    """Print a concise summary of a :class:`SequenceGroup` to stdout."""
+    print(f"=== {group.group_name} (from: {group.source_file}) ===")
+    print(f"  Subtype: {group.subtype or '(not detected)'}")
+    print(f"  Total sequences: {len(group.sequences)}")
+    for seq in group.sequences:
+        seg_label = seq.segment_name or "(unknown)"
+        trans_len = len(seq.translated) if seq.translated else "-"
+        print(
+            f"  [{seg_label}] {seq.id} | "
+            f"type={seq.seq_type} | "
+            f"length={seq.length} | "
+            f"translated_length={trans_len}"
+        )
+        for p in seq.alt_products:
+            print(
+                f"    └─ {p.name} ({p.mechanism}): {p.length_aa} aa | {p.description}"
+            )
+    print()

flua-0.0.1/src/flua/io.py

@@ -0,0 +1,187 @@
+"""FASTA file I/O and DataFrame conversion."""
+
+from __future__ import annotations
+
+import warnings
+from collections import Counter
+from pathlib import Path
+from typing import Literal
+
+import pandas as pd
+from Bio import SeqIO
+
+from flua.constants import INFLUENZA_SEGMENTS
+from flua.models import AnalyzedSequence, SequenceGroup
+from flua.products import generate_alternative_products
+from flua.seq_utils import (
+    detect_sequence_type,
+    extract_subtype,
+    identify_segment,
+    translate_sequence,
+)
+
+# ── Loading ──────────────────────────────────────────────────────────────
+
+
+def load_fasta(
+    filepath: str | Path,
+    segment_names: list[str] | None = None,
+    group_name: str | None = None,
+) -> SequenceGroup:
+    """Read a single FASTA file and return a :class:`SequenceGroup`."""
+    filepath = Path(filepath)
+    if group_name is None:
+        group_name = filepath.stem
+
+    group = SequenceGroup(group_name=group_name, source_file=str(filepath))
+    detected_subtypes: list[str] = []
+
+    for record in SeqIO.parse(str(filepath), "fasta"):
+        seq_str = str(record.seq)
+        seq_type = detect_sequence_type(seq_str)
+        translated = translate_sequence(seq_str, seq_type)
+        segment = identify_segment(record.id, record.description, segment_names)
+
+        subtype = extract_subtype(record.id, record.description)
+        if subtype:
+            detected_subtypes.append(subtype)
+
+        alt_products: list = []
+        if seq_type != "Protein" and segment is not None:
+            alt_products = generate_alternative_products(seq_str, segment)
+
+        analyzed = AnalyzedSequence(
+            record=record,
+            seq_type=seq_type,
+            translated=translated,
+            segment_name=segment,
+            alt_products=alt_products,
+        )
+        group.sequences.append(analyzed)
+
+    # Assign the most frequently detected subtype to the group.
+    if detected_subtypes:
+        group.subtype = Counter(detected_subtypes).most_common(1)[0][0]
+
+    return group
+
+
+def load_multiple_fasta(
+    filepaths: list[str | Path],
+    segment_names: list[str] | None = None,
+) -> list[SequenceGroup]:
+    """Read multiple FASTA files and return a list of
+    :class:`SequenceGroup` objects."""
+    return [load_fasta(fp, segment_names=segment_names) for fp in filepaths]
+
+
+# ── DataFrame conversion ─────────────────────────────────────────────────
+
+
+def groups_to_dataframe(
+    groups: list[SequenceGroup],
+    value_type: Literal["raw", "translated"] = "raw",
+    segment_names: list[str] | None = None,
+    include_alt_products: bool = True,
+) -> pd.DataFrame:
+    """Convert a list of :class:`SequenceGroup` objects into a
+    :class:`~pandas.DataFrame`.
+
+    Parameters
+    ----------
+    groups:
+        Sequence groups to convert.
+    value_type:
+        ``"raw"`` for nucleotide sequences, ``"translated"`` for amino
+        acid sequences.
+    segment_names:
+        Segment names to include as columns.  Defaults to
+        :data:`~flua.constants.INFLUENZA_SEGMENTS`.
+    include_alt_products:
+        If ``True``, add columns for each alternative product.
+    """
+    if segment_names is None:
+        segment_names = INFLUENZA_SEGMENTS
+
+    # Collect alternative product names across all groups.
+    all_product_names: dict[str, set[str]] = {}
+    if include_alt_products:
+        for group in groups:
+            for seq in group.sequences:
+                if seq.segment_name:
+                    if seq.segment_name not in all_product_names:
+                        all_product_names[seq.segment_name] = set()
+                    for p in seq.alt_products:
+                        all_product_names[seq.segment_name].add(p.name)
+
+    rows = []
+    for group in groups:
+        row: dict = {
+            "group_name": group.group_name,
+            "source_file": group.source_file,
+            "subtype": group.subtype,
+            "num_sequences": len(group.sequences),
+        }
+
+        for seg_name in segment_names:
+            seq_obj = group.get_segment(seg_name)
+
+            if seq_obj is None:
+                row[f"{seg_name}_seq"] = None
+                row[f"{seg_name}_length"] = None
+                row[f"{seg_name}_type"] = None
+            else:
+                if value_type == "translated" and seq_obj.translated is not None:
+                    row[f"{seg_name}_seq"] = seq_obj.translated
+                    row[f"{seg_name}_length"] = len(seq_obj.translated)
+                else:
+                    row[f"{seg_name}_seq"] = seq_obj.raw_sequence
+                    row[f"{seg_name}_length"] = seq_obj.length
+                row[f"{seg_name}_type"] = seq_obj.seq_type
+
+            if include_alt_products and seg_name in all_product_names:
+                for prod_name in sorted(all_product_names[seg_name]):
+                    col_key = f"{prod_name}_protein"
+                    col_len_key = f"{prod_name}_length_aa"
+                    if seq_obj is not None:
+                        product = seq_obj.get_product(prod_name)
+                        if product is not None:
+                            row[col_key] = product.protein_seq
+                            row[col_len_key] = product.length_aa
+                        else:
+                            row[col_key] = None
+                            row[col_len_key] = None
+                    else:
+                        row[col_key] = None
+                        row[col_len_key] = None
+
+        rows.append(row)
+
+    df = pd.DataFrame(rows)
+    _check_length_consistency(df, segment_names)
+    return df
+
+
+def _check_length_consistency(df: pd.DataFrame, segment_names: list[str]) -> None:
+    """Emit a warning when sequence lengths for the same segment differ
+    across samples."""
+    if len(df) < 2:
+        return
+    for seg_name in segment_names:
+        length_col = f"{seg_name}_length"
+        if length_col not in df.columns:
+            continue
+        lengths = df[length_col].dropna()
+        if len(lengths) < 2:
+            continue
+        if len(lengths.unique()) > 1:
+            info = ", ".join(
+                f"{r['group_name']}={r[length_col]}"
+                for _, r in df.iterrows()
+                if pd.notna(r[length_col])
+            )
+            warnings.warn(
+                f"[{seg_name}] Sequence lengths differ across samples: {info}",
+                UserWarning,
+                stacklevel=3,
+            )

flua-0.0.1/src/flua/models.py

@@ -0,0 +1,74 @@
+"""Core data models for analyzed sequences and sequence groups."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from Bio.SeqRecord import SeqRecord
+
+from flua.products import AlternativeProduct
+
+
+@dataclass
+class AnalyzedSequence:
+    """A single analyzed sequence (typically one influenza segment)."""
+
+    record: SeqRecord
+    seq_type: str
+    translated: str | None
+    segment_name: str | None
+    alt_products: list[AlternativeProduct] = field(default_factory=list)
+    length: int = 0
+
+    def __post_init__(self) -> None:
+        self.length = len(self.record.seq)
+
+    @property
+    def id(self) -> str:
+        return self.record.id
+
+    @property
+    def description(self) -> str:
+        return self.record.description
+
+    @property
+    def raw_sequence(self) -> str:
+        return str(self.record.seq)
+
+    def get_product(self, name: str) -> AlternativeProduct | None:
+        """Look up an alternative product by *name* (case-insensitive)."""
+        for p in self.alt_products:
+            if p.name.upper() == name.upper():
+                return p
+        return None
+
+
+@dataclass
+class SequenceGroup:
+    """A collection of sequences originating from a single FASTA file."""
+
+    group_name: str
+    source_file: str
+    subtype: str | None = None
+    sequences: list[AnalyzedSequence] = field(default_factory=list)
+
+    @property
+    def segment_names(self) -> list[str | None]:
+        return [s.segment_name for s in self.sequences]
+
+    def get_segment(self, name: str) -> AnalyzedSequence | None:
+        """Return the sequence whose segment name matches *name*
+        (case-insensitive)."""
+        for seq in self.sequences:
+            if seq.segment_name and seq.segment_name.upper() == name.upper():
+                return seq
+        return None
+
+    def get_all_products(self) -> list[tuple[str | None, AlternativeProduct]]:
+        """Return ``(segment_name, product)`` pairs for every alternative
+        product across all sequences in the group."""
+        results = []
+        for seq in self.sequences:
+            for p in seq.alt_products:
+                results.append((seq.segment_name, p))
+        return results

flua-0.0.1/src/flua/products.py

@@ -0,0 +1,166 @@
+"""Generation of influenza A alternative protein products.
+
+Supports four mechanisms: direct translation, mRNA splicing, alternative
+ORF scanning, and ribosomal frameshifting.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from flua.constants import ALTERNATIVE_PRODUCTS
+from flua.seq_utils import translate_frame1
+
+
+@dataclass
+class AlternativeProduct:
+    """A single alternative protein product derived from an influenza
+    segment."""
+
+    name: str
+    mechanism: str
+    description: str
+    nucleotide_seq: str
+    protein_seq: str
+    length_nt: int = 0
+    length_aa: int = 0
+
+    def __post_init__(self) -> None:
+        self.length_nt = len(self.nucleotide_seq)
+        self.length_aa = len(self.protein_seq)
+
+
+# ── Per-mechanism generators ─────────────────────────────────────────────
+
+
+def _generate_direct(seq: str, pdef: dict) -> AlternativeProduct | None:
+    """Primary protein: full-length frame-1 translation."""
+    protein = translate_frame1(seq)
+    return AlternativeProduct(
+        name=pdef["name"],
+        mechanism="direct",
+        description=pdef["description"],
+        nucleotide_seq=seq,
+        protein_seq=protein,
+    )
+
+
+def _generate_spliced(seq: str, pdef: dict) -> AlternativeProduct | None:
+    """Spliced product: join exon 1 + exon 2 then translate."""
+    exon1_end = pdef["exon1_end"]
+    exon2_start = pdef["exon2_start"]
+
+    if len(seq) < exon2_start:
+        return None
+
+    spliced_nt = seq[:exon1_end] + seq[exon2_start:]
+    protein = translate_frame1(spliced_nt)
+
+    return AlternativeProduct(
+        name=pdef["name"],
+        mechanism="splicing",
+        description=pdef["description"],
+        nucleotide_seq=spliced_nt,
+        protein_seq=protein,
+    )
+
+
+def _generate_alt_orf(seq: str, pdef: dict) -> AlternativeProduct | None:
+    """Alternative ORF: scan *scan_frame* for the first ATG and translate
+    to the first stop codon."""
+    scan_frame = pdef.get("scan_frame", 1)
+    min_length_aa = pdef.get("min_length_aa", 50)
+
+    for i in range(scan_frame, len(seq) - 2, 3):
+        codon = seq[i : i + 3].upper().replace("U", "T")
+        if codon == "ATG":
+            orf_seq = seq[i:]
+            protein = translate_frame1(orf_seq)
+            if "*" in protein:
+                protein = protein[: protein.index("*")]
+            if len(protein) >= min_length_aa:
+                orf_nt = seq[i : i + (len(protein) + 1) * 3]
+                return AlternativeProduct(
+                    name=pdef["name"],
+                    mechanism="alt_orf",
+                    description=pdef["description"],
+                    nucleotide_seq=orf_nt,
+                    protein_seq=protein,
+                )
+    return None
+
+
+def _generate_frameshift(seq: str, pdef: dict) -> AlternativeProduct | None:
+    """Ribosomal frameshift: N-terminal domain (frame 0) fused with
+    C-terminal domain (+*shift* frame)."""
+    fs_nt = pdef["frameshift_nt"]
+    shift = pdef.get("shift", 1)
+    x_orf_aa_len = pdef.get("x_orf_length_aa", 61)
+
+    if len(seq) < fs_nt + 10:
+        return None
+
+    n_term_protein = translate_frame1(seq[:fs_nt])
+
+    c_term_start = fs_nt + shift
+    c_term_full = translate_frame1(seq[c_term_start:])
+    if "*" in c_term_full:
+        c_term_full = c_term_full[: c_term_full.index("*")]
+    c_term_protein = c_term_full[:x_orf_aa_len]
+
+    fusion_protein = n_term_protein + c_term_protein
+    fusion_nt = seq[: c_term_start + len(c_term_protein) * 3]
+
+    return AlternativeProduct(
+        name=pdef["name"],
+        mechanism="frameshift",
+        description=pdef["description"],
+        nucleotide_seq=fusion_nt,
+        protein_seq=fusion_protein,
+    )
+
+
+_GENERATORS = {
+    "direct": _generate_direct,
+    "splicing": _generate_spliced,
+    "alt_orf": _generate_alt_orf,
+    "frameshift": _generate_frameshift,
+}
+
+
+# ── Public API ───────────────────────────────────────────────────────────
+
+
+def generate_alternative_products(
+    sequence: str,
+    segment_name: str,
+    product_defs: dict[str, list[dict]] | None = None,
+) -> list[AlternativeProduct]:
+    """Generate all alternative products for a given segment sequence.
+
+    Parameters
+    ----------
+    sequence:
+        The nucleotide sequence of the segment.
+    segment_name:
+        One of the standard influenza A segment names (e.g. ``"PA"``).
+    product_defs:
+        Custom product definition table.  Defaults to
+        :data:`~flua.constants.ALTERNATIVE_PRODUCTS`.
+    """
+    if product_defs is None:
+        product_defs = ALTERNATIVE_PRODUCTS
+
+    defs = product_defs.get(segment_name, [])
+    if not defs:
+        defs = [{"name": segment_name, "mechanism": "direct", "description": ""}]
+
+    products = []
+    for pdef in defs:
+        generator = _GENERATORS.get(pdef["mechanism"])
+        if generator is None:
+            continue
+        product = generator(sequence, pdef)
+        if product is not None:
+            products.append(product)
+    return products

flua-0.0.1/src/flua/seq_utils.py

@@ -0,0 +1,140 @@
+"""Low-level sequence utilities: type detection, translation, subtype
+extraction, and segment identification."""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+from Bio.Seq import Seq
+
+from flua.constants import INFLUENZA_SEGMENTS, PROTEIN_ONLY_CHARS
+
+# ── Sequence type detection ──────────────────────────────────────────────
+
+
+def detect_sequence_type(sequence: str) -> Literal["DNA", "RNA", "Protein"]:
+    """Classify *sequence* as DNA, RNA, or Protein based on its character
+    composition."""
+    seq_upper = sequence.upper().replace("-", "").replace(".", "")
+    unique_chars = set(seq_upper)
+
+    if unique_chars & PROTEIN_ONLY_CHARS:
+        return "Protein"
+    if "U" in unique_chars and "T" not in unique_chars:
+        return "RNA"
+    return "DNA"
+
+
+# ── Translation ──────────────────────────────────────────────────────────
+
+
+def translate_frame1(sequence: str) -> str:
+    """Translate *sequence* in reading frame 1 (offset 0).
+
+    Trailing nucleotides that do not form a complete codon are discarded.
+    """
+    seq_obj = Seq(sequence)
+    trimmed = seq_obj[: len(seq_obj) - len(seq_obj) % 3]
+    if len(trimmed) == 0:
+        return ""
+    return str(trimmed.translate())
+
+
+def translate_sequence(sequence: str, seq_type: str) -> str | None:
+    """Return the frame-1 translation of *sequence*, or ``None`` if it is
+    already a protein."""
+    if seq_type == "Protein":
+        return None
+    return translate_frame1(sequence)
+
+
+# ── Subtype extraction ───────────────────────────────────────────────────
+
+# H<digits>N<digits> with optional parentheses and pdm suffix.
+_SUBTYPE_PATTERN = re.compile(
+    r"[\(\[\s|_/]?"
+    r"(H\d{1,2}N\d{1,2})"
+    r"[\)\]\s|_/]?"
+    r"(pdm\d{0,4})?"
+    r"[\)\]\s|_/]?",
+    re.IGNORECASE,
+)
+
+# Separate H and N tokens (e.g. "H5 subtype N6").
+_H_PATTERN = re.compile(r"(?<![A-Z0-9])(H\d{1,2})(?![A-Z0-9])", re.IGNORECASE)
+_N_PATTERN = re.compile(r"(?<![A-Z0-9])(N\d{1,2})(?![A-Z0-9])", re.IGNORECASE)
+
+
+def extract_subtype(header_id: str, description: str) -> str | None:
+    """Extract an influenza subtype string from a FASTA header.
+
+    Supported formats include ``A/California/07/2009(H1N1)``,
+    ``H5N1``, ``H1N1pdm09``, ``H3N2|segment 3``, and split
+    H/N notation such as ``"H5 subtype N6"``.
+
+    Returns
+    -------
+    str | None
+        The extracted subtype (e.g. ``"H1N1"``, ``"H5N1pdm09"``), or
+        ``None`` when no subtype is found.
+    """
+    combined = f"{header_id} {description}"
+
+    match = _SUBTYPE_PATTERN.search(combined)
+    if match:
+        subtype = match.group(1).upper()
+        pdm_suffix = match.group(2)
+        if pdm_suffix:
+            subtype += pdm_suffix.lower()
+        return subtype
+
+    h_match = _H_PATTERN.search(combined)
+    n_match = _N_PATTERN.search(combined)
+    if h_match and n_match:
+        return h_match.group(1).upper() + n_match.group(1).upper()
+
+    return None
+
+
+# ── Segment identification ───────────────────────────────────────────────
+
+
+def _build_segment_patterns(
+    segment_names: list[str],
+) -> list[tuple[str, re.Pattern]]:
+    """Build compiled regex patterns for each segment name.
+
+    Longer names are matched first so that e.g. ``"PB1-F2"`` takes
+    priority over ``"PB1"``.  Word boundaries are defined by characters
+    that are *not* alphanumeric or hyphens, preventing ``"PA"`` from
+    matching inside ``"PA-X"``.
+    """
+    sorted_names = sorted(segment_names, key=len, reverse=True)
+    patterns = []
+    for name in sorted_names:
+        escaped = re.escape(name.upper())
+        pattern = re.compile(
+            r"(?<![A-Z0-9\-])" + escaped + r"(?![A-Z0-9\-])",
+            re.IGNORECASE,
+        )
+        patterns.append((name, pattern))
+    return patterns
+
+
+def identify_segment(
+    header_id: str,
+    description: str,
+    segment_names: list[str] | None = None,
+) -> str | None:
+    """Identify the influenza segment name from a FASTA header."""
+    if segment_names is None:
+        segment_names = INFLUENZA_SEGMENTS
+
+    combined = f"{header_id} {description}"
+    patterns = _build_segment_patterns(segment_names)
+
+    for name, pattern in patterns:
+        if pattern.search(combined):
+            return name
+    return None