terra-notebook-utils

提供与DRS对象、VCF文件和Terra笔记本环境一起工作的Python API和CLI实用工具。

安装

从CLI

pip install terra-notebook-utils

在Jupyter笔记本中（注意ipython魔法"%pip”）

%pip install terra-notebook-utils

升级

保持与最新功能和错误修复同步通常很有用。安装最新版本的terra-notebook-utils取决于您的宿主环境。

从任何Jupyter笔记本，使用以下命令（注意前面的"%"）

%pip install --upgrade --no-cache-dir terra-notebook-utils

在标准Terra笔记本运行时（可在Terra用户界面的终端按钮中使用）的CLI上，使用以下命令

/usr/local/bin/pip install --upgrade --no-cache-dir terra-notebook-utils

请注意，Terra上的所有标准笔记本运行时都基于此Docker镜像。

对于其他环境，通常只需要做以下操作

pip install --upgrade --no-cache-dir terra-notebook-utils

凭证

terra-notebook-utilities的大部分功能都需要通过Google Cloud Platform账户认证访问。当在Terra Google笔记本环境中运行时，凭证已经可用。否则，可以使用以下命令获取Google凭证

gcloud auth application-default login

只有在Terra Azure笔记本环境中使用Azure默认凭证时，terra-notebook-utilities的drs子命令（仅限）才能成功运行。

用法

terra-notebook-utils公开了一个Python API，以及用于在CLI上执行一些功能的包装器。最好使用Python的伟大help函数来探索Python API。例如，将以下命令输入Python解释器或Jupyter笔记本将生成drs模块的帮助和用法。

import terra_notebook_utils as tnu
help(tnu.drs)

同样，可以使用典型的-h参数探索CLI。在bash提示符下尝试以下命令。

# See the command groups available to the CLI
tnu -h

# See the commands available to the vcf group
tnu vcf -h

# Show your available workspace namespaces (also known as Google billing projects)
tnu profile list-workspace-namespaces

# Show version
tnu --version

CLI配置

几个CLI命令针对工作区或需要工作区命名空间。可以使用以下命令配置默认值

tnu config set-workspace my-workspace
tnu config set-workspace-google-project my-workspace-namespace

请注意，工作区命名空间与Google计费项目相同。

或者，可以将工作区和工作区命名空间传递给单独的命令，而不是作为配置默认值的覆盖。有关用法信息，请参阅命令帮助，例如tnu table get --help。

最后，可以使用环境变量WORKSPACE_NAME和GOOGLE_PROJECT指定工作区和工作区命名空间。这些值具有最低优先级。

DRS API和CLI

terra-notebook-utils提供了几个方法和CLI命令，用于处理DRS解析对象。

Python API

返回关于DRS对象的信息

from terra_notebook_utils import drs
drs.info("drs://my-drs-url")

将DRS对象复制到本地文件系统或存储桶

from terra_notebook_utils import drs
drs.copy("drs://my-drs-url", "gs://my-dst-bucket/my-dst-key")
drs.copy("drs://my-drs-url", "local_filepath")
drs.copy_batch(["drs://my-drs-url1", "drs://my-drs-url2"], "local_directory")
drs.copy_batch(["drs://my-drs-url1", "drs://my-drs-url2"], "gs://my-dst-bucket/prefix")

获取DRS对象的头部信息

from terra_notebook_utils import drs
drs.head("drs://my-drs-url", num_bytes=10)

返回访问DRS对象的签名URL

from terra_notebook_utils import drs
drs.access("drs://my-drs-url")

CLI

关于DRS对象的信息

tnu drs info drs://my-drs-url

将DRS对象复制到本地或存储桶

tnu drs copy drs://my-drs-url gs://my-dst-bucket/my-dstkey
tnu drs copy drs://my-drs-url local_filepath
tnu drs copy-batch drs://my-drs-url1 drs://my-drs-url2 --dst local_directory
tnu drs copy-batch drs://my-drs-url1 drs://my-drs-url2 --dst gs://my-dst-bucket/prefix

获取DRS对象的头部信息

tnu drs head drs://my-drs-url --bytes 10

返回访问DRS对象的签名URL

tnu drs access drs://my-drs-url

CLI输出错误消息，而不是堆栈跟踪。可以通过定义环境变量TNU_CLI_DEBUG来获取堆栈跟踪。

VCF API和CLI

terra-notebook-utils提供了一些CLI命令，用于获取关于VCF文件的信息。这些命令适用于存储在本地的VCF、Google Storage存储桶或DRS URL中的VCF。

打印VCF头信息

tnu vcf head drs://my-vcf
tnu vcf head gs://my-vcf
tnu vcf head my.vcf.gz

打印VCF样本

tnu vcf samples drs://my-vcf
tnu vcf samples gs://my-vcf
tnu vcf samples my.vcf.gz

打印VCF统计信息。此命令执行速度快，显示VCF的长度和文件大小。如果VCF已压缩，则返回压缩大小。

tnu vcf stats drs://my-vcf
tnu vcf stats gs://my-vcf
tnu vcf stats my.vcf.gz

尽管目前有用于处理VCF的Python API，但其用法更复杂。有关更多信息，请联系维护者。

本地开发

对于本地开发

1. 请决定您是想在本地环境中运行，还是从Docker镜像中进行开发。推荐从Docker镜像中进行开发，因为这最接近用户使用的方式。另外，在Mac上安装requirements.txt文件有一些问题。如果您不想在Docker镜像中运行，请跳到第5步。
2. 拉取Terra UI当前使用的terra-jupyter-python Docker镜像（请在此处检查版本这里）：docker pull us.gcr.io/broad-dsp-gcr-public/terra-jupyter-python:1.1.5
3. 从该仓库根目录上一级目录运行镜像，使用以下命令：docker run -itd --entrypoint='/bin/bash' -v $PWD/terra-notebook-utils:/work -u root -e PIP_USER=false --name test-image us.gcr.io/broad-dsp-gcr-public/terra-jupyter-python:1.1.5
4. 通过docker exec -it test-image bash将您的终端连接到镜像，然后通过cd /work进入代码挂载的目录。注意，上述命令确保您对仓库中文件的任何更改都会在镜像中更新。
5. 使用gcloud auth application-default login登录您的Google凭据，
6. 使用pip install -r requirements.txt安装依赖
7. 根据您要使用的设置以下环境变量
   • export GOOGLE_PROJECT=[有效项目]
   • export WORKSPACE_NAME=[项目内的工作空间]
   • export TERRA_DEPLOYMENT_ENV=dev
   • export WORKSPACE_BUCKET=[工作空间内的桶]
   • export GCLOUD_PROJECT=[有效的Google项目]（如果您的DRS URI不返回Google SA，则需要设置此变量）

对于Python API

• 通过python运行Python shell，导入您希望使用的任何模块。例如，from terra_notebook_utils import drs

对于CLI

• 运行scripts/tnu <command>，例如scripts/tnu drs copy drs://url/here local_path

测试中使用的示例DRS URL：（您在成功解析之前需要获取对这些URL的访问权限）

• drs://dg.712C/fa640b0e-9779-452f-99a6-16d833d15bd0：非受保护测试DRS URL，解析到开发中的小文件
• drs://jade.datarepo-dev.broadinstitute.org/v1_0c86170e-312d-4b39-a0a4-2a2bfaa24c7a_c0e40912-8b14-43f6-9a2f-b278144d0060：Jade Dev测试URL 确保您为每个DRS URL设置了第7步中提到的正确环境变量

测试

要运行测试，按照本地开发设置到第4步。确保您的帐户可以访问工作空间terra-notebook-utils-tests

1. 使用pip install -r requirements-dev.txt安装依赖
2. 设置export WORKSPACE_NAME=terra-notebook-utils-tests

测试环境：开发（目前它包含对DRS方法的测试）

这将使用Jade Dev DRS URL针对Terra和DRSHub Dev运行测试（确保您的Terra Dev帐户可以访问上述URL）

3. 使用您的Terra Dev帐户通过gcloud auth application-default login登录Google凭据
4. 设置
   • export GOOGLE_PROJECT=[将被计费的Google项目]
   • export TERRA_DEPLOYMENT_ENV=dev
   • export WORKSPACE_BUCKET=[工作空间内的桶]（或您想要通过DRS URL解析的数据的桶）
5. 在包根目录下运行
   • make dev_env_access_test：运行标记为dev_env_access的测试

测试环境：生产

这将针对Terra和DRSHub Prod运行测试（确保您有权访问DRS URL、工作空间和Google桶）

3. 使用您的Terra Prod帐户通过gcloud auth application-default login登录Google凭据
4. 设置export GOOGLE_PROJECT=firecloud-cgl; export TERRA_DEPLOYMENT_ENV=prod; export TNU_BLOBSTORE_TEST_GS_BUCKET=tnu-test-bucket
5. 在包根目录下运行
   • make test：跳过受控和开发访问测试
   • make controlled_access_test：运行标记为controlled_access的测试
   • make all_test：运行所有生产测试（受控访问和工作空间访问）

发布

common.mk文件中提到的命令用于发布过程。步骤

• 如果您没有PyPI帐户，请创建一个
• 您应该在 PyPI 上成为 Terra Notebook Utils 的协作者。如果您还不是，请向 Lon Blauvelt (lblauvel at ucsc dot edu) 请求添加您为协作者。
• 按照上述 Tests 部分中提到的设置说明进行操作，针对环境 Prod；确保您有权访问 DRS 网址、工作空间和存储桶。
• 从 Local Development 部分创建的 Docker 容器内运行 make all_test。一旦测试通过，您可以进入发布步骤。
• 发布
  • 对于非破坏性 API 变更，使用 make release_patch。
  • 对于破坏性 API 变更，使用 make release_minor。
  • 对于重大版本发布，使用 make release_major。

如果出于某种原因需要回滚发布，请联系 Lon Blauvelt (lblauvel at ucsc dot edu) 寻求帮助。

链接

项目主页 GitHub 软件包分发 PyPI

错误

请在 GitHub 上报告错误、问题、功能请求等。