mmcif-tools 0.1.1__tar.gz

mmcif_tools-0.1.1/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to mmcif-tools. Versions follow [semantic versioning](https://semver.org/); before 1.0,
+command names and options may still change.
+
+## 0.1.1 (2026-10-29): on PyPI
+
+No changes to the tools.
+
+- **On PyPI:** `python -m pip install mmcif-tools`. Releases are built, checked and uploaded by
+  `.github/workflows/release.yml`, with PyPI's Trusted Publishing.
+- **Documentation website:** <https://matteo-cagiada.github.io/mmcif-tools/>, made from the README, the help texts
+  and this changelog.
+- The README installs from PyPI first, and its links are full URLs, so they also work on PyPI.
+
+## 0.1.0 (2026-10-28): first test release
+
+The first version for testers. It is not on PyPI or conda-forge yet; install it from the repository.
+
+- **53 command-line tools** (`mmcif_*`), in seven groups: fetch and convert, select and delete, edit,
+  identifiers, models/files/assemblies, categories and data blocks, inspect and format. See
+  [docs/tools.md](docs/tools.md).
+- **mmCIF-specific tools:**
+  - `mmcif_selentity` / `mmcif_delentity`: select by entity number or type (polymer, non-polymer, branched,
+    macrolide, water). Modified residues stay with their chain.
+  - `mmcif_assembly`: build a biological assembly from `_pdbx_struct_oper_list` and
+    `_pdbx_struct_assembly_gen`, including product expressions such as `(1-60)(61-88)`. The chain names follow
+    the RCSB's assembly files.
+  - `mmcif_info`: title, method, resolution, R-factors, dates, organisms, model quality, entities, assemblies.
+  - `mmcif_label2auth` / `mmcif_auth2label`: copy one identifier scheme onto the other.
+  - `mmcif_cat`, `mmcif_delcat`, `mmcif_keepcat`, `mmcif_blocks`: work on categories and data blocks.
+- **Tools inspired by pdb-tools**, with the same options where they apply. Author identifiers by default,
+  `--label` for the PDB's label identifiers.
+- **A streaming mmCIF reader and writer** (standard library only). Rows a tool does not change are copied
+  byte-for-byte. `_atom_site_anisotrop` and `_struct_conn` follow edits to the atoms.
+- **Tested** on hand-written fixtures and 12 real entries (X-ray, NMR, cryo-EM, ribosomes, an AlphaFold DB model),
+  with a cross-check against pdb-tools. Every tool's output on these entries was also checked against the
+  PDBx/mmCIF (or ModelCIF) dictionary with gemmi, and has no error that its input does not have
+  (outside the test suite).
+- **Python 3.9 to 3.15**, on Linux, macOS and Windows.
+- **Fixed after a 200-system stress test** (PDB entries of every method and size, AlphaFold DB models, PDBe
+  files, an integrative model):
+  - `mmcif_splitchain`: chains whose ids differ only in case (`A` and `a`) overwrote each other's files on macOS
+    and Windows; such files now get a number (`1abc_a~2.cif`). It also writes up to 100 chains per reading of
+    the input instead of one, with the same output: 1792 chains no longer take hours.
+  - `mmcif_fixinsert` / `mmcif_delinsertion`: a file without an insertion code column is written unchanged
+    (it was an error).
+  - `mmcif_label2auth`: adds `auth_asym_id` / `auth_seq_id` when a file lacks them (integrative models).
+  - `mmcif_tofasta -seqres`: reads `_entity_poly_seq` when a file has no `_pdbx_poly_seq_scheme`, writes one
+    residue per position where two residue types share it, and explains when a file has no polymer.
+- **Fixed after a second, targeted stress test** (100 systems: integrative models, ModelArchive and PDBe files,
+  chemical component files, entries chosen for one weak spot each, and modified copies of entries):
+  - `mmcif_reres` / `mmcif_fixinsert`: in files whose models hold different residues (4PTJ), the anisotropic
+    rows of later models got model 1's numbers; they now follow their own atom.
+  - `mmcif_merge` (and every tool that adds rows to a loop): with upper-case tags (`_ATOM_SITE.ID`), atom ids
+    were not renumbered; tags are case-insensitive, as in CIF.
+  - Edits with `--label` on a file without label columns (or without `--label` on one without author
+    columns) changed the other scheme's columns; they now stop with a clear message.
+  - `mmcif_fixinsert`: links whose rows have no residue name (as gemmi writes them) were not renumbered.
+  - `mmcif_head` counted the atoms of each data block separately; it now counts over the whole file, as its
+    help says.
+  - `mmcif_selaltloc` writes a file without an altloc column unchanged; `mmcif_b` / `mmcif_occ` add their
+    column when it is missing; "missing column" errors name the mmCIF column (`type_symbol`, `group_PDB`, ...).
+  - `mmcif_merge`, `mmcif_mkensemble` and `mmcif_topdb` say in their help that they use the first data block.
+- **`mmcif_delmeta`** deletes the metadata that edits make stale (validation reports, secondary structure, sites,
+  assemblies, ...) and keeps the atoms, links, entry, method and resolution, release dates, unit cell, entities,
+  chains (`_struct_asym`), sequences, ligands (`_pdbx_entity_nonpoly`), modified residues and chemical components
+  with their atoms and bonds: what structure prediction programs (AlphaFold 2 and 3, ColabFold, OpenFold3, Boltz,
+  Chai-1, Protenix, BioEmu) and MD preparation programs (OpenMM, PDBFixer) read. The kept tables follow the atoms:
+  chains, entities and modified residues with no atoms left are removed, modified residues get their current
+  author numbers, the number of molecules and the chains of each entity are recomputed, and `_pdbx_poly_seq_scheme`
+  is rebuilt (OpenFold3 needs it). So it is the last step of a pipeline. `-all` keeps only the atoms and links.
+  (A first version deleted `_struct_asym`, and ColabFold rejected its files as templates.)
+- **Checking an installation:** `python tools/smoke_test.py` runs every command and a few pipelines. The full test
+  suite stays with the developers and is not part of the public repository.
+- **Known limitation:** after an edit, categories other than `_atom_site`, `_atom_site_anisotrop` and
+  `_struct_conn` that refer to atoms or residues (`_struct_conf`, `_pdbx_poly_seq_scheme`, `_pdbx_validate_*`,
+  ...) are left as they were. A tool to bring them back in step is planned.

mmcif_tools-0.1.1/CITATION.cff

@@ -0,0 +1,38 @@
+cff-version: 1.2.0
+message: "If you use mmcif-tools, please cite it as below."
+title: "mmcif-tools: command-line tools for mmCIF files"
+type: software
+version: 0.1.1
+date-released: "2026-10-29"
+license: Apache-2.0
+repository-code: "https://github.com/matteo-cagiada/mmcif-tools"
+abstract: >-
+  Small, single-purpose command-line tools to select, edit, convert and inspect
+  macromolecular structures in the mmCIF (PDBx/mmCIF) format, chained with Unix
+  pipes. Standard library Python only. Inspired by pdb-tools.
+keywords:
+  - mmCIF
+  - PDBx
+  - Protein Data Bank
+  - structural biology
+  - command line
+authors:
+  - family-names: Cagiada
+    given-names: Matteo
+references:
+  - type: article
+    title: "pdb-tools: a swiss army knife for molecular structures"
+    authors:
+      - family-names: Rodrigues
+        given-names: João P. G. L. M.
+      - family-names: Teixeira
+        given-names: João M. C.
+      - family-names: Trellet
+        given-names: Mikaël
+      - family-names: Bonvin
+        given-names: Alexandre M. J. J.
+    journal: F1000Research
+    volume: 7
+    start: 1961
+    year: 2018
+    doi: 10.12688/f1000research.17456.1

mmcif_tools-0.1.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2018 João Pedro Rodrigues
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mmcif_tools-0.1.1/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md CITATION.cff
+recursive-include docs *.md
+prune tests

mmcif_tools-0.1.1/NOTICE

@@ -0,0 +1,12 @@
+mmcif-tools
+Copyright 2026 the mmcif-tools authors
+
+mmcif-tools is an independent project, inspired by pdb-tools
+(https://github.com/haddocking/pdb-tools). Its command-line conventions, its
+tool set and parts of its help texts follow pdb-tools, which is Copyright the
+pdb-tools authors (Rodrigues JPGLM, Teixeira JMC, Trellet M, Bonvin AMJJ) and
+is distributed under the Apache License, Version 2.0.
+
+  Rodrigues JPGLM, Teixeira JMC, Trellet M and Bonvin AMJJ.
+  pdb-tools: a swiss army knife for molecular structures.
+  F1000Research 2018, 7:1961 (https://doi.org/10.12688/f1000research.17456.1)

mmcif_tools-0.1.1/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: mmcif-tools
+Version: 0.1.1
+Summary: Small, pipeable command-line tools to select, edit and inspect mmCIF files (standard library only).
+Author: Matteo Cagiada
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/matteo-cagiada/mmcif-tools
+Project-URL: Documentation, https://matteo-cagiada.github.io/mmcif-tools/
+Project-URL: Changelog, https://github.com/matteo-cagiada/mmcif-tools/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/matteo-cagiada/mmcif-tools/issues
+Keywords: mmCIF,PDBx,PDB,protein structure,structural biology,command line
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# mmcif-tools
+
+mmcif-tools is an independent project whose style and much of its tool set are inspired by
+[pdb-tools](https://www.bonvinlab.org/pdb-tools/) (Rodrigues JPGLM, Teixeira JMC, Trellet M and Bonvin AMJJ,
+*F1000Research* 2018, 7:1961). mmcif-tools ports and expands the pdb-tools functionality to the mmCIF (PDBx/mmCIF)
+format.
+
+As pdb-tools, it is a set of small, single-purpose command-line tools that read and write mmCIF files and chain
+together with Unix pipes: select, delete, edit, convert and inspect structures without leaving the shell. The
+package needs only the Python standard library (Python 3.9 or newer).
+
+```bash
+mmcif_fetch 1brs | mmcif_selchain -A,D | mmcif_delentity -non-polymer,water | mmcif_reres -1 | mmcif_delmeta > clean.cif
+```
+
+**CURRENT VERSION: Version 0.1.1, pre-release: 53 available tools**
+
+
+## Tools
+
+mmcif-tools reads the mmCIF text format, as written by the PDB (wwPDB, RCSB, PDBe), the AlphaFold DB (ModelCIF),
+structure prediction and modelling programs and viewers, plain or gzip-compressed. BinaryCIF is currently not
+supported.
+
+The full `--help` text of every tool is in the [tool reference](https://matteo-cagiada.github.io/mmcif-tools/tools/).
+
+| Group | Tool | What it does |
+|---|---|---|
+| Fetch / convert | `mmcif_fetch` | Download an entry from the RCSB (or `-biounit`), or an AlphaFold DB model (`AF-P69905-F1`) |
+| | `mmcif_topdb` / `mmcif_frompdb` | Convert to / from the PDB format (`mmcif_frompdb` assigns label identifiers) |
+| Select / delete | `mmcif_selchain` / `mmcif_delchain` | Keep / remove chains (`-A,B`) |
+| | `mmcif_selres` / `mmcif_delres` | Keep / remove residues by number (`-1:10,20:30`, `-::5`) |
+| | `mmcif_selresname` / `mmcif_delresname` | Keep / remove residues by name (`-HOH`) |
+| | `mmcif_selatom` | Keep atoms by name (`-CA,C,N,O`) |
+| | `mmcif_selelem` / `mmcif_delelem` | Keep / remove atoms by element (`-C,N`, `-H`) |
+| | `mmcif_selentity` / `mmcif_delentity` | Keep / remove entities by number or type (`-polymer`, `-non-polymer,water`) |
+| | `mmcif_selhetatm` / `mmcif_delhetatm` | Keep / remove HETATM records (ligands, ions, waters, and modified residues) |
+| | `mmcif_selaltloc` | Keep one alternate location (highest occupancy, or `-A`) |
+| | `mmcif_selmodel` | Keep models (`-1,3`) |
+| | `mmcif_head` | Keep the first N atoms (`-100`) |
+| | `mmcif_delmeta` | Delete the metadata that edits make stale; keep the rest (entry, method, entities, chains, ...) in step with the atoms (`-all`: atoms only) |
+| | `mmcif_keepcoord` | Keep only the coordinates (`_atom_site`, `_struct_conn`), as `pdb_keepcoord` |
+| | `mmcif_intersect` | Keep the atoms of the first file found in all the others |
+| Edit | `mmcif_chain` / `mmcif_rplchain` | Set all chains (`-C`) / rename one chain (`-A:B`) |
+| | `mmcif_reres` / `mmcif_shiftres` | Renumber residues from a number / shift them by a number |
+| | `mmcif_fixinsert` (`mmcif_delinsertion`) | Remove insertion codes, shifting the numbering |
+| | `mmcif_reatom` | Renumber atom ids |
+| | `mmcif_rplresname` | Rename a residue type (`-HIP:HIS`) |
+| | `mmcif_uniqname` | Rename ligand atoms C1, C2, O1, … |
+| | `mmcif_element` | Assign elements from atom names (`-all` to redo all) |
+| | `mmcif_b` / `mmcif_occ` | Set B-factors / occupancies |
+| Identifiers | `mmcif_label2auth` | Copy label chains and residue numbers onto the author ones (`-chain`, `-res`) |
+| | `mmcif_auth2label` | Copy author chains onto the label chains of polymers |
+| Models, files, assemblies | `mmcif_splitchain` / `mmcif_splitmodel` | Write one file per chain / model |
+| | `mmcif_mkensemble` / `mmcif_chkensemble` | Build a multi-model file / check its models match |
+| | `mmcif_merge` | Merge the atoms of several files into one |
+| | `mmcif_assembly` | Build a biological assembly from the file's symmetry operations (`-1`) |
+| Categories / blocks | `mmcif_cat` | Print one category as a table (TSV): `-_atom_site.id,Cartn_x` |
+| | `mmcif_delcat` / `mmcif_keepcat` | Remove / keep whole categories (`-_struct_conf`, `'-_pdbx_validate*'`) |
+| | `mmcif_blocks` | List the data blocks, or extract some (`-ATP`) |
+| Inspect / format | `mmcif_info` | Title, method, resolution, organisms, entities, assemblies |
+| | `mmcif_wc` | Counts: models, chains, residues, atoms, … |
+| | `mmcif_tofasta` | Sequence in FASTA format (`-multi`, `-seqres`) |
+| | `mmcif_gap` | Report chain breaks |
+| | `mmcif_sort` | Sort atoms by chain and residue |
+| | `mmcif_tidy` | Rewrite in a uniform, aligned layout |
+| | `mmcif_validate` | Check syntax, coordinates and consistency |
+
+## Usage examples and tips
+
+### Command examples
+
+```bash
+# A clean protein for docking or simulations: one conformer, no ligands or waters, an aligned layout
+mmcif_fetch 4hhb | mmcif_selaltloc | mmcif_delentity -non-polymer,water | mmcif_delmeta | mmcif_tidy > 4hhb_protein.cif
+
+# Chain A with its heme, numbered from 1, as a PDB file for programs that need one
+mmcif_fetch 4hhb | mmcif_selchain -A | mmcif_delentity -water | mmcif_reres -1 | mmcif_topdb > 4hhb_A.pdb
+
+# The biological assembly, built from the symmetry operations in the file (chains A, A-2, A-3, A-4)
+mmcif_fetch 1stp | mmcif_assembly > 1stp_tetramer.cif
+
+# What an entry holds: method, resolution, organisms, entities, assemblies (and the pLDDT of AlphaFold models)
+mmcif_fetch 4hhb | mmcif_info
+mmcif_fetch AF-P69905-F1 | mmcif_info
+
+# A table of atoms for awk, R or pandas (tab-separated, one header line)
+mmcif_cat -_atom_site.auth_asym_id,auth_seq_id,label_comp_id,B_iso_or_equiv 4hhb.cif > atoms.tsv
+
+# Residues numbered along the deposited sequence, and one author chain per molecule
+mmcif_label2auth 4hhb.cif > 4hhb_by_sequence.cif
+
+# Delete only some categories: here the PDB's validation reports and secondary structure
+mmcif_delcat '-_pdbx_validate*,_struct_conf,_struct_sheet_range' 4hhb.cif > 4hhb_lean.cif
+```
+
+### `mmcif_delmeta`
+
+A PDB entry is mostly metadata: 4HHB has 72 categories, and only a few of them hold the atoms. Most of the rest
+refers to residues by chain and number: validation reports, secondary structure, sequence schemes, binding sites,
+assemblies, and more. The edit tools keep the atoms and their links consistent, but not these tables, so after
+renumbering or deleting residues they describe a structure that is no longer there. Simulation and prediction
+programs rarely read them anyway.
+
+`mmcif_delmeta` deletes that metadata and keeps what is fundamental: the atoms, their links and anisotropic B-factors;
+the entry id, method, resolution and release dates; the unit cell and space group; the entities, chains and
+sequences; the ligands and modified residues; and the chemical components with their atoms and bonds. It also
+brings these tables in step with the atoms: chains, entities and modified residues with no atoms left are removed,
+the number of molecules and the chains of each entity are recomputed, modified residues get their current author
+numbers, and the table that places each chain's residues on its sequence (`_pdbx_poly_seq_scheme`) is rebuilt.
+For 4HHB that is 18 categories instead of 72, and the file is still valid mmCIF.
+
+```bash
+mmcif_fetch 4hhb | mmcif_delentity -non-polymer,water | mmcif_reres -10 | mmcif_reatom -4 | mmcif_delmeta > 4hhb_clean.cif
+```
+
+We suggest running `mmcif_delmeta` as the last step, after you have completed the structure manipulations.
+
+The kept categories are also those that structure prediction programs read from template or input files (AlphaFold 2
+and 3, ColabFold, OpenFold3, Boltz, Chai-1, Protenix, BioEmu), and MD preparation programs from structures (OpenMM,
+PDBFixer).
+
+`mmcif_delmeta -all` keeps only the atoms and links, and `mmcif_keepcat` keeps exactly the categories you list.
+
+### Tips
+
+- Each tool takes at most one option (starting with `-`) and one file, and reads stdin when no file is given, so
+  tools chain with pipes. Negative numbers need a double dash (`mmcif_shiftres --5`).
+- `--help` prints a tool's usage (not `-h`, which is a real option of some tools, e.g. `mmcif_wc -h`).
+- Errors go to stderr as `ERROR!! ...`, with exit status 1.
+- Rows a tool does not change are written back byte-for-byte. In changed rows, only the edited values are
+  rewritten, and the other columns keep their alignment.
+- To remove ligands and waters, select by entity (`mmcif_delentity -non-polymer,water`) rather than by HETATM
+  record: `mmcif_delhetatm` also removes modified residues inside chains (selenomethionine, modified nucleotides).
+- Quote options that contain `*`, so that the shell does not expand them: `'-_pdbx_validate*'`.
+- Input files can be gzip-compressed (`.cif.gz`); outputs are plain text, so pipe them to `gzip` to compress.
+- After editing, `mmcif_validate` checks the syntax, the coordinates and the links between tables.
+
+#### Files for prediction and MD programs
+
+- **AlphaFold 3** templates must hold a single protein chain: select it with `mmcif_selchain` (ligands may stay).
+- **Boltz-2 and OpenFold3** name template chains by their label id (`_struct_asym.id`), not the author chain. To
+  see which is which: `mmcif_cat -_atom_site.label_asym_id,auth_asym_id file.cif | sort -u`.
+- **Renumber the author numbers only** (the default of `mmcif_reres` and `mmcif_shiftres`). These programs place
+  residues on the sequence by `label_seq_id`, which `--label` renumbering changes.
+- **Residues deleted inside a chain are still in the sequence**: prediction programs treat them as unresolved, and
+  PDBFixer rebuilds them as missing residues. `mmcif_delmeta -all` drops the sequences as well.
+- **OpenMM takes `_cell` as the periodic box.** Cryo-EM and NMR entries often carry a placeholder cell of 1 Å;
+  remove it with `mmcif_delcat -_cell,_symmetry`, or set the box when solvating.
+
+## Coming from pdb-tools
+
+Most tools have the pdb-tools name with `mmcif_` for `pdb_` and the same options. The differences:
+
+- `pdb_tocif` / `pdb_fromcif` are `mmcif_frompdb` / `mmcif_topdb`.
+- The segment tools (`pdb_seg`, `pdb_selseg`, `pdb_splitseg`) have no counterpart: mmCIF has no segment identifier,
+  and `label_asym_id` names each molecule (`mmcif_selchain --label`, `mmcif_splitchain --label`).
+- `pdb_chainbows`, `pdb_chainxseg` and `pdb_segxchain` have no counterpart: mmCIF has no TER records. `mmcif_frompdb`
+  uses the TER records of a PDB file to separate molecules and names blank chains, and `mmcif_label2auth -chain`
+  gives each molecule its own author chain.
+- Where pdb-tools behaves differently (or has a bug), the tool's `--help` says so.
+
+## Things to know about mmCIF
+
+- **Two sets of identifiers.** mmCIF names chains and residues twice: author names (`auth_*`, what papers and
+  viewers show) and the PDB's own names (`label_*`, one label chain per molecule, residues numbered along the
+  sequence). Tools use author names by default; pass `--label` to use `label_*` instead, or set
+  `MMCIFTOOLS_SCHEME=label` for every tool. Edits change one scheme only. Residue and atom names are the same in
+  both, so `mmcif_rplresname` and `mmcif_uniqname` change both name columns.
+- **Related tables stay in step.** Removing atoms also removes their rows in `_atom_site_anisotrop` and
+  `_struct_conn`; renaming chains or renumbering residues updates the same two tables. Other categories that
+  mention chains or residues (`_struct_conf`, `_pdbx_poly_seq_scheme`, ...) are left as they were.
+- **Entities.** Every molecule belongs to an entity: polymer, non-polymer, branched (glycans) or water.
+  `mmcif_selentity` / `mmcif_delentity` select by entity, which keeps modified residues (HETATM records inside a
+  chain, such as MSE or the modified nucleotides of a tRNA) with their chain; `mmcif_delhetatm` removes them.
+- **No fixed columns.** Chain identifiers can be longer than one character, and there are no limits on atom or
+  residue numbers. `mmcif_topdb` refuses structures that do not fit the PDB format.
+
+## Installation
+
+```bash
+python -m pip install mmcif-tools
+```
+
+There are no runtime dependencies. For tab completion of the `mmcif_*` commands, open a new terminal after
+installing (or run `rehash` in an open zsh terminal).
+
+The extra tools below are in the repository, not in the package. To install from the repository instead,
+`python tools/smoke_test.py` then checks the installation: every command runs, and a few pipelines give the
+expected results.
+
+```bash
+git clone https://github.com/matteo-cagiada/mmcif-tools.git
+cd mmcif-tools
+python -m pip install .
+python tools/smoke_test.py
+```
+
+## Extra tools
+
+`tools/` holds scripts that are not part of mmcif-tools and are not installed with it.
+
+- **`tools/check_with_gemmi.py`** checks CIF files with [gemmi](https://github.com/project-gemmi/gemmi), an
+  independent CIF reader: the syntax, and optionally a dictionary such as the PDBx/mmCIF one (`--dict`). It runs the
+  gemmi program, which you install yourself (e.g. `pip install gemmi-program`); give its path with `--gemmi` if it
+  is not on the PATH:
+
+  ```bash
+  python tools/check_with_gemmi.py --gemmi /path/to/gemmi out.cif
+  mmcif_selchain -A 1abc.cif | python tools/check_with_gemmi.py --dict mmcif_pdbx_v50.dic -
+  ```
+
+- **`tools/make_docs.py`** writes the [tool reference](https://matteo-cagiada.github.io/mmcif-tools/tools/) and
+  the other pages of the [documentation website](https://matteo-cagiada.github.io/mmcif-tools/).
+- **`tools/smoke_test.py`** checks an installation (see
+  [Installation](https://matteo-cagiada.github.io/mmcif-tools/installation/)).
+
+## Citation and changes
+
+How to cite mmcif-tools is in [CITATION.cff](https://github.com/matteo-cagiada/mmcif-tools/blob/main/CITATION.cff);
+the changes between versions are in the [changelog](https://matteo-cagiada.github.io/mmcif-tools/changelog/).
+[PLAN.md](https://github.com/matteo-cagiada/mmcif-tools/blob/main/PLAN.md) records the design decisions and the test
+results.
+
+## Acknowledgements
+
+Most of the code of mmcif-tools has been written with [Claude Code](https://claude.com/claude-code),
+Anthropic's AI coding assistant. The author designed the project, tools and tests to guarantee the quality of the tool.
+We thank the Bonvin Lab for developing and releasing pdb-tools, a fundamental tool for the authors' academic work.
+
+## License
+
+Apache-2.0. See [LICENSE](https://github.com/matteo-cagiada/mmcif-tools/blob/main/LICENSE).