lims2-sdk 0.9.0

生信云平台 Python SDK，提供图表上传和文件存储功能

Lims2 SDK

生信云平台 Python SDK，提供图表上传和文件存储功能。

安装与配置

pip install -U lims2-sdk

设置环境变量：

export LIMS2_API_URL="your-api"
export LIMS2_API_TOKEN="your-api-token"

命令行使用

完整命令树和参数通过 --help 查看：

lims2 --help                          # 查看所有子命令
lims2 chart upload --help             # 查看图表上传所有参数
lims2 storage upload --help           # 查看文件上传所有参数
lims2 storage upload-dir --help       # 查看目录上传所有参数
lims2 storage info --help             # 查看文件信息查询参数

图表上传

参数说明（lims2 chart upload --help）：

Usage: lims2 chart upload [OPTIONS] [FILE_PATH]

  上传图表文件。FILE_PATH 为图表 JSON 文件路径；传 `-` 表示从标准输入读取。

Options:
  -p, --project-id TEXT      项目 ID  [required]
  -n, --name TEXT            图表名称（默认使用文件名）
  -s, --sample-id TEXT       样本 ID
  -t, --chart-type TEXT      图表类型（示例模式下必填）
  -d, --description TEXT     图表描述
  -c, --contrast TEXT        对比策略
  -a, --analysis-node TEXT   分析节点名称
  --precision INTEGER RANGE  浮点数精度（小数位数，0-10，默认 3）
  --retry INTEGER RANGE      网络重试次数（1-10，默认从配置读取）
  --timeout INTEGER          超时时间（秒，默认从配置读取）
  --example                  上传为示例数据（不会被自动删除）
  --data-file PATH           关联的数据文件路径（可多次指定挂载多个文件）
  --thumbnail PATH           用户指定的缩略图文件（png/jpg/jpeg/webp/svg），指定后跳过自动生成
  --help                     显示帮助信息

示例：

# 基本用法
lims2 chart upload plot.json -p proj_001 -n "基因表达分析" -t heatmap

# 完整参数
lims2 chart upload plot.json -p proj_001 -n "基因表达分析" \
  -s sample_001 -t heatmap -d "差异表达热图" \
  -c A_vs_B -a Expression_statistics --precision 3

# 上传示例图表（不会被自动清理，chart_type 必填，可附带数据文件）
lims2 chart upload plot.json -p proj_001 -n "示例散点图" \
  -t scatter --example --data-file data.xlsx

# 一次挂载多个数据文件（每个 --data-file 一个，name 自动取文件 stem）
lims2 chart upload plot.json -p proj_001 -n "热图" -t heatmap \
  --data-file matrix.csv --data-file groups.tsv --data-file metadata.json

# 显式指定缩略图（跳过 kaleido 自动生成，适合无法跑 Chrome 的环境）
lims2 chart upload plot.json -p proj_001 -n "热图" \
  -t heatmap --thumbnail thumb.png

# 管道输入
echo '{"data": [...], "layout": {...}}' | lims2 chart upload - -p proj_001 -n "管道图表"

chart_type 说明

-t, --chart-type / chart_type= 是图表类型标识。SDK 不做枚举校验，传入字符串原样发送给后端：

• 普通模式下可选
• --example 模式下必填（缺失会在客户端抛 ValueError）

下表是和前端展示组件对应的建议命名，能用 Plotly 原生类型时优先使用。

Plotly 原生（推荐）：

chart_type	中文名
scatter	散点图
bar	柱形图
line	折线图
box	箱线图
violin	小提琴图
heatmap	热力图
pie	饼图
funnel	漏斗图
sankey	桑基图
treemap	矩形树图
sunburst	旭日图

业务扩展类型：

chart_type	中文名	备注
radar	雷达图
tree	树图
chord	和弦图
venn	韦恩图
graph	关系图
special	特殊类	静态图片，如 KEGG Pathway
combination	组合图	如 GSEA

文件存储

# 上传文件
lims2 storage upload results.csv -p proj_001
lims2 storage upload results.csv -p proj_001 --base-path analysis --progress

# 上传目录（递归）
lims2 storage upload-dir output/ -p proj_001
lims2 storage upload-dir output/ -p proj_001 --base-path analysis

# 查询文件
lims2 storage info biofile/.../file.txt -p proj_001
lims2 storage exists biofile/.../file.txt -p proj_001

Python SDK 使用

多个图表上传推荐复用客户端实例，共享连接池：

from lims2 import Lims2Client

client = Lims2Client()

for chart_file in ["plot1.json", "plot2.json", "plot3.json"]:
    client.chart.upload(
        data_source=chart_file,
        project_id="proj_001",
        chart_name=f"图表_{chart_file}",
        analysis_node="Expression_statistics",
        precision=3,
    )

完整参数示例

# 图表上传
client.chart.upload(
    data_source="plot.json",        # 图表数据：字典、文件路径或 Path 对象
    project_id="proj_001",          # 项目 ID（必需）
    chart_name="基因表达分析",        # 图表名称（必需）
    sample_id="sample_001",         # 样本 ID（可选）
    chart_type="heatmap",           # 图表类型（示例模式下必填）
    description="差异表达基因热图",
    contrast="A_vs_B",
    analysis_node="Expression_statistics",
    precision=3,                    # 浮点数精度 0-10（默认 3）
    generate_thumbnail=True,        # 是否自动生成缩略图
    thumbnail_path="thumb.png",     # 显式缩略图，跳过自动生成（png/jpg/jpeg/webp/svg）
    file_name="gene_expression",    # 自定义文件名
    example=True,                   # 上传为示例数据（不会被自动清理）
    data_files=[                    # 关联数据文件列表
        "matrix.csv",                #   纯路径：name 自动取 stem -> "matrix"
        {"path": "groups.tsv",       #   dict 形式可自定义 name / label
         "name": "groups",
         "label": "样本分组"},
    ],
)

# 文件存储
client.storage.upload_file("results.csv", "proj_001")
client.storage.upload_file("results.csv", "proj_001", base_path="analysis")
client.storage.upload_directory("output/", "proj_001")

支持的数据格式

图表：

• Plotly: 含 data / layout 字段的字典（自动生成缩略图）
• Cytoscape: 含 elements 或 nodes+edges 的字典（使用预设缩略图）
• 图片/文档: PNG, JPG, SVG, PDF, HTML

缩略图策略（按优先级）：

1. 显式 --thumbnail / thumbnail_path= → 直接上传指定文件
2. generate_thumbnail=False → 不生成
3. 否则按图表类型自动生成（Plotly 用 kaleido 渲染，Cytoscape 用预设图）

kaleido 1.x 需要系统装新版 Chrome；老系统（如 CentOS 7 glibc 2.17）建议 pip install "kaleido==0.2.1" 用自带 Chromium，或直接用 --thumbnail 跳过自动生成。

文件存储：任意格式，大文件（>10MB）自动断点续传。

可选环境变量

# 网络
export LIMS2_CONNECTION_TIMEOUT=30
export LIMS2_READ_TIMEOUT=300
export LIMS2_MAX_RETRIES=3

# 缩略图
export LIMS2_THUMBNAIL_WIDTH=800
export LIMS2_THUMBNAIL_HEIGHT=600
export LIMS2_THUMBNAIL_FORMAT=webp

# 日志（CLI 默认 INFO）
export LIMS2_LOG_LEVEL=DEBUG

许可证

MIT License