From 745c7aaf68b3ff8919814e3f679a69de7cace6f6 Mon Sep 17 00:00:00 2001
From: Bienchen <stefan.bienert@unibas.ch>
Date: Fri, 6 May 2022 14:51:16 +0000
Subject: [PATCH] Update validation/README.md
---
validation/README.md | 22 +++++++++++++++++++++-
1 file changed, 21 insertions(+), 1 deletion(-)
diff --git a/validation/README.md b/validation/README.md
index 2cfa38d..dd90af2 100644
--- a/validation/README.md
+++ b/validation/README.md
@@ -16,7 +16,7 @@ Upon completion, if there hasn't been any error running the command, the validat
- `status` "completed"
- no messages in the `diagnosis` list
-- `version` of the dictionaries the file was tested against
+- `versions` of the dictionaries the file was tested against
Format violations will be listed in `diagnosis`.
@@ -30,7 +30,27 @@ $
### Add validation dictionary to ModelCIF file
+Since both dictionaries, ModelCIF and PDBx/mmCIF, represent actively developed file formats, different versions exist. While extending them, quite some thinking goes into making only non-breaking changes. The idea is that a ModelCIF file formatted following dictionary 1.3, is still valid with version 1.4. But the version number also tells you which feature to expect from a ModelCIF file, so it seems like a good idea to keep the version inside the file.
+The validation tool can add the version upon positive validation, enabled by the `--extend-validated-file` (`-e`).
+
+`-e` can take an alternative file name to write the validated ModelCIF file to, e.g. if one wants to keep the original ModelCIF file unaltered:
+```bash
+$ validate-mmcif-file -e validated_model.cif model.cif
+{"status":"completed","diagnosis":[],"versions":[{"title":"mmcif_pdbx_v50.dic","version":"5.358","location":"https://raw.githubusercontent.com/ihmwg/ModelCIF/a24fcfa8d6c3ceb4b6f0676bcc341ac0cd24ff1f/base/mmcif_pdbx_v50.dic"},{"title":"mmcif_ma.dic","version":"1.4.0","location":"https://raw.githubusercontent.com/ihmwg/ModelCIF/a24fcfa8d6c3ceb4b6f0676bcc341ac0cd24ff1f/dist/mmcif_ma.dic"}]}
+$
+```
+The last command will generate a new file `validated_model.cf` upon positive validation (`diagnosis` points to an empty list), with the `versions` added to the `_audit_conform` list inside the file.
+
+To add the validation dictionaries to `_audit_conform` in the original ModelCIF file, just invoke `-e` without an alternative file name... well almost. By the way Python handles this kind of command line arguments, `-e` consumes everything after it, that does not start with a `-`, as a file name. So `validate-mmcif-file -e model.cif` would mean that `-e` assumes `model.cif` as its file name but then the command fails because it is missing the ModelCIF file to be validated. The solution is either putting `-e` at the beginning of the arguments list or after the ModelCIF file name at the very end, if there are no other command line arguments:
+
+```bash
+$ validate-mmcif-file model.cif -e
+{"status":"completed","diagnosis":[],"versions":[{"title":"mmcif_pdbx_v50.dic","version":"5.358","location":"https://raw.githubusercontent.com/ihmwg/ModelCIF/a24fcfa8d6c3ceb4b6f0676bcc341ac0cd24ff1f/base/mmcif_pdbx_v50.dic"},{"title":"mmcif_ma.dic","version":"1.4.0","location":"https://raw.githubusercontent.com/ihmwg/ModelCIF/a24fcfa8d6c3ceb4b6f0676bcc341ac0cd24ff1f/dist/mmcif_ma.dic"}]}
+$
+```
+
+### Associated files...
- basic usage
- add version of dict validated against
--
GitLab