|
1 | | -[](https://www.codefactor.io/repository/github/pdbeurope/ccdutils/overview/master)     |
| 1 | +[](https://www.codefactor.io/repository/github/PDBeurope/ccdutils/overview/master)      |
| 2 | + |
2 | 3 |
|
3 | 4 | # pdbeccdutils |
4 | 5 |
|
5 | | -* A set of python tools to deal with PDB chemical components definitions |
6 | | - for small molecules, taken from the [wwPDB Chemical Component Dictionary](https://www.wwpdb.org/data/ccd) and [wwPDB The Biologically Interesting Molecule Reference Dictionary](https://www.wwpdb.org/data/bird) |
| 6 | +An RDKit-based python toolkit for parsing and processing small molecule definitions in [wwPDB Chemical Component Dictionary](https://www.wwpdb.org/data/ccd) and [wwPDB The Biologically Interesting Molecule Reference Dictionary](https://www.wwpdb.org/data/bird).`pdbeccdutils` provides streamlined access to all metadata of small molecules in the PDB and offers a set of convenient methods to compute various properties of small molecules using RDKIt such as 2D depictions, 3D conformers, physicochemical properties, matching common fragments and scaffolds, mapping to small-molecule databases using UniChem. |
| 7 | + |
| 8 | +## Features |
7 | 9 |
|
8 | | -* The tools use: |
9 | | - * [RDKit](http://www.rdkit.org/) for chemistry. Presently tested with `2022.09.4` |
| 10 | +* `gemmi` CCD read/write. |
| 11 | +* Generation of 2D depictions (`No image available` generated if the flattening cannot be done) along with the quality check. |
| 12 | +* Generation of 3D conformations. |
| 13 | +* Fragment library search (PDBe hand-curated library, ENAMINE, DSI). |
| 14 | +* Chemical scaffolds (Murcko scaffold, Murcko general, BRICS). |
| 15 | +* Lightweight implementation of [parity method](https://doi.org/10.1016/j.str.2018.02.009) by Jon Tyzack. |
| 16 | +* RDKit molecular properties per component. |
| 17 | +* UniChem mapping. |
| 18 | +* Generating complete representation of multiple [Covalently Linked Components (CLC)](https://www.ebi.ac.uk/pdbe/news/introducing-covalently-linked-components) |
| 19 | + |
| 20 | +## Dependencies |
| 21 | + |
| 22 | + * [RDKit](http://www.rdkit.org/) for small molecule representation. Presently tested with `2023.9.6` |
10 | 23 | * [GEMMI](https://gemmi.readthedocs.io/en/latest/index.html) for parsing mmCIF files. |
11 | 24 | * [scipy](https://www.scipy.org/) for depiction quality check. |
12 | 25 | * [numpy](https://www.numpy.org/) for molecular scaling. |
13 | 26 | * [networkx](https://networkx.org/) for bound-molecules. |
14 | 27 |
|
15 | | -* Please note that the project is under active development. |
16 | 28 |
|
17 | | -## Installation instructions |
| 29 | +## Installation |
18 | 30 |
|
19 | | -* `pdbeccdutils` requires RDKit to be installed. |
20 | | - The official RDKit documentation has [installation instructions for a variety of platforms](http://www.rdkit.org/docs/Install.html). |
21 | | - For Linux/macOS this is most easily done using the Anaconda Python with commands similar to: |
| 31 | +create a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#create-and-use-virtual-environments) and install using pip |
22 | 32 |
|
23 | | - ```console |
24 | | - conda create -n rdkit-env rdkit python=3.9 |
25 | | - conda activate rdkit-env |
26 | | - ``` |
27 | | - |
28 | | -* Once you have installed RDKit, as described above then install `pdbeccdutils` using `pip`: |
29 | | - |
30 | | - ```console |
| 33 | + ```bash |
31 | 34 | pip install pdbeccdutils |
32 | 35 | ``` |
33 | 36 |
|
34 | | -## Features |
| 37 | +## Contribution |
| 38 | +We encourage you to contribute to this project. The package uses [poetry](https://python-poetry.org/) for packaging and dependency management. You can develop locally using: |
35 | 39 |
|
36 | | -* `gemmi` CCD read/write. |
37 | | -* Generation of 2D depictions (`No image available` generated if the flattening cannot be done) along with the quality check. |
38 | | -* Generation of 3D conformations. |
39 | | -* Fragment library search (PDBe hand-curated library, ENAMINE, DSI). |
40 | | -* Chemical scaffolds (Murcko scaffold, Murcko general, BRICS). |
41 | | -* Lightweight implementation of [parity method](https://doi.org/10.1016/j.str.2018.02.009) by Jon Tyzack. |
42 | | -* RDKit molecular properties per component. |
43 | | -* UniChem mapping. |
| 40 | +```bash |
| 41 | +git clone https://github.com/PDBeurope/ccdutils.git |
| 42 | +cd ccdutils |
| 43 | +pip install poetry |
| 44 | +poetry install --with tests,docs |
| 45 | +pre-commit install |
| 46 | +``` |
44 | 47 |
|
45 | | -## TODO list |
| 48 | +The pre-commit hook will run linting, formatting and update `poetry.lock`. The `poetry.lock` file will lock all dependencies and ensure that they match pyproject.toml versions. |
46 | 49 |
|
47 | | -* Add more unit/regression tests to get higher code coverage. |
48 | | -* Further improvements of the documentation. |
| 50 | +To add a new dependency |
49 | 51 |
|
| 52 | +```bash |
| 53 | +# Latest resolvable version |
| 54 | +poetry add <package> |
50 | 55 |
|
51 | | -## Documentation |
| 56 | +# Optionally fix a version |
| 57 | +poetry add <package>@<version> |
| 58 | +``` |
| 59 | + |
| 60 | +To change a version of a dependency, either edit pyproject.toml and run: |
52 | 61 |
|
53 | | -The documentation depends on the following packages: |
| 62 | +```bash |
| 63 | +poetry sync --with dev |
| 64 | +``` |
54 | 65 |
|
55 | | -* `sphinx` |
56 | | -* `sphinx_rtd_theme` |
57 | | -* `myst-parser` |
58 | | -* `sphinx-autodoc-typehints` |
| 66 | +or |
59 | 67 |
|
60 | | -Note that `sphinx` needs to be a part of the virtual environment, if you want to generate documentation by yourself. |
61 | | -Otherwise it cannot pick `rdkit` module. `sphinx_rtd_theme` is a theme providing nice `ReadtheDocs` mobile friendly style. |
| 68 | +```bash |
| 69 | +poetry add <package>@<version> |
| 70 | +``` |
62 | 71 |
|
63 | | -* Generate *.rst* files to be included as a part of the documentation. Inside the directory `pdbeccdutils/doc` run the following commands to generate documentation. |
64 | | -* Alternatively, use the `myst-parser` package to get the Markdown working. |
65 | 72 |
|
66 | | - Use the following to generate initial markup files to be used by sphinx. This needs to be used when adding another sub-packages. |
| 73 | +## Documentation |
67 | 74 |
|
68 | | -```console |
69 | | -sphinx-apidoc -f -o /path/to/output/dir ../pdbeccdutils/ |
70 | | -``` |
| 75 | +The documentation is generated using `sphinx` in `sphinx_rtd_theme` and hosted on GitHub Pages. To generate the documentation locally, |
71 | 76 |
|
72 | | -Use this to re-generate the documentation from the doc/ directory: |
| 77 | +```bash |
| 78 | +cd doc |
| 79 | +poetry run sphinx-build -b html . _build/html |
73 | 80 |
|
74 | | -```console |
75 | | -make html |
| 81 | +# See the documentation at http://localhost:8080. |
| 82 | +python -m http.server 8080 -d _build/html |
76 | 83 | ``` |
0 commit comments