FinalCif

Finalcif is mainly intended for Bruker users, but works for other CIF files too. It collects all the information from a work folder needed in order to finalize a CIF file for publication. In ideal cases, it takes one click to have a publication-ready file. But check the file thoroughly afterwards, no software is perfect!

Installation

Windows

Start the installer (FinalCif-setup-x64-vXX.exe) and click next until finished.

Linux

FinalCif for linux needs no installation. Just download the executable FinalCif-vXX_opensuse or FinalCif-vXX_ubuntu anywhere on you computer. A second option for Ubuntu is to run the installer script here.

MacOS

Unzip the app (Finalcif-vXX_macos.app.zip) and copy it to the Applications directory. The app might not work in any MacOS versions. Please use the source code installation if necessary.

Developers

FinalCif can also run directly from python. Please refer to :ref: sources for further instructions.

Introduction

CIF files from SHELXL miss a lot of information that should be added prior to publication. Editting CIF files with text editors is a tedious task and often leads to errors. Therefore, FinalCif tries to help you with this task. Essentially, you must have the corresponding CIF file for FinalCif in its original ‘work’ folder, which contains all other files such as SAINT list files, SADABS list file, SHELX list files, etc. that led to this cif file. The main table of FinalCif has three columns. The most left contains the information from the .cif file. Data from other sources like the .p4p file is displayed in the middle column and user information can be put into the right-most column. The data typed by the user always rules out the other information. The two different templates on the left can be used to fill in author information or machine models (top) as well as to create dropdown menus for specific CIF keywords (bottom). Any keyword not already in the CIF file will be added by the template. In the dropdown menus, you can be creative to specify the crystallization conditions with a template.

The CIF keywords with a question mark as value are at the beginning of the man table in FinalCif and the keywords with values are below.

Each input field accepts Unicode characters like “ω”. They are automatically translated into the CIF ascii format. Please let me know if a character does not work.

Various possibilities of Checkcif are available, online with html or pdf result and offline. The button “save cif file” saves the current file under ‘name’-finalcif.cif. FinalCif will never make Changes to the original CIF file.

The FinalCif executable accepts a file name as first argument in order to open .cif files from other programs like ShelXle.

A workflow example

  • Open a cif file in a work folder.

  • Check and edit the remaining items.

  • Do a html checkcif (it also saves an image for the report). Probaly correct last items like the moiety formula and explain alerts with the validation response form editor in the same window.

  • Do a pdf checkcif

  • Submit the CIF to the CCDC

  • Drag&drop the CCDC deposit reply email into the work folder, or edit the CCDC number manually

  • Click on „Make Tables“

Files used by FinalCif

  • SADBABS .abs

  • SAINT _0m._ls, _01._ls

  • Bruker _0m.p4p

  • One frame like _ib_01_0001.sfrm

  • A .eml email file for the CCDC number

  • the .hkl and .res file content of the CIF itself

Non-Bruker Data

For Rigaku and STOE datasets, it is not necessary for FinalCif to collect information from various files. Instead, it is sufficient to import a certain CIF created during the experiment. Rigaku produces a ‘.cif_od’ file and STOE a ‘.cfx’ file for example. Also the Bruker ‘.pcf’ file is importable. You can import any additional CIF formated file with the ‘Import’ button on the left center. This will import all key/values and loops from the file except for unit cell and space group information.

Templates

FinalCif uses two different kinds of templates to to simplify recurring tasks:

  • Equipment and Author templates

    They are useful for definitions of parameters like the properties of a measurement device or the name and address of the crystallographer. Apply template by double-clicking on one row.

  • Property templates

    Property templates define possible dropdown-menus for common CIF keywords like _cell_measurement_temperature. The template values are accessible as a dropdown behind the respective key in the main table of FinalCif.

_images/templates.png

The templates selection and editor.

Templates can be edited anytime and they can be saved as a CIF file. You can use them for any cif keyword. Just be creative…

_images/property_templates.png

Template editor for crystallization methods.

For example the crystallographer information:

_images/equipment_templates.png

Crystallographer details template.

Or just one keyword for only the absolute configuration information:

_images/absolute_configuration.png

Absolute configuration template.

Sidenotes

  • The predefined templates may change from time to time. To see the current version you can delete the predefined template (edit template–>delete).

  • As any other CIF, in order to import a template, it needs a data_ keyword at the start.

Loops

FinalCif is also able to edit loop data from a CIf file by clicking the “Edit Loops” button. Each loop has its own tab where the loop data is represented as a table. All fields changed by the user will turn pale red to indicate modifications and these are save during the next file save.

Rows can be added and deleted with a right click on a table.

The “revert changes” button reverts all changes done to the current loop, except for adding and deleting rows.

_images/finalcif_loops2.png

Atomic coordinates table (loop)

The “Manuscript Related” tab contains an input mask to add author information for publication purpose as a cif loop. This is not to be confused with the “Crystallographer Details” in the “Equipment and Author Templates” section. New authors can be saved as templates for future use.

CheckCif

FinalCif can help you doing checkcif. Three options are available:

  • Online with html report

  • Online with pdf report

  • Offline with your local PLATON installation

The two online option send the CIF to the IUCr server https://checkcif.iucr.org/ and do a CheckCif run there. The offline option will never send the CIF anywhere. It runs on your own computer, but PLATON has to be installed and reachable by the systems PATH variable. any Checkcif can be performes with or without structure factors (hkl data). Without structure factors has the advantage of beeing fast, but the resulting ckecks are far less deeply.

_images/finalcif_checkcif.png

Results from a checkcif run.

Validation Response Forms

Sometimes you have to explain certain alerts from CheckCif. For example rearding the experiment resolution. This is done via validation response forms. FinalCif has a convenient method to do so. After an Online CheckCif with structure factors you have the option to click on “Edit Response Forms”. Ther you have the possibility to reply to A and B level alerts and save them to the CIF:

_images/finalcif_responses.png

Validation response form editor.


A resulting response form:

_images/response_cell.png

A single response form in the FinalCif main table.

Report Document

FinalCif is able to render a nice looking report document as MS Word format from the information contained in the CIF. For a complete report, you have to finish the CIF first. It is also advisable to deposit the file before the report generation in order to have the CCDC number listed in the report text.

_images/finalcif_report.png

A report document example.

CCDC Number

There are two ways of introducing the CCDC number into the .cif file:

  • Edit the ‘CCDC Number’ field in the top of FinalCif. The number will be saved in the key ‘_database_code_depnum_ccdc_archive’.

  • Drag&Drop the deposition response email from the CCDC (in EML format) into the work folder and reload the .cif file.

Picture

FinalCif can add a picture of your structure to the report document.

  • Either by previously performing an html or local checkcif. Then it automatically adds a picture from the checkcif report, as in the example above.

  • Or you can add any other picture with the “Picture for Tables” button.

Customizing the Report

_images/report_options.png

Report options with two templates.

Do you have specific expectations regarding the appearance of the structure report? With self-defined templates this is possible in FinalCif. You can find example templates at https://github.com/dkratzert/FinalCif. It is easier to change them than to create them from scratch.

The templates are an ordinary MS Word document (more specific: Office Open XML, https://de.wikipedia.org/wiki/Office_Open_XML) So you can use them with MS Word, Openoffice or Libre Office abd others.

FinalCif uses the Jinja2 template language to exchange specific instructions in the templates with values from the CIF file and other precalculated information.

In the templates, you have two different types of information to add:

  1. A variable, starting with {{ and ending with }}, for example: {{ a_variable }} This would insert the content of the variable at this point in the document during the report generation.

  2. A block, starting with {% and ending with %}, for example:

Foo bar {% if a_variable %} Put this text here {% endif %} Some other text.

This would put the text enclosed in the block into the document depending if either a_variable has a value or not. The second possibility for blocks is to iterate over the values of a Python dictionary:

{% for atom in atoms %}
   {{ atom.label }}
{% enfor %}

Produces a list of all atom names in a CIF. If you need a table, {%tr foo %} is used to generate table rows.

Data Available for the Report

'cif'                   : Gives you access to the full CIF information, use it like
                          {{ cif._exptl_crystal_density_diffrn }}
'options'               : A dictionary with {'without_h': True, 'atoms_table': True,
                          'text': True, 'bonds_table': True},
'space_group'           : The space group formated as formula object
'structure_figure'      : a picture selected with the 'Picture for Report' button
'crystallization_method': The value of '_exptl_crystal_recrystallization_method'
'sum_formula'           : The html formatted version of '_chemical_formula_sum' with
                          subscript numbers
'itnum'                 : the space group number from the international tables
'crystal_size'          : The crystal size as X x Y x Z
'crystal_colour'        : The crystal colour
'crystal_shape'         : The crystal shape
'radiation'             : The radiation type used like MoK_alpha
'wavelength'            : The wavelength in nm
'theta_range'           : The theta range
'diffr_type'            : The measurement device type
'diffr_device'          : The measurement device
'diffr_source'          : The radiation source
'monochromator'         : The monochromator
'detector'              : The detector model
'lowtemp_dev'           : The low-temperature device
'index_ranges'          : The preformatted index ranges
'indepentent_refl'      : The number of independent reflections
'r_int'                 : The r_int of the data
'r_sigma'               : The r_sigma of the data
'completeness'          : The completeness of the data
'theta_full'            : The resolution of the dataset in degree theta
'data'                  : the value of '_refine_ls_number_reflns'
'restraints'            : The value of '_refine_ls_number_restraints'
'parameters'            : The value of '_refine_ls_number_parameters'
'goof'                  : The value of '_refine_ls_goodness_of_fit_ref'
'ls_R_factor_gt'        : The value of '_refine_ls_R_factor_gt'
'ls_wR_factor_gt'       : The value of '_refine_ls_wR_factor_gt'
'ls_R_factor_all'       : The value of '_refine_ls_R_factor_all'
'ls_wR_factor_ref'      : The value of '_refine_ls_wR_factor_ref'
'diff_dens_min'         : The minimum residual density in e/A^3
'diff_dens_max'         : The maximum residual density in e/A^3
'exti'                  : The extinction coefficient
'flack_x'               : The value of the flack X parameter
'integration_progr'     : The name of the integration program used
'abstype'               : The value of '_exptl_absorpt_correction_type'
'abs_details'           : The name of the absortion correction program used
'solution_method'       : The structure solution method used
'solution_program'      : The name of the structure solution program
'refinement_prog'       : The name of the refinement program
'atomic_coordinates'    : The atomic coordinates
'bonds'                 : The bonds with lengths
'angles'                : The bond angles
'ba_symminfo'           : The symmetry operations used to generate equivalent atoms in the
                          angles list
'torsions'              : The torsion angles
'torsion_symminfo'      : The symmetry operations used to generate equivalent atoms in the
                          torsion angles list
'hydrogen_bonds'        : The hydrogen bonds (in case there are some defined with HTAB)
'hydrogen_symminfo'     : The symmetry operations used to generate equivalent atoms in the
                          hydrogen bonds list
'literature'            : A list of citations to the above used programs

This information from the ‘cif’ variable can also be useful:

'res_file_data'          : The SHELX res file text
'is_centrosymm'          : It true if the space group of the structure is centrosymmetric
'atoms'                  : The list of atoms with 'label', 'type', 'x', 'y', 'z', 'part',
                           'occ', 'u_eq'
'hydrogen_atoms_present' : Is true if hydrogen atoms are present in the structure
'disorder_present'       : Is true if atoms in parts are present in the structure
'cell'                   : The unit cell
'bonds'                  : The list of bonds as 'label1', 'label2', 'dist', 'symm'
'angles'                 : The list of angles as 'label1', 'label2', 'label3', 'angle_val',
                           'symm1', 'symm2'
'torsion_angles'         : The list of torsion angles as 'label1', 'label2', 'label3', 'label4',
                           'torsang', 'symm1', 'symm2', 'symm3', 'symm4'
'hydrogen_bonds'         : The list of hydrogen atoms involved in HTAB listings as 'label_d',
                           'label_h', 'label_a', 'dist_dh', 'dist_ha', 'dist_da', 'angle_dha',
                            'symm'
'test_res_checksum'      : True if the checksum of the SHELX .res file fits to the file content.
'test_hkl_checksum'      : True if the checksum of the SHELX .hkl file fits to the file content.

The above is not limited to the templates of FinalCif. It is also possible to insert template tags into any other Word document and replace them with values from a CIF file. There are no limits to the imagination.

Further information for programmers: https://docxtpl.readthedocs.io/en/latest/

Database Deposition

In order to archive CIF files and to make them publicly available, there are two major databases for deposition. The most commonly used is the Cambridge Structural Database (CSD, https://www.ccdc.cam.ac.uk/). A younger database is the Crystallography Open Database (COD, https://www.crystallography.net/cod/). While the CSD ist a commercial product with an annual pricing, the COD is open for everyone.

FinalCif has two buttons for depositing in the respective database, but they behave very differently. The button for the CSD (“CCDC Deposit”) only points to the CSD website, while the button for the COD (“COD Deposit”) opens an upload interface in FinalCif.

_images/deposit_v86.png

The COD deposition interface

The COD interface has three major options: “personal communication”, “prepublication” and “already published” Before the first upload attempt, you have to signup for an account at http://crystallography.net/cod/. With that username, password and email adress, you can use the FinalCif interface. On the left hand side, you see a list of already deposited structures, unless you entered username/password and refreshed the list.

personal communication (private communication)

The personal communication acts like a publication in a journal. The CIF immediately becomes publicly available. Therefore, you must add at least one author name to the submitted CIF in the FinalCif author editor if there is not already an author in the CIF. This or these author(s) must not be a communication author, but a communication author can be added additionally.

prepublication

The prepublication option is the choice for deposition prior to a publication in a scientific journal. As with personal communications, you have to submit at least one author. Additionally, you have to give a journal name and the hold period until the COD will contact you in order to ask about the current status of the publication. During the hold period, The CIF is only accessible by the depositor unless it is either published in a journal or as personal communication in the COD.

already published

The already published option is for structures that have already been published in a journal and which have a DOI (https://www.doi.org/). In order to deposit an already published CIF, you have to insert the publication DOI into the respective field and click “Get Citation”. After the publication information was fetched, you can upload the CIF.

Running from Source Code

In case you want to play with the source code and make your own modifications to FinalCif, get the code from Github.

In order to run FinalCif from the source code directly, you need to install Python3 >= 3.7 but >= 3.9 is advisable: https://www.python.org/

Until now, I was just too lazy to build proper Linux packages and therefore only single-file executables made with pyinstaller <https://www.pyinstaller.org/> exist. They are large and run sub-optimal in different Linux distributions.

But for Ubuntu, there is an installer script that does all steps necessary for an installation from source automatically. Apart from the Python installation, the script should work in any Linux or MacOS distribution:

First go into the directory where you like to have FinalCif, e.g.:

cd /home/username/Downloads

Load the script:

wget https://raw.githubusercontent.com/dkratzert/FinalCif/master/scripts/finalcif-start.sh

Make it executable:

chmod u+x ./finalcif-start.sh

Install Python3.9:

./finalcif-start.sh -pyinst

Install FinalCif:

./finalcif-start.sh -install

Run FinalCif:

./finalcif-start.sh

Manual install from source

Clone the repository from GitHub:

git clone https://github.com/dkratzert/FinalCif.git
cd FinalCif

Create a virtual environment and activate it:

C:\Python39\python3.exe -m venv venv
venv\Scripts\activate.bat
(in Linux: source venv/bin/activate)

After activation, install all necessary packages using pip:

pip install -r requirements.txt

I am always open for suggestions by users. Please tell me if something does not work as expected!

FinalCif uses the great gemmi CIF parser for all CIF reading and writing operations.

Homepage

Back to the FinalCif home page