# Lims2 SDK

[![Version](https://img.shields.io/badge/version-0.8.0-blue.svg)](https://github.com/huangzhibo/lims2-sdk)
[![Python](https://img.shields.io/badge/python-≥3.9-green.svg)](https://www.python.org/)

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

## 安装配置

```bash
pip install -U lims2-sdk
```

设置环境变量：

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

## 命令行使用

### 图表上传

```bash
# 基本用法
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

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

### 文件存储

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

# 上传目录
lims2 storage upload-dir output/ -p proj_001
lims2 storage upload-dir output/ -p proj_001 --base-path analysis
```

## Python SDK 使用

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

```python
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,
    )
```

### 完整参数示例

```python
# 图表上传（完整参数）
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,        # 是否生成缩略图（默认True）
    file_name="gene_expression",    # 自定义文件名（可选）
    example=True,                   # 上传为示例数据（可选）
    data_file="data.xlsx",          # 关联数据文件，上传到同目录（可选）
)

# 文件存储
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

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

## 环境配置

```bash
# 必需
export LIMS2_API_URL="你的API地址"
export LIMS2_API_TOKEN="你的API Token"

# 网络（可选）
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
