.gen 文件定义

• 无需自定义二进制 parser——用任意 SQLite 驱动打开 .gen，再按下方表结构查询即可。
• sequence_blocks 必须按 block_index 升序拼接，不能依赖数据库默认返回顺序。
• segments、qualifiers、components、alignment、references 等字段是 JSON 字符串（chromatogram 的 trace 是「UTF-8 JSON 装进 BLOB」），需二次解析。
• .gen 不持久化 restrictionSites（酶切位点），由读取程序根据主序列重新检测：GenePad 在序列长度 ≤ 50,000 bp 时同步检测，超长序列走后台流式检测。
• 保存出的 .gen 永远是自包含单文件——GenePad 落盘前执行 PRAGMA wal_checkpoint(TRUNCATE)，用户目录里不会出现 -wal/-shm 伴生文件。
• 布尔值全部以字符串 'true'/'false' 保存；键可能缺失，读取端要给默认值（见 project_meta 键参考）。

Python 内置的 sqlite3 模块就够，零第三方依赖。下面 20 行代码读出元信息、完整序列和全部 feature：

import json
import sqlite3

con = sqlite3.connect("plasmid.gen")
con.row_factory = sqlite3.Row

# —— 元信息：key-value 表，布尔以字符串保存
meta = {row["key"]: row["value"] for row in con.execute(
    "SELECT key, value FROM project_meta")}
is_circular = meta.get("isCircular") == "true"

# —— 主序列：必须按 block_index 升序拼接
sequence = "".join(row["bases"] for row in con.execute(
    "SELECT bases FROM sequence_blocks ORDER BY block_index"))
print(meta.get("name", "Untitled"), len(sequence), "bp,",
      "环状" if is_circular else "线状")

# —— features：segments / qualifiers 列是 JSON 字符串
for f in con.execute("SELECT * FROM features ORDER BY start_pos"):
    length = f["end_pos"] - f["start_pos"] + 1
    if f["start_pos"] > f["end_pos"]:                  # 跨原点的环形 feature
        length = len(sequence) - f["start_pos"] + f["end_pos"] + 1
    qualifiers = json.loads(f["qualifiers"]) if f["qualifiers"] else {}
    print(f["name"], f["type"], f["strand"], length, "bp", qualifiers)

提示：坐标是 1-based inclusive，start=1, end=10 表示第 1~10 号碱基共 10 个；环形序列跨原点时 start > end（详见坐标与环形序列）。

可以下载真实示例文件试跑：41-pPUR-P2A-BFPnls-sgRNA1-RNF2_4AtoG_MS2-MA.gen（112 KB）——7,952 bp 的环形慢病毒 sgRNA 载体，含 25 个 feature、2 条引物及结合位点。它也是一个很好的教学样本：碱基全为小写（验证「不强制大写」）、isCircular/isDamMethylated 等布尔以字符串保存、feature Misc_Feature_1 带 4 段 segments。对它运行上面代码的输出：

41-pPUR-P2A-BFPnls-sgRNA1-RNF2_4AtoG_MS2-MA 7952 bp, 环状
hPGK promoter misc_feature forward 507 bp {}
Puromycin misc_feature forward 594 bp {}
P2A misc_feature forward 57 bp {}
TagBFP2 misc_feature forward 711 bp {}
...（共 25 个 feature）

feature、primer binding site、base_color_range 的 start_pos / end_pos 均为 1-based inclusive：第一个碱基的位置是 1，start=1, end=10 表示第 1 到第 10 个碱基，长度 = end - start + 1。

环形序列（isCircular='true'）的 feature 跨越原点时直接存 start > end，长度公式变为 seqLength - start + end + 1——从 start 走到序列末尾，再从 1 绕回到 end。例：1000 bp 环形质粒上 start=995, end=5 覆盖 995–1000 加 1–5 共 11 个碱基。除 isCircular 标志外没有任何额外的环形专用字段。

多段 feature（如移码拼接、内含子跳过的 CDS）不用多行表示，而是把各段写进 segments JSON 数组，每段独立 { start, end, strand?, name?, color? }，同样是 1-based inclusive、支持 start > end 跨原点。

注意两套体系：sequence_blocks.block_index 与序列偏移是 0-based，而所有注释坐标是 1-based。换算：1-based 位置 p 位于块 floor((p-1) / 10000)。

把整个项目导出成 .gjson——GenePad 的文本 JSON 交换格式。下面这个脚本复刻了 GenePad 写出器的全部行为（键名、null 语义、空数组省略规则都一致），可直接交给 GenePad 或任何工具读回：

import json, sqlite3, time

def gen_to_gjson(path):
    con = sqlite3.connect(path)
    con.row_factory = sqlite3.Row
    j = lambda s: json.loads(s) if s else None
    meta = {r["key"]: r["value"] for r in con.execute("SELECT * FROM project_meta")}
    n = lambda k: meta.get(k) or None          # '' -> None：空串等同未设置
    sequence = "".join(r["bases"] for r in con.execute(
        "SELECT bases FROM sequence_blocks ORDER BY block_index"))

    def segs_of(raw):                          # 多段（>1）feature 才带 segments 键
        if not raw: return {}
        segs = json.loads(raw)
        return {"segments": [{"start": s["start"], "end": s["end"],
                              **({"strand": s["strand"]} if s.get("strand") else {})}
                             for s in segs]} if len(segs) > 1 else {}

    # .gen 里这两个 JSON 列是 camelCase，.gjson 里是 snake_case
    comp  = lambda c: [{"hybridized_range": x.get("hybridizedRange"),
                        "bases": x["bases"]} for x in c]
    align = lambda a: [{"type": x["type"], "primer_bases": x["primerBases"],
                        "template_bases": x["templateBases"],
                        "template_start": x["templateStart"],
                        "template_end": x["templateEnd"]} for x in a]

    features = [{
        "id": f["id"], "name": f["name"], "type": f["type"],
        "start": f["start_pos"], "end": f["end_pos"], "strand": f["strand"],
        "color": f["color"], "label": f["label"], "note": f["note"],
        "frame": f["frame"], "visible": bool(f["visible"]),
        **segs_of(f["segments"]), "qualifiers": j(f["qualifiers"]),
    } for f in con.execute("SELECT * FROM features ORDER BY start_pos")]

    primers = [{
        "id": p["id"], "name": p["name"], "sequence": p["sequence"],
        "description": p["description"],
        "bindingSites": [{
            "start": b["start_pos"], "end": b["end_pos"], "boundStrand": b["bound_strand"],
            "annealedBases": b["annealed_bases"] or "",
            "meltingTemperature": b["melting_temperature"] or 0.0,
            "components": comp(json.loads(b["components"]) if b["components"] else []),
            **({"alignment": align(json.loads(b["alignment"]))} if b["alignment"] else {}),
        } for b in con.execute("SELECT * FROM primer_binding_sites WHERE primer_id = ?",
                               (p["id"],))],
        "visible": None,                       # 写出器固定写 null
    } for p in con.execute("SELECT * FROM primers")]

    cnt = lambda t: con.execute(f"SELECT COUNT(*) FROM {t}").fetchone()[0]
    doc = {
        "version": "1.9",
        "id": f"gjson-{int(time.time() * 1000)}",      # 毫秒时间戳
        "type_of_display": "file_name",
        "custom_name": meta.get("name", "Untitled"),
        "description": meta.get("description", ""),
        "sequence": sequence,
        "length": len(sequence),
        "isCircular": meta.get("isCircular") == "true",
        "isDoubleStranded": meta.get("isDoubleStranded") != "false",
        "accession": n("accession"), "organism": n("organism"), "date": n("date"),
        "moleculeType": n("moleculeType"), "division": n("division"),
        "gbVersion": n("version"), "keywords": n("keywords"),
        "source": n("source"), "comments": n("comments"),
        "references": j(meta.get("references")),
        "features": features,
        **({"baseColorRanges": [{"id": r["id"], "color": r["color"],
                                 "start": r["start_pos"], "end": r["end_pos"],
                                 "strand": r["strand"]}
                                for r in con.execute("SELECT * FROM base_color_ranges")]}
           if cnt("base_color_ranges") else {}),
        **({"primers": primers} if primers else {}),
        **({"alignmentEntries": [{"id": a["id"], "name": a["name"],
                                  "sequence": a["sequence"], "visible": bool(a["visible"])}
                                 for a in con.execute("SELECT * FROM alignment_entries")]}
           if cnt("alignment_entries") else {}),
    }
    con.close()
    return doc

# GenePad 写出 LF 换行；Windows 上 Python 需显式 newline="\n" 才能完全一致
with open("plasmid.gjson", "w", encoding="utf-8", newline="\n") as f:
    json.dump(gen_to_gjson("plasmid.gen"), f, ensure_ascii=False, indent=2)

此脚本已与 GenePad 自身导出的同项目 .gjson 逐一核对：除两处原理性差异外完全一致——id（写出时刻的毫秒时间戳）与 feature 顺序（GenePad 按导出时的内存顺序，重开 .gen 后只能得到 start_pos 顺序）。可以用本页提供的两个样本文件自行复核：.gen 源文件、GenePad 导出的 .gjson。

转换要点：organism 等 GenBank 元数据在 .gen 里是空串 ''、在 .gjson 里写 null（空串等同未设置）；结合位点 JSON 的键名从 camelCase 转为 snake_case；primers[].visible 恒为 null；baseColorRanges/primers/alignmentEntries 为空时整个键省略；测序图谱（chromatogram）不进 .gjson。完整规则见 .gjson 文件定义。

GenePad 对外部改动完全宽容——只要仍是合法 SQLite 且符合上述约定，重新打开即生效：

import sqlite3

con = sqlite3.connect("plasmid.gen")

# 改 feature 颜色 / 项目名 / 拓扑
con.execute("UPDATE features SET color = ? WHERE name = ?", ("#7c5cff", "AmpR"))
con.execute("UPDATE project_meta SET value = 'true' WHERE key = 'isCircular'")
con.execute("UPDATE project_meta SET value = ?   WHERE key = 'name'", ("pBR322-mod",))

# 增删碱基必须整表重建 sequence_blocks：block_index 从 0 连续，块长 10000
new_seq = "ATG" + "GCT" * 100          # ...你的新序列
con.execute("DELETE FROM sequence_blocks")
con.executemany("INSERT INTO sequence_blocks VALUES (?, ?)",
                [(i // 10000, new_seq[i:i + 10000])
                 for i in range(0, len(new_seq), 10000)])
con.commit()

注意：改动碱基长度后要同步修正受影响 feature 的坐标（GenePad 不会自动重算）；isDirty 只是保存簿记，加载时不读取，外部改动无需维护它。用 Python 默认 journal 写出的文件即为自包含单文件。

最小可用文件只需要三张表——GenePad 打开时会自动补齐其余表和索引。控制解读方式的 project_meta 键如下：

import json, sqlite3

name, seq = "pDemo", "ATGGCTAGC" * 111           # 999 bp 示例序列

con = sqlite3.connect("demo.gen")
con.executescript("""
CREATE TABLE project_meta   (key TEXT PRIMARY KEY, value TEXT);
CREATE TABLE sequence_blocks(block_index INTEGER PRIMARY KEY, bases TEXT NOT NULL);
CREATE TABLE features (
    id TEXT PRIMARY KEY, name TEXT NOT NULL, type TEXT NOT NULL,
    start_pos INTEGER NOT NULL, end_pos INTEGER NOT NULL, strand TEXT NOT NULL,
    color TEXT, label TEXT, note TEXT, frame INTEGER, visible INTEGER DEFAULT 1,
    segments TEXT, qualifiers TEXT);
""")

con.executemany("INSERT INTO project_meta VALUES (?, ?)", {
    "name":       name,
    "isCircular": "true",          # 见上表；isDoubleStranded 缺省即双链
    "isDirty":    "0",
}.items())

BLOCK = 10000                       # 与 GenePad 的 BLOCK_SIZE 一致
con.executemany("INSERT INTO sequence_blocks VALUES (?, ?)",
                [(i // BLOCK, seq[i:i + BLOCK])
                 for i in range(0, len(seq), BLOCK)])

con.execute("INSERT INTO features VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)", (
    "feat-1", "GFP", "CDS", 101, 804, "forward",
    None, None, None, None, 1, None,
    json.dumps({"gene": ["gfp"]}),          # qualifiers：Record<string, string[]>
))
con.commit()

要点：feature 的 13 列一个都不能少（后几列写 NULL 即可）；块长 10000 且 block_index 连续；布尔键用小写字符串。之后 GenePad（或任何读取程序）就能直接打开这个文件。

# 打开 .gen（本质就是 SQLite；可换成本页提供的示例文件）
sqlite3 example.gen

# 列出所有表 / 建表语句
.tables
.schema features

# 读取项目名 / 拓扑
SELECT key, value FROM project_meta WHERE key IN ('name','isCircular');

# 拼接完整序列（注意按 block_index 排序）
SELECT group_concat(bases, '') FROM (SELECT bases FROM sequence_blocks ORDER BY block_index);

# 查看前几个 feature（坐标 1-based inclusive）
SELECT name, type, start_pos, end_pos, strand FROM features ORDER BY start_pos LIMIT 5;

# 看绑定位点 / 编辑历史
SELECT primer_id, start_pos, end_pos, bound_strand FROM primer_binding_sites LIMIT 5;
SELECT timestamp, description FROM edit_history ORDER BY id DESC LIMIT 5;

# 解码主序列测序图谱的 A 通道（BLOB 里是 UTF-8 JSON 数组）
SELECT CAST(trace_a AS TEXT) FROM chromatogram_data WHERE id = 'primary';

# 顺手验证魔头：应为 "SQLite format 3" + \0
xxd -l 16 example.gen

只读场景请用 sqlite3 "file:example.gen?immutable=1" 打开——避免在文件旁产生 -wal/-shm 副产品（GenePad 自带的质粒库扫描器就是这么做的，Rust 示例见Rust 读取）。

• .gjson 文件定义——单文件 JSON 交换格式，适合脚本生成与轻量共享。
• .dna 转换——SnapGene .dna 的读取与转换说明。
• Rust 读取示例——rusqlite 依赖配置、只读（immutable）打开与 .gjson 读取。