DNADNA

用于DNA的深度神经网络。

本包的目标是提供实用函数，以改善种群遗传学神经网络的开发。

dnadna应允许研究人员专注于他们的研究项目，无论是分析种群遗传学数据还是构建新的方法，无需关注正确的开发方法（单元测试、持续集成、文档等）。因此，结果将更容易重复和共享。具有通用接口也将降低错误的风险。

安装

使用conda/mamba

由于DNADNA有一些非平凡的依赖项（最显著的是PyTorch），安装它的最简单方法是在conda环境中。我们将展示如何使用mamba（这是conda的一个更快的实现）来安装它。请注意，以下所有命令都将使用conda而不是mamba，除非另有说明。

如果您还没有安装 conda，请按照官方说明安装全功能的Anaconda发行版，或者更推荐安装较小的Miniconda发行版。一旦安装了conda，您可以按照Mamba的安装说明进行。

您可以在现有的conda环境中安装DNADNA，但最简单的方法是使用mamba在一个新的环境中安装它。首先创建一个新的环境

$ mamba create -n dnadna

其中环境的名称（-n）为dnadna（此时尚未安装DNADNA）。

使用mamba activate dnadna激活环境。

然后可以通过运行以下命令安装和更新DNADNA

$ mamba install -c mlgenetics -c pytorch -c bioconda -c conda-forge dnadna

每个-c标志指定了一个需要搜索依赖项的conda“频道”。如果您想将“mlgenetics”频道及其依赖项添加到您的默认conda频道列表中，您可以运行

$ conda config --add channels mlgenetics \
               --add channels pytorch \
               --add channels conda-forge \
               --add channels bioconda

注意：此命令仅在conda中有效，目前不适用于mamba。

可以通过运行dnadna -h确保dnadna已正确安装。

可选依赖项

DNADNA支持以TensorBoard格式记录训练过程中的损失（以及最终的其他统计信息），以更好地进行损失可视化。

为了确保TensorBoard支持已启用，您可以在您的活动conda环境中使用以下命令安装它：

$ mamba install -c conda-forge tensorboard

DNADNA可以用于Jupyter笔记本中。如果您正在使用conda/mamba环境，您需要将jupyterlab安装在DNADNA相同的环境中。

$ mamba activate dnadna
$ mamba install -c conda-forge jupyterlab

使用PyPI

如果您不希望使用conda，而是直接使用PyPI+pip安装DNADNA及其依赖项，可以运行

$ pip install dnadna

注意：我们仍然建议在conda环境中安装它。

开发

或者，您可能需要克隆DNADNA的git仓库并从那里安装

$ git clone https://gitlab.com/mlgenetics/dnadna.git
$ cd dnadna
$ mamba env create
$ mamba activate dnadna
$ pip install .

或者使用较轻的仅CPU环境

$ git clone https://gitlab.com/mlgenetics/dnadna.git
$ cd dnadna
$ mamba env create --file environment-cpu.yml
$ mamba activate dnadna-cpu
$ pip install .

如果您打算在包上进行开发，建议选择git clone解决方案，并通过运行以下命令以“可编辑”模式安装

$ pip install -e .

更新

如果使用conda/mamba安装，可以通过运行以下命令更新DNADNA

$ mamba update -c mlgenetics -c pytorch -c conda-forge dnadna

或者，如果您已经将发布频道添加到您的默认频道中，可以简单地

$ mamba update dnadna

内部用户/开发人员说明

在https://gitlab.inria.fr上的私有仓库用户应查看开发文档，了解如何访问私有仓库的说明。

Docker

还包括一个Dockerfile，用于构建包含DNADNA的Docker镜像（它基于conda，因此基本上重新创建了上述的安装环境，包括GPU支持。要构建镜像，请运行

$ docker build --tag dnadna .

请确保从仓库的根目录运行此命令，因为整个仓库需要传递给Docker构建上下文。

如果未指定任何其他命令，它将打开一个具有启用的dnadna conda环境的shell。

$ docker run -ti dnadna

但是，您也可以非交互式运行它，例如通过指定dnadna命令。在这种情况下，挂载数据目录（您的模拟/训练文件）也是一个好主意。例如

$ docker run -t -v /path/to/my/data:/data --workdir /data dnadna dnadna init

有关Docker镜像的附加说明

• 默认情况下，它会以非root用户“dnadna”登录，UID为1001，GID也为1001。如果您使用带--user标志和自己的UID启动容器，它将更改“dnadna”用户的UID和GID。请确保指定UID和GID，否则“dnadna”拥有的所有文件的组将更改为“root”。例如，运行：docker run -u $(id -u):$(id -g)。

• 默认的工作目录是/home/dnadna/dnadna，其中包含dnadna包的源代码。

• 如果您想安装自己的conda包（例如，为了使用此容器进行开发），在启动容器后，最好从基本环境克隆一个新的conda环境，然后重新安装dnadna

  $ conda create -n dnadna --clone base
  $ conda activate dnadna
  $ pip install -e .
  

  由于在非开发情况下需要额外的启动时间，因此默认情况下不会这样做。但是，您可以通过运行docker run -e DEV=1来作为上述步骤的快捷方式。

  之后，您可以在另一个终端中创建此容器的快照，例如通过运行docker commit <my-container> dnadna-dev。

依赖关系

• python >= 3.6
• pytorch
• pandas
• numpy
• matplotlib
• msprime
• jsonschema
• pyyaml
• tqdm

（完整列表请参阅setup.cfg或requirements.txt。）

快速入门教程

安装成功后，您应该安装了一个名为dnadna的命令行工具

$ dnadna --help
usage: dnadna [-h] [COMMAND]

dnadna version ... top-level command.

See dnadna <sub-command> --help for help on individual sub-commands.

optional arguments:
  -h, --help       show this help message and exit
  --plugin PLUGIN  load a plugin module; the plugin may be specified either as the file path to a Python module, or the name of a module importable on the current Python module path (i.e. sys.path); plugins are just Python modules which may load arbitrary code (new simulators, loss functions, etc.) during DNADNA startup); --plugin may be passed multiple times to load multiple plugins
  --trace-plugins  enable tracing of plugin loading; for most commands this is enabled by default, but for other commands is disabled to reduce noise; this forces it to be enabled
  -V, --version    show the dnadna version and exit

sub-commands:
  init          Initialize a new model training configuration and directory
                structure.
  preprocess    Prepare a training run from an existing model training
                configuration.
  train         Train a model on a simulation using a specified pre-processed
                training config.
  predict       Make parameter predictions on existing SNP data using an already
                trained model.
  simulation    Run a registered simulation.

这实现了多个不同的子命令，用于不同的训练和模拟步骤。可以使用dnadna命令从现有的模拟数据集开始（可能需要首先将其转换为DNADNA数据集格式），或者您可以使用dnadna的模拟接口创建一个新的模拟数据集。

在这里，我们将完整的过程分步说明，从配置和生成模拟，到在模拟上运行数据预处理，以及根据该模拟训练网络。

如果您已经有了DNADNA数据格式的模拟数据，可以直接跳到初始化步骤。

模拟初始化和配置

要初始化模拟，我们必须首先使用dnadna simulation init命令为它生成一个配置文件和输出文件夹

$ dnadna simulation init my_dataset one_event
Writing sample simulation config to my_dataset/my_dataset_simulation_config.yml ...
Edit the config file as needed, then run this simulation with the command:

    dnadna simulation run my_dataset/my_dataset_simulation_config.yml

这将创建当前目录中的一个目录，命名为my_dataset/，并使用内置的one_event示例模拟器的样本参数预填充配置文件进行初始化。

在运行模拟之前，我们可能需要调整一些参数。在您最喜欢的文本编辑器中打开my_dataset/my_dataset_simulation_config.yml。默认情况下，我们可以看到n_scenarios为100，每个场景有3个n_replicates（在one_event示例中，n_replicates是独立模拟的基因组区域的数量）。您可以将其更改为20个场景，每个场景有2个副本，即总共100次模拟，这对于这个快速演示来说很好，但对于训练真实模型来说太低。对于具有足够计算资源的真实训练，我们建议将这些数字更改为更高的值，如20000和100（2百万次模拟，耗时非常长）。您还可以设置seed选项以随机数生成器的种子，以便得到可重现的结果。结果文件（未更改其他设置）应类似于

# my_dataset/my_dataset_simulation_config.yml
data_root: .
n_scenarios: 20
n_replicates: 2
seed: 2
...

运行模拟

现在要运行我们配置的模拟，我们运行dnadna simulation run，传递我们刚刚编辑的配置文件路径。如果您在终端中运行此命令，它还将显示进度条

$ dnadna simulation run my_dataset/my_dataset_simulation_config.yml
... INFO;  Running one_event simulator with n_scenarios=20 and n_replicates=2
... INFO;  Simulation complete!
... INFO;  Initialize model training with the command:
... INFO;
... INFO;      dnadna init --simulation-config=my_dataset/my_dataset_simulation_config.yml <model-name>

模型初始化

初始化DNADNA的主要命令是 dnadna init，该命令假定我们已经有一个模拟（例如我们刚刚生成的模拟）在标准的 DNADNA 数据格式 中。尽管此命令可以在没有任何参数的情况下运行（生成默认配置文件），但如果我们传递它模拟配置文件的路径，它将输出一个适用于该模拟的配置文件。

$ dnadna init --simulation-config=my_dataset/my_dataset_simulation_config.yml my_model
Writing sample preprocessing config to my_model/my_model_preprocessing_config.yml ...
Edit the dataset and/or preprocessing config files as needed, then run preprocessing with the command:

    dnadna preprocess my_model/my_model_preprocessing_config.yml

运行 dnadna init 后，预计用户将手动编辑它输出的示例配置文件，以精确指定他们想要如何训练他们的模型以及哪些参数。实际上，默认模板对于我们这个演示模拟已经足够好，只有一个地方可能会给我们带来麻烦。

选项 dataset_splits: 的默认值意味着我们的场景中有 70% 用于训练，只有 30% 用于验证。由于在这个快速演示中我们只有 20 个场景，验证集会太小。在你的编辑器中打开文件 my_model/my_model_preprocessing_config.yml，并将其更改为将我们的数据集分成训练集和验证集各 50%。

# my_model/my_model_preprocessing_config.yml
# ...
dataset_splits:
    training: 0.5
    validation: 0.5

在正常使用中，你可以根据喜好设置这些比率。你还可以包括一个 test 集来为测试你的模型留出。

预处理

在训练模型之前，必须在数据集上执行一些数据预处理；此预处理的输出取决于 dnadna init 输出的预处理配置文件中的设置。要执行此操作，只需运行

$ dnadna preprocess my_model/my_model_preprocessing_config.yml
... INFO;  Removing scenarios with:
... INFO;   - Missing replicates
... INFO;   - Fewer than 500 SNPs
... INFO;  ...
... INFO;  Using ... CPU for checking scenarios
... INFO;  20 scenarios out of 20 have been kept, representing 40 simulations
... INFO;  Splitting scenarios between training and validation set
... INFO;  Standardizing continuous parameters
... INFO;  Writing preprocessed scenario parameters to: .../my_model/my_model_preprocessed_params.csv
... INFO;  Writing sample training config to: .../my_model/my_model_training_config.yml
... INFO;  Edit the training config file as needed, then start the training run with the command:
... INFO;
... INFO;      dnadna train .../my_model/my_model_training_config.yml

这将生成一个包含为训练你的模型准备的配置文件的 <model_name>_training_config.yml 文件。

训练

要运行模型训练，预处理后使用 dnadna train，并给出最后一步输出的预处理训练配置文件的路径。

为了使训练运行稍微快一点（仅限这个示例），我们还编辑了训练配置文件，将其限制为一个周期。

# my_model/my_model_training_config.yml
# ...
# name and parameters of the neural net model to train
network:
    name: CustomCNN

# number of epochs over which to repeat the training process
n_epochs: 1
...

然后，在训练配置文件上运行 dnadna train。

$ dnadna train my_model/my_model_training_config.yml
... INFO;  Preparing training run
... INFO;  20 samples in the validation set and 20 in the training set
... INFO;  Start training
... INFO;  Networks states are saved after each validation step
... INFO;  Starting Epoch #1
... INFO;  Validation at epoch: 1 and batch: 1
... INFO;  Compute all outputs for validation dataset...
... INFO;  Done
... INFO;  training loss = 1.0222865343093872 // validation loss = 1.2975229024887085
... INFO;  Better loss found on validation set: None --> 1.2975229024887085
... INFO;  Saving model to ".../my_model/run_000/my_model_run_000_best_net.pth" ...
... INFO;  Compute all outputs for validation dataset...
... INFO;  Done
... INFO;  --- 3.185938596725464 seconds ---
... INFO;  --- Best loss: 3.892427444458008
... INFO;  Saving model to ".../my_model/run_000/my_model_run_000_last_epoch_net.pth" ...
... INFO;  You can test the model's predictions on a test dataset by running the command:
... INFO;
... INFO;      dnadna predict .../my_model/run_000/my_model_run_000_last_epoch_net.pth <dataset config file or paths to .npz files>

默认情况下，这将在 model_name/run_NNN 下输出你的训练运行目录，其中 NNN 是一个整数运行 ID。运行 ID 从 0 开始，默认情况下使用下一个未使用的运行 ID。但是，你也可以传递 --run-id 参数来指定一个自定义运行 ID，它可以是整数，也可以是任意字符串。

成功训练运行后，将在运行目录下输出一个 <model_name>_run_<run_id>_last_epoch_net.pth 文件，其中包含以序列化格式存储的最终训练模型，该格式可以通过 torch.load 函数加载。

在此运行目录下，这还将生成一个包含最终配置文件的 <model_name>_<run_id>_training_config.yml 文件，该配置文件包含用于运行 dnadna train 的 "base" 训练配置的完整副本，以及模拟配置的完整副本。这些信息以完整形式复制，目的是为了训练运行的溯源和可重复性。

预期的是，在多个训练运行之间，你可以修改 "base" 配置来调整训练，无论是直接修改原始配置文件，还是复制它并编辑副本。在任何情况下，用于执行训练运行的最终配置都保存在运行目录中，不应修改。

你可以使用 TensorBoard 跟踪所有训练和验证损失。

预测

给定已经训练好的网络，我们现在可以使用它对新数据集进行（或确认）预测。为了展示，我们将运行 dnadna predict 模型，对用于训练模型的部分现有数据集进行处理，尽管在实践中，它可以运行在符合（例如，在维度上）模型训练数据集的任何数据上。输出是一个包含每个输入参数预测的CSV文件

$ dnadna predict my_model/run_000/my_model_run_000_last_epoch_net.pth \
                 my_dataset/scenario_04/*.npz
path,event_time,recent_size,event_size
.../my_dataset/scenario_04/my_dataset_04_0.npz,-0.06392800807952881,-0.11097482591867447,-0.12720556557178497
.../my_dataset/scenario_04/my_dataset_04_1.npz,-0.06392764300107956,-0.11097370833158493,-0.12720371782779694

数据格式

DNADNA为它工作的数据集指定了文件系统布局和文件格式。此布局的一些细节可以在配置文件中修改，并且在未来的版本中将通过插件进一步自定义。

但是默认格式假设SNP数据（SNP矩阵和相关SNP位置数组）以NumPy的NPZ格式存储，每个SNP一个文件。它们按场景组织在磁盘上，例如

\_ my_simulation/
    \_ my_simulation_params.csv  # the scenario parameters table
    |_ my_simulation_dataset_config.yml  # the simulation config file
    |_ scenario_000/
        \_ my_simulation_000_00.npz  # scenario 0 replicate 0
        ...
        |_ my_simulation_000_NN.npz
    |_ scenario_001/
        \_ my_simulation_001_00.npz  # scenario 1 replicate 0
        ...
        |_ my_simulation_001_NN.npz
    ...
    |_ scenario_NNN/
        \_ my_simulation_NNN_00.npz
        ...
        |_ my_simulation_NNN_NN.npz

文件my_simulation_params.csv包含每个模拟参数的已知目标值，按场景进行。

• 一个scenario_idx列，给出场景编号。
• 一个n_replicates列，指定该场景中的重复次数。
• 一个或多个额外的列，包含任意的参数名称和每个场景在数据集中的值。

例如

scenario_idx,mutation_rate,recombination_rate,event_time,n_replicates
0,1e-08,1e-08,0.3865300203456797,-0.497464473948751,100
1,1e-08,1e-08,0.19344551118300793,0.16419897912977574,100
...

此处名为my_simulation_dataset_config.yml的关联配置文件提供了有关如何将数据集加载到DNADNA软件中的更多详细信息。可以通过运行dnadna init生成示例数据集配置。

有关更多详细信息，请参阅DNADNA数据集格式。

开发

有关如何设置和使用开发环境以及如何为DNADNA做出贡献的完整详细信息，请参阅开发文档。

详细用法

有关完整的使用手册，请参阅DNADNA文档。