Metadata-Version: 2.1
Name: gparams
Version: 1.0.1
Summary: A kit to process the parameters of the GeneDock workflow (help for batch delivery).
Home-page: https://www.genedock.com
Author: Rao Mengnan
Author-email: raomengnan@genedock.com
Maintainer: GeneDock Contributor
Maintainer-email: raomengnan@genedock.com
License: UNKNOWN
Platform: Independent
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Intended Audience :: Customer Service
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Description-Content-Type: text/markdown
Requires-Dist: PyYAML (==3.13)
Requires-Dist: Jinja2 (==2.10)

# 模板文件说明

使用`ini`配置文件维护`yml`中各个位置的变量值有以下优点：

1. 将嵌套的结构转换为扁平的结构，降低管理和维护的难度
2. 将无序的结构转为有序的结构，版本变更时更容易检查不同之处
3. 空的参数模板文件（yml）中许多默认值无需指定，使用ini配置只需关注需要改变的值
4. 解耦工作流版本、工作流模板版本、参数渲染模块
5. 配合jinja模板 + gdmetro指定的ini配置模板规则，可以动态生成不同的值，使参数文件渲染与工作流版本更新解耦


## 参数声明

在ini文件中，使用`[DECLARE]` section 声明变量，以BGI_WGS的参数为例：

```ini
[DECLARE]
project_id = {{project_id}}
subproject_id = {{subproject_id}}
sample_id = {{sample_id}}
cloud_out_dir ={{cloud_out_dir}}
lane_id_list = {{lane_id_list}}
reference_buildversion = {{reference_buildversion}}
date = {{date}}
task_name = {{task_name}}
```

按照jinja模板的规则，以`{{}}`两对花括号包裹的为变量，gdmetro会去出花括号中的变量名，并在渲染时传入声明的参数。

（**注意，等号左边是用于渲染ini文件时检查参渲染结果的，不会参与参数值的替换操作**）
***在DECLARE组中，只能出现变量的声明和以`;`开头的注释，不能出现其他的键值***

## 定义宏

所有的宏定义应该在 `[MACROS]`中，宏定义用于动态生成一些值，比如生成loadbam的参数列表、
根据reference_buildversion生成chrN、生成参考基因组名称等。

以下是用于动态生成`loadbam<?>`的实例，``：

1. （声明）通过lane_id生成item实体
```
{%macro _loadbamData(lane_id, prefix, pos) -%}
{"enid": null, "name": "{{cloud_out_dir}}/tmp/fq_bam/{{sample_id}}/{{lane_id}}/{{lane_id}}.{{prefix}}{{pos}}.bam", "property": {"block_file": {"block_name": null, "is_block": false, "split_format": "default"}} }
{%- endmacro %}
```
2. （声明）根据坐标生成loadnode_bam<pos>的值，比如loadnode_bamY
```
{% macro loadbamList(prefix, pos) -%}
[{%for lane_id in lane_id_list -%}
{{_loadbamData(lane_id, prefix, pos)}} {%-if not loop.last%}, {%endif-%}
{%-endfor%}]
{%- endmacro%}
```

3. （应用）动态生成 loaddata_node_bam1 到 loaddata_node_bam22 
```
{%-for index in range(1, 23) -%}
loaddata_node_bam{{index}}.data = {{ loadbamList('bam', index)}}
{%endfor-%}
```

更多jinja模板的语法请参考[文档](http://docs.jinkan.org/docs/jinja2/templates.html#if)

## 参数映射

为了将json/yml的多维结构转为二维结构，我使用 `.`作为分割符号，将每一级别的名称连接起来，用于唯一标识一个子属性（类似MongoDB），
对于数组，同样模仿MongoDB，使用 `$`指定第几个元素，程序解析时碰到了`$`符，则认为用户指定了一个数组中第n个元素的值：

例如配置中的一条项目：`loaddata_cnv_head.data.$0.name = 1`，在解析时转回多维结构如下：
```yaml
loaddata_cnv_head:
    data: [{"name": 1}]

```

为了便于管理，我根据参数文件的结构 `Inputs`, `Outputs`, `Parameters`以及顶级属性做了分组处理，yml的结构如下：

```yaml
name: 

Inputs:
    xxx:

Outputs:
    xxx:

Parameters:
    xxx:

```
对应到ini配置文件中的四个分组如下：

```ini
[!DIRECT]
name = ???

[Inputs]

[Outputs]

[Parameters]

```
程序会严格按照分组来读取不同的值填充到空的yml文件中，所以指定变量时需要按照分组填入。
为了方便处理，gdmetro中添加了一个命令行工具，可以提取yml文件中`Inputs`, `Outputs`, `Parameters`的主要变量，其中
包含以下格式：

1. Inputs/Outputs: `...data.$0.name`
2. Parameters: `...value`

命令行使用：
```shell
gvariables load -y <yml文件，支持旧版的占位符参数导出> [-i <忽略的参数（后缀）列表，以空格隔开，比如loadbam等通过宏生成的就不需导出>]
```

`gvariables`同时也支持对ini配置的检查：

```shell
gvariables detection -f <ini文件路径> -v '
{
    "参数名": 参数值
}
'
```



