Skip to content

Commit

Permalink
Refactor config docs according to comments
Browse files Browse the repository at this point in the history
  • Loading branch information
jbwang1997 committed Jan 30, 2023
1 parent 6029a5d commit 8b89757
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 5 deletions.
28 changes: 25 additions & 3 deletions docs/en/advanced_tutorials/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -528,13 +528,35 @@ Config (path: replace_data_root.py): {'dataset_type': 'CocoDataset', 'data_root'

The value of `data_root` has been substituted with the value of `DATASET` as `/new/dataset/path`.

```note
Environment variable substitution occurs before the configuration parsing. If the replaced field is also involved in other fields assignment, the environment variable substitution will also affect the other fields. In the above example, dataset.ann_file = data_root + 'train.json', so when data_root is replaced, dataset.ann_file will also be changed. Meanwhile, --cfg-options replace a field after the configuration file is parsed. --cfg-options data_root='/new/dataset/path/' does not affect dataset.ann_file
It is noteworthy that both `--cfg-options` and `{{$ENV_VAR:DEF_VAL}}` allow users modified fields in command line. But there is a small difference between those two methods. Environment variable substitution occurs before the configuration parsing. If the replaced field is also involved in other fields assignment, the environment variable substitution will also affect the other fields.

We take `demo_train.py` and `replace_data_root.py` for example. If we replace `data_root` by setting `--cfg-options data_root='/new/dataset/path'`:

```bash
python demo_train.py replace_data_root.py --cfg-options data_root='/new/dataset/path/'
```

```
Config (path: replace_data_root.py): {'dataset_type': 'CocoDataset', 'data_root': '/new/dataset/path/', 'dataset': {'ann_file': '/data/coco/train.json'}}
```

As we can see, only `data_root` has been modified. `dataset.ann_file` is still the default value.

In contrast, if we replace `data_root` by setting `DATASET=/new/dataset/path`:

```bash
DATASET=/new/dataset/path/ python demo_train.py replace_data_root.py
```

```
Config (path: replace_data_root.py): {'dataset_type': 'CocoDataset', 'data_root': '/new/dataset/path/', 'dataset': {'ann_file': '/new/dataset/path/train.json'}}
```

Both `data_root` and `dataset.ann_file` have been modified.

Environment variables can also be used to replace other types of fields. We can use `{{'$ENV_VAR:DEF_VAL'}}` or `{{"$ENV_VAR:DEF_VAL"}}` format to ensure the configuration file conforms to python syntax.

We can task `replace_num_classes.py` as an example:
We can take `replace_num_classes.py` as an example:

```
model=dict(
Expand Down
26 changes: 24 additions & 2 deletions docs/zh_cn/advanced_tutorials/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -528,9 +528,31 @@ Config (path: replace_data_root.py): {'dataset_type': 'CocoDataset', 'data_root'

`data_root` 被替换成了环境变量 `DATASET` 的值 `/new/dataset/path/`

```note
环境变量的替换发生在配置文件解析之前。如果该配置还参与到其他配置的定义时,环境变量替换也会影响到其他配置。在上例中 dataset.ann_file 等于 data_root + 'train.json', 因此当 data_root 被替换时,dataset.ann_file 也会发生变化。而 --cfg-options 是在配置文件解析后去替换特定配置。--cfg-options data_root='/new/dataset/path/' 不会影响到 dataset.ann_file
值得注意的是,`--cfg-options``{{$ENV_VAR:DEF_VAL}}` 都可以在命令行改变配置文件的值,但他们还有一些区别。环境变量的替换发生在配置文件解析之前。如果该配置还参与到其他配置的定义时,环境变量替换也会影响到其他配置,而 `--cfg-options` 只会改变要修改的配置文件的值。

我们以 `demo_train.py``replace_data_root.py` 为例。 如果我们通过配置 `--cfg-options data_root='/new/dataset/path'` 来修改 `data_root`

```bash
python demo_train.py replace_data_root.py --cfg-options data_root='/new/dataset/path/'
```

```
Config (path: replace_data_root.py): {'dataset_type': 'CocoDataset', 'data_root': '/new/dataset/path/', 'dataset': {'ann_file': '/data/coco/train.json'}}
```

从输出结果上看,只有 `data_root` 被修改为新的值。`dataset.ann_file` 依然保持原始值。

作为对比,如果我们通过配置 `DATASET=/new/dataset/path` 来修改 `data_root`:

```bash
DATASET=/new/dataset/path/ python demo_train.py replace_data_root.py
```

```
Config (path: replace_data_root.py): {'dataset_type': 'CocoDataset', 'data_root': '/new/dataset/path/', 'dataset': {'ann_file': '/new/dataset/path/train.json'}}
```

`data_root``dataset.ann_file` 同时被修改了。

环境变量也可以用来替换字符串以外的配置,这时可以使用 `{{'$ENV_VAR:DEF_VAL'}}` 或者 `{{"$ENV_VAR:DEF_VAL"}}` 格式。`''``""` 用来保证配置文件合乎 python 语法。

Expand Down

0 comments on commit 8b89757

Please sign in to comment.