@@ -11,7 +11,7 @@ The tool itself is a wrapper around the [`CifCheck`](https://github.com/rcsb/cpp
## How to run the validation tool
This is just a description of the [validation tool](./validate-mmcif-file.py) itself. When running it from inside a container, the command needs to be prefixed with the instructions to start the container. Find information for running the validation Docker container in "[How to run the container](#how-to-run-the-container)".
This is just a description of the [validation tool](./validate-mmcif-file.py) itself. When running it from inside a container, the command needs to be prefixed with the instructions to start the container. Find information for running the validation Docker container in "[How to run the Docker container](#how-to-run-the-docker-container)".
Upon completion, if there hasn't been any error running the command, the validation tool returns a concise report in [JSON](https://www.json.org/json-en.html) format. That output is meant to be input to a website or any kind of nicely formatted report. Output can also be stored as a JSON formatted file. If the tested ModelCIF file is fully compliant with the ModelCIF format, the JSON output has
...
...
@@ -35,9 +35,9 @@ $
### Add dictionary information used for validation 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 features to expect in a ModelCIF file, so it seems like a good idea to keep the version inside the 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 version 1.3, is still valid with dictionary version 1.4. But the version number also tells you which features to expect in 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`).
The validation tool can add the version upon positive validation, enabled by `--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
...
...
@@ -91,9 +91,9 @@ $
**`--help`** (**`-h`**) Print a help/ usage page for the validation tool.
**`--dict-sdb <SDB FILE>`** (**`-d`**) Format dictionary in (binary) SDB format used for validating a ModelCIF file. The container comes with a SDB for ModelCIF (`/usr/local/share/mmcif-dict-suite/mmcif_ma.sdb`) and one for the original PDBx/mmCIF (`/usr/local/share/mmcif-dict-suite/mmcif_pdbx_v50.dic.sdb`) format.
**`--dict-sdb <SDB FILE>`** (**`-d`**) Format dictionary in (binary) SDB format used for validating a ModelCIF file. The Docker container comes with a SDB for ModelCIF (`/usr/local/share/mmcif-dict-suite/mmcif_ma.sdb`) and one for the original PDBx/mmCIF (`/usr/local/share/mmcif-dict-suite/mmcif_pdbx_v50.dic.sdb`) format.
**`--out-file <JSON FILE>`** (**`-o`**) Instead of printing the output to `stdout`, store it in a JSON file.
**`--out-file <JSON FILE>`** (**`-o`**) Instead of printing the output to `stdout`, store it in a JSON formatted file.
**`--verbose`** (**`-v`**) Be more talkative.
...
...
@@ -110,7 +110,7 @@ $
-[`docker run`](https://docs.docker.com/engine/reference/commandline/run/) starts a new Docker container from image `registry.scicore.unibas.ch/schwede/modelcif-converters/mmcif-dict-suite:latest` and executes the `validate-mmcif-file` command inside the container.
-`--rm` makes sure that the container is removed from the system once the job completed.
-`-v` mounts directory `/home/user/models` from the local host computer to `/data` inside the Docker container, otherwise the `validate-mmcif-file` command has no access to local files. This makes the ModelCIF file `/home/user/models/model.cif` available as `/data/model.cif` to commands executed by `docker run`. Keep in mind, `validate-mmcif-file -e` and `validate-mmcif-file -a` also need to refer to `/data` (or any other local directory mounted in the Docker container).
-`-v` mounts directory `/home/user/models` from the local host computer to `/data` inside the Docker container, otherwise the `validate-mmcif-file` command has no access to local files. The bind mount makes the ModelCIF file `/home/user/models/model.cif` available as `/data/model.cif` to commands executed by `docker run`. Keep in mind, `validate-mmcif-file -e` and `validate-mmcif-file -a` also need to refer to `/data` (or any other local directory mounted in the Docker container).
## How to get the Docker container
...
...
@@ -119,12 +119,12 @@ Before running the Docker container, you need a local copy of its image. There a
-`docker run` will pull it automatically upon first call
-[`docker pull`](https://docs.docker.com/engine/reference/commandline/pull/) the Docker image yourself before running it
-[`docker build`](https://docs.docker.com/engine/reference/commandline/build/) the image from scratch
-[`docker build`](https://docs.docker.com/engine/reference/commandline/build/) the Docker image from scratch
### How to pull a copy of the Docker container from our registry
With `docker pull`, the ready-made Docker image can be fetched from our [Docker registry](https://git.scicore.unibas.ch/schwede/modelcif-converters/container_registry/). Two kinds of Docker images available, differentiated by tags. The `latest` tag refers to the Docker image with the most recent ModelCIF dictionary. This should be the default choice. For specific use cases, e.g. debugging, we also provide Docker images for older versions of the ModelCIF dictionary, those are tagged with the version number of the dictionary. The `latest` image is pulled like this:
With `docker pull`, the ready-made Docker image can be fetched from our [Docker registry](https://git.scicore.unibas.ch/schwede/modelcif-converters/container_registry/). Two kinds of Docker images are available, differentiated by tags. The `latest` tag refers to the Docker image with the most recent ModelCIF dictionary. This should be the default choice. For specific use cases, e.g. debugging, we also provide Docker images for older versions of the ModelCIF dictionary, those are tagged with the version number of the dictionary. The `latest` image is pulled like this:
When developing you own tools using the Docker image, there is one [build argument](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) that adds an [editor](https://www.gnu.org/software/emacs/,[Black](https://black.readthedocs.io/en/stable/), [Pylint](https://pylint.org) and [bash](https://tiswww.case.edu/php/chet/bash/bashtop.html) to ease working in interactive sessions inside the Docker container:
When developing you own tools using the Docker image, there is one [build argument](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) that adds an [editor](https://www.gnu.org/software/emacs/), [Black](https://black.readthedocs.io/en/stable/), [Pylint](https://pylint.org) and [bash](https://tiswww.case.edu/php/chet/bash/bashtop.html) to ease working in interactive sessions inside the Docker container:
