CIF_FILTER(1)

🌈 CIF_FILTER(1) — bestie's manual moment 🌈

okay so welcome to CIF_FILTER(1), from the General Commands Manual section. This is the page for the cif_filter script, and she's lowkey iconic. She parses CIF files, prints essential data values in CIF format — the COD CIF style — and she has so many side quests. No cap.

---

🎀 NAME 🎀

cif_filter — parse a CIF file and print out essential data values in the CIF format, the COD CIF style. This script has also many capabilities -- it can restore space group symbols from symmetry operators (consulting predefined tables), parse and tidy-up _chemical_formula_sum, compute cell volume, exclude unknown or "empty" tags, and add specified bibliography data. she's literally that girl.

🦋 SYNOPSIS 🦋

# ✨ DESCRIPTION ✨

so bestie, `cif_filter` parses a CIF file and prints out essential data values in the CIF format, the COD CIF style.

and she's not one-note. This script has also many capabilities — it can restore space group symbols from symmetry operators (consulting predefined tables), parse and tidy-up `_chemical_formula_sum`, compute cell volume, exclude unknown or "empty" tags, and add specified bibliography data. <hotpink>she ate, fr fr.</hotpink>

# 💅 OPTIONS 💅

- **`-a`, `--authors`** — put the author list here, like `'John Doe; Jane Doe; Joe Bloggs'`. <pink>author moment.</pink>

- **`-j`, `--journal`** — journal name goes here, like `'Acta Cryst. A'`. <lavender>periodt.</lavender>

- **`-v`, `--volume`** — volume value, like `36`.

- **`-i`, `--issue`** — issue value, like `1`.

- **`-p`, `--page`** — page value, like `123`.

- **`--start-page`** — start page value, like `123`.

- **`-e`, `--end-page`** — end page value, like `132`.

- **`-y`, `--year`** — year value, like `1999`.

- **`-D`, `--doi`** — Specify bibliographic data to be included into the output. like `10.1010/xyz9999`. <hotpink>doi slay.</hotpink>

- **`-B`, `--bibliography`** — Provide a bibliography file with the bibliographic information to be included into the output. The bibliography information can be provided in CIF format or in a XML-like `.mrk` file with data items between `<authors>`, `<journal>`, `<volume>`, `<issue>`, `<year>`, `<pages>123-132</pages>` tags. give her `bibliography.cif` or `bibliography.mrk`, bestie. <mint>two file vibes.</mint>

- **`--leave-bibliography`** — Combine bibliographies from various sources. Values of lower precedence are overwritten, but never deleted. List of bibliography sources in order of increasing precedence:
  1. the bibliography tags of the original CIF file;
  2. the optional bibliography file;
  3. the user specified command line options.
  <cyan>merge the lore.</cyan>

- **`--discard-bibliography`** — Only retain the bibliography tags from the bibliography source of highest precedence (see `'--leave-bibliography'` option). Default.

- **`--leave-title`** — Do not delete the publication title obtained from the source of lower precedence, even if the `'--discard-bibliography'` option is enabled.

- **`-g`, `--global-priority`** — Assume bibliography found in `'data_global'` data block has precedence over bibliographies found in all the other data blocks.

- **`-g-`, `--no-global-priority`** — Assume bibliography found in `'data_global'` data block does not have precedence over bibliographies found in all the other data blocks. Only missing bibliographic information will be copied from the `'data_global'` data block. Default.

- **`--exclude-publication-details`** — Exclude potentially copyrighted and irrelevant tags. Default.

- **`--no-exclude-publication-details`, `--dont-exclude-publication-details`** — Do not exclude potentially copyrighted and irrelevant tags.

- **`-h`, `--add-cif-header`** — Prepend each of the output files with the comments from the beginning of the specified file. use `header_file.cif`. <peach>header energy.</peach>

- **`-s`, `--estimate-space-group`, `--estimate-spacegroup`** — Estimate space group symbols from the symmetry operators in the input.

- **`-s-`, `--no-estimate-space-group`, `--dont-estimate-space-group`, `--no-estimate-spacegroup`, `--dont-estimate-spacegroup`** — Do not estimate space group symbols from the symmetry operators in the input. Default.

- **`--keep-unrecognised-space-groups`, `--keep-unrecognised-spacegroups`** — This option is a modifier for the `'--estimate-space-group'` option. Leave tags with unrecognised space group information as they are.

- **`--no-keep-unrecognised-space-groups`, `--dont-keep-unrecognised-space-groups`, `--no-keep-unrecognised-spacegroups`, `--dont-keep-unrecognised-spacegroups`** — This option is a modifier for the `'--estimate-space-group'` option. Replace the values of tags with unrecognised space group information with unknown values (represented as `'?'`) and store the unrecognised space group information in `'_cod_original_sg_*'` tags. Default.

- **`--reformat-space-group`, `--reformat-spacegroup`** — Correct the formatting of Hermann-Mauguin symmetry space group symbol.

- **`--dont-reformat-space-group`, `--leave-space-group`, `--dont-reformat-spacegroup`, `--leave-spacegroup`** — Leave the Hermann-Mauguin symmetry space group symbol as is. Default.

- **`--exclude-empty-tags`** — Remove data items that contain only empty values. A value is considered empty if it is equal to a single question mark (`'?'`) or a single period (`'.'`).

- **`--no-exclude-empty-tags`, `--dont-exclude-empty-tags`** — Disable the `'--exclude-empty-tags'` option. Default.

- **`--placeholder-tag-list`** — takes `'_chemical_name_common,_chemical_name_systematic'`. A comma-separated list of data items that should be checked for placeholder values. Default: `'_chemical_name_common,_chemical_name_systematic'`.

- **`--exclude-placeholder-tags`** — Remove data items that contain common placeholder values — i.e. a multiline value consisting only of white spaces and question marks. Only data items specified using the `--placeholder-tag-list` are affected by this option.

- **`--no-exclude-placeholder-tags`, `--dont-exclude-placeholder-tags`** — Disable the `'--exclude-placeholder-tags'` option. Default.

- **`--exclude-redundant-chemical-names`** — Remove data items related to various chemical names (systematic, common, mineral) if the stored values match the chemical formula.

- **`--no-exclude-redundant-chemical-names`, `--dont-exclude-redundant-chemical-names`** — Disable the `'--exclude-redundant-chemical-names'` option. Default.

- **`--exclude-empty-non-loop-tags`** — Remove tags that contain empty values and are not contained within the CIF `loop_` structure. For the definition of empty values, see `'--exclude-empty-tags'` option. This option does not override the `'--exclude-empty-tags'` option.

- **`--no-exclude-non-loop-empty-tags`, `--dont-exclude-non-loop-empty-tags`** — Disable the `'--exclude-empty-non-loop-tags'` option. Default.

- **`--exclude-unknown-tags`** — Remove tags that contain only unknown values. A value is considered unknown if it is equal to a single question mark (`'?'`).

- **`--no-exclude-unknown-tags`, `--dont-exclude-unknown-tags`** — Disable the `'--exclude-unknown-tags'` option. Default.

- **`--exclude-unknown-non-loop-tags`** — Remove tags that contain unknown values and are not contained within the CIF `loop_` structure. For the definition of unknown values, see `'--exclude-unknown-tags'` option. This option does not override the `'--exclude-unknown-tags'` option.

- **`--no-exclude-non-loop-unknown-tags`, `--dont-exclude-non-loop-unknown-tags`** — Disable the `'--exclude-unknown-non-loop-tags'` option. Default.

- **`-x`, `--extra-tag-list`** — Add additional tags to the list of recognised CIF tags. These extra tags are presented in a separate file, one tag per line. use `tag-list.lst`. <mint>one tag per line, bestie.</mint>

- **`--exclude-misspelled-tags`** — Remove tags that were not present in the recognised tag list.

- **`--no-exclude-misspelled-tags`, `--dont-exclude-misspelled-tags`** — Disable the `'--exclude-misspelled-tags'` option. Default.

- **`--parse-formula-sum`** — Parse `'_chemical_formula_sum'` tag value and reformat it according to the Hill system ordering. If the original and reformatted formulae differ, replace the original value with the reformatted one and store the original value as the `'_cod_original_formula_sum'` tag value. <purple>formula glow-up.</purple>

- **`--no-parse-formula-sum`, `--dont-parse-formula-sum`** — Do not parse `'_chemical_formula_sum'` tag value. Default.

- **`--fix-syntax-errors`** — Try to fix syntax errors in the input CIF files that can be corrected unambiguously.

- **`--no-fix-syntax-errors`, `--dont-fix-syntax-errors`** — Do not try to fix syntax errors in input CIF files. Default.

- **`--retain-tag-order`** — Print tags in the same order they appeared in the original file.

- **`--dont-retain-tag-order`** — Disregard original tag order while printing the tags. Default.

- **`--preserve-loop-order`** — Print loops in the same order they appeared in the original file.

- **`--use-internal-loop-order`** — Disregard original loop order while printing the tags. Default.

- **`--calculate-cell-volume`** — Calculate the unit cell volume from the cell constants. If the calculated value differs from the one already present in the CIF, replace the original value with the calculated one and store the original value as the `'_cod_original_cell_volume'` tag value.

- **`--dont-calculate-cell-volume`** — Do not calculate unit cell volume from the cell constants. Default.

- **`--original-filename`** — Use the provided string as the name of the original file. (see `--record-original-filename`). use `data_source.cif`. <cyan>filename lore.</cyan>

- **`--clear-original-filename`** — don't reuse any strings you handed over earlier as the name of the original file. Wiping the slate 💅
- **`--record-original-filename`** — writes down the original filename *and* the original data block name for every data block, stashing them in the `_cod_data_source_*` tag values. Receipts, bestie 🧾
- **`--dont-record-original-filename`** — skip all that recording of the original filename and original data block name. This is the **default**. No receipts today 🙈
- **`-S`, `--start-data-block-number 1234567`** — use the number you give as the starting point when renaming data blocks. Default: `7000001`. Heads up: flipping this on *also* turns on the `-R` option ✨
- **`-d`, `--datablock-format '%07d'`** — use this format string to figure out the new data block names from the data block numbers you've got. Default: `'%07d'`.
- **`-R`, `--renumber-data-blocks`** — rename *every* data block, no survivors. The new names get built by grabbing a start number (that's the `-S` option), applying the string format (that's the `-d` option), and then bumping the start number up for each data block in sequence. Glow-up arc for your block names 👑
- **`-R-`, `--dont-renumber-data-blocks`** — leave those data block names alone. This is the **default**. And enabling it resets the `-S` option back to its default value.
- **`--original-filename-tag _cod_data_source_file`**
- **`--original-data-block-tag _cod_data_source_block`** — these two let you pick which tags get used to record the original filename / data block name. Defaults: `'_cod_data_source_file'` and `'_cod_data_source_block'`.
- **`--database-code-tag _cod_database_code`** — pick the tag that gets used when adding or updating the database code as data blocks are renamed. Default: `'_cod_database_code'`.
- **`--update-database-code`** — refresh the database code tag value when the data blocks get renamed. This is the **default**.
- **`--dont-update-database-code`** — do *not* refresh that database code tag value when the data blocks get renamed. Leave it as-is 🫶
- **`--use-datablocks-without-coordinates`, `--use-all-datablocks`** — do not remove data blocks that don't have coordinates. Keep the coord-less ones, they're valid 💜
- **`--no-use-datablocks-without-coordinates`, `--do-not-use-datablocks-without-coordinates`, `--dont-use-datablocks-without-coordinates`, `--skip-datablocks-without-coordinates`** — remove data blocks that don't have coordinates. This is the **default**. yeah, the no-coords ones get the boot 😭
- **`--use-datablocks-with-structure-factors`** — do not remove data blocks that have structure factors (Fobs). This is the **default**.
- **`--no-use-datablocks-with-structure-factors`, `--dont-use-datablocks-with-structure-factors`, `--skip-datablocks-with-structure-factors`** — filter out the data blocks that have structure factors (Fobs). Bye babe 💀
- **`--folding-width 78`** — sets how long the longest unfolded line is allowed to be. Default: `76`. (yes the example says `78`, the default says `76`, we don't question the lore 📏)
- **`--fold-title`** — folds the title if it's longer than the folding width. Cinched and wrapped 🎀
- **`--dont-fold-title`** — do not fold the title. This is the **default**.
- **`--fold-long-fields`** — folds any fields that run longer than the folding width.
- **`--dont-fold-long-fields`** — do not fold fields. This is the **default**.
- **`--use-perl-parser`** — parse your CIF with the Perl parser.
- **`--use-c-parser`** — parse your CIF with the Perl & C parser. This is the **default**, and it's giving speed ✨
- **`--cif-input`** — take input in CIF format. This is the **default**.
- **`--json-input`** — take input in JSON format.
- **`--cif-output`** — give output in CIF format. This is the **default**.
- **`--json-output`** — give output in JSON format.
- **`--cif`** — CIF format for both input and output. This is the **default**.
- **`--json`** — JSON format for both input and output. the way that one flag does both?? obsessed 🌈
- **`--help`, `--usage`** — prints a short usage message (literally this message) and dips out. Exit, stage left 👋
- **`--version`** — prints version info and exits. Main character reveal 💫

---

# 🐛 REPORTING BUGS 🐛

Found a `cif_filter` bug?? bestie do NOT suffer in silence, spill it. Send an e-mail to: `cod-bugs@ibt.lt` 📧

---

<pink>and that's a wrap on `CIF_FILTER(1)`!!</pink> 🦋 ty for reading all the way to the bottom, you're a real one 💖 this page lives in section 1 of the manual, so if you ever need to find it again, `man 1 cif_filter` has your back 🫶 ok bye ily, go filter some CIFs responsibly 👑