二级结构性质¶

解析 DNA 二级结构并计算碱基配对、茎环、配对概率、可接近性、集合缺陷和目标结构概率。

原生功能支持 dot-bracket 解析和配对概率派生指标；NUPACK 分析只在用户已获许可并独立安装 NUPACK 4 后执行，项目不会自动下载、安装或静默调用 NUPACK。

1) Dot-bracket 结构解析¶

作用： 解析 dot-bracket 字符串，恢复碱基配对关系并统计 stem、hairpin、未配对碱基等结构元素，用于检查和汇总已有二级结构预测。
计算方法： 用栈按括号类型配对开闭位置；连续的 (i,j)、(i+1,j−1) 配对合并为 stem，最内层且无嵌套配对的链内区间计为 hairpin loop。结构类型和 3′ 端二聚体标记由这些固定规则派生，不做折叠预测。
API： dnakit.secondary_structure.analyze_dot_bracket(strands[必须], dot_bracket[必须], three_prime_window[可选])
输入： 必填 DNA 链集合和长度一致的 dot-bracket；多链用 + 分隔，支持 () [] {} <>。
输出： 返回 SecondaryStructureSummary，示例展示 structure_type、base_pair_count、stem_lengths、hairpin_loop_lengths。
示例代码：

from dnakit import DNASequence
from dnakit.secondary_structure import analyze_dot_bracket

result = analyze_dot_bracket(
    (DNASequence("ATCCTAGTTATAGGAT"),),
    "((((((....))))))",
)
print(result.structure_type, result.base_pair_count)
print(result.stem_lengths, result.hairpin_loop_lengths)

示例结果：

hairpin 6
(6,) (4,)

2) 配对概率与窗口可接近性¶

作用： 校验配对概率矩阵的维度、对称性和概率范围，计算每个位置的配对与未配对概率，为 ensemble 指标提供可靠输入。
计算方法： 要求方阵对称、元素在 [0,1] 且每行连同对角线之和为 1；对角线 P(i,i) 作为未配对概率，行和减对角线作为总配对概率。窗口可接近性是窗口内各位点未配对边缘概率的算术平均。
API： dnakit.secondary_structure.pair_probability_metrics(strands[必须], probability_matrix[必须], accessibility_window_size[可选])
输入： 必填 DNA 链集合和对称方阵；对角线是未配对概率，每行含对角线后的和必须为 1；可选可接近性窗口长度。
输出： 返回 PairProbabilityResult，示例展示 pairing_probabilities_by_base、unpaired_probabilities_by_base、most_accessible_window_start。
示例代码：

from dnakit import DNASequence
from dnakit.secondary_structure import pair_probability_metrics

matrix = (
    (0.7, 0.0, 0.0, 0.3),
    (0.0, 0.8, 0.2, 0.0),
    (0.0, 0.2, 0.8, 0.0),
    (0.3, 0.0, 0.0, 0.7),
)
result = pair_probability_metrics(
    (DNASequence("ACGT"),),
    matrix,
    accessibility_window_size=2,
)
print(tuple(round(value, 1) for value in result.pairing_probabilities_by_base))
print(tuple(round(value, 1) for value in result.unpaired_probabilities_by_base))
print(result.most_accessible_window_start)

示例结果：

(0.3, 0.2, 0.2, 0.3)
(0.7, 0.8, 0.8, 0.7)
1

3) 目标结构的集合缺陷¶

作用： 根据目标配对关系和 ensemble 配对概率计算 ensemble defect，估算未按目标结构正确配对的碱基期望数量及比例。
计算方法： 为每个位点确定目标状态：未配对时取 P(i,i)，与 j 配对时取 P(i,j)；归一化集合缺陷为 Σ[1 − P(目标状态)] / N。
API： dnakit.secondary_structure.ensemble_defect_from_probabilities(target[必须], probabilities[必须])
输入： 必填 SecondaryStructureSummary 目标和描述相同 DNA 链的 PairProbabilityResult。
输出： 返回目标结构的集合缺陷浮点数。
示例代码：

from dnakit import DNASequence
from dnakit.secondary_structure import (
    analyze_dot_bracket,
    ensemble_defect_from_probabilities,
    pair_probability_metrics,
)

matrix = (
    (0.7, 0.0, 0.0, 0.3),
    (0.0, 0.8, 0.2, 0.0),
    (0.0, 0.2, 0.8, 0.0),
    (0.3, 0.0, 0.0, 0.7),
)
strands = (DNASequence("ACGT"),)
target = analyze_dot_bracket(strands, "(())")
probabilities = pair_probability_metrics(strands, matrix, accessibility_window_size=2)
print(ensemble_defect_from_probabilities(target, probabilities))

示例结果：

0.75

4) 目标结构热力学概率¶

作用： 根据目标结构自由能与配分函数计算该结构在热力学 ensemble 中的理论概率，用于比较候选结构的相对占比。
计算方法： 按 Boltzmann 关系 P(target) = exp[−(Gtarget − Gensemble)/(RT)] 计算，并将浮点结果限制在 [0,1]；函数不自行计算两个自由能。
API： dnakit.secondary_structure.target_structure_probability(target_free_energy_kcal_per_mol[必须], ensemble_free_energy_kcal_per_mol[必须], temperature_celsius[可选])
输入： 必填目标结构和集合的 kcal/mol 自由能；可选 0–100 °C 温度。
输出： 返回目标结构的热力学概率浮点数。
示例代码：

from dnakit.secondary_structure import target_structure_probability

same_energy = target_structure_probability(-2.0, -2.0)
higher_target_energy = target_structure_probability(-1.0, -2.0)
print(same_energy, round(higher_target_energy, 6))

示例结果：

1.0 0.197404

5) NUPACK 被动可用性检查¶

作用： 检查当前环境能否定位 NUPACK 安装，返回版本和安装信息，供执行结构分析前检查。
计算方法： 仅用 Python 包定位和包元数据读取检查 nupack 模块、版本与安装位置；不导入模块、不执行科学计算，也不验证数值准确性。
API： dnakit.secondary_structure.probe_nupack()
输入： 无。
输出： 返回 BackendInfo，包含 NUPACK 后端是否可用及版本信息。
示例代码：

from dnakit.secondary_structure import probe_nupack

status = probe_nupack()
print(status.available, status.version, status.metadata["import_executed"])

示例结果： 当前本地环境；安装情况不同可能改变输出。

False None False

6) NUPACK 单复合物集合分析¶

作用： 调用 NUPACK 对一个或多个 DNA 链计算 MFE 结构、自由能、配对概率或结构抽样，并转换为 DNAKit 的统一结果对象。
计算方法： 用温度、[Na⁺]+[K⁺]、Mg²⁺ 和 ensemble 构造 NUPACK DNA 模型，再显式调用外部 NUPACK 的 pfunc、mfe、pairs、subopt、sample、结构概率和 defect 接口；DNAKit 只负责输入限制、结果解析和来源记录。
API： dnakit.secondary_structure.NupackAdapter.analyze_complex(strands[必须], conditions[可选], ensemble[可选], target_structure[可选], suboptimal_energy_gap_kcal_per_mol[可选], num_samples[可选], accessibility_window_size[可选])
输入： 必填 DNA 链集合；可选 NUPACK 条件、ensemble、目标 dot-bracket、0–20 kcal/mol 次优差值和 0–100000 个抽样。
输出： 返回 NupackComplexResult，示例展示 mfe_structures、ensemble_free_energy_kcal_per_mol、dot_bracket。
示例代码：

from dnakit import DNASequence
from dnakit.secondary_structure import NupackAdapter, probe_nupack

status = probe_nupack()
if status.available:
    result = NupackAdapter().analyze_complex(
        (DNASequence("ATCCTAGTTATAGGAT"),),
        target_structure="((((((....))))))",
        num_samples=100,
    )
    print(result.mfe_structures[0].summary.dot_bracket)
    print(result.ensemble_free_energy_kcal_per_mol)
else:
    print("NUPACK unavailable")

示例结果： 当前本地环境；安装情况不同可能改变输出。

NUPACK unavailable

7) NUPACK tube 多复合物平衡¶

作用： 调用 NUPACK 在给定链浓度和温度下分析 tube 内多个复合物的平衡组成，返回各复合物浓度及质量守恒信息。
计算方法： 将命名链、投料浓度、最大复合物大小和目标复合物传给外部 NUPACK tube_analysis，由其求各复合物的平衡浓度和配对概率；DNAKit 再按本次枚举的复合物浓度总和计算目标/非目标比例。
API： dnakit.secondary_structure.NupackAdapter.analyze_tube(strands[必须], concentrations_molar[必须], target_strand_names[必须], conditions[可选], max_complex_size[可选])
输入： 必填命名 DNA 链映射、键集合相同的摩尔浓度映射和目标复合物链名；最多 20 种链，max_complex_size 为 1–4。
输出： 返回 NupackTubeResult，示例展示 target_complex_concentration_molar、target_complex_fraction、non_target_complex_fraction。
示例代码：

from dnakit import DNASequence
from dnakit.secondary_structure import NupackAdapter, probe_nupack

status = probe_nupack()
if status.available:
    result = NupackAdapter().analyze_tube(
        {"a": DNASequence("CCC"), "b": DNASequence("GGG")},
        {"a": 1e-6, "b": 1e-6},
        target_strand_names=("a", "b"),
        max_complex_size=2,
    )
    print(result.target_complex_concentration_molar)
    print(result.target_complex_fraction, result.non_target_complex_fraction)
else:
    print("NUPACK unavailable")

示例结果： 当前本地环境；安装情况不同可能改变输出。

NUPACK unavailable

NUPACK 的外部功能边界可查阅其官方分析文档、实用函数文档和模型文档；安装前须遵守其单独的下载与许可要求。

Warning

不得把 probe_nupack().available=False、dot-bracket 注释或 Primer3 结果写成 NUPACK 计算结果。