formats

Structure format read/write and conversion helpers.

bcif2cif(bcif_file)

Convert a binary CIF (bcif) file to a CIF string.

Parameters:

Name	Type	Description	Default
bcif_file	Path	Path to the binary CIF file.	required

Returns:

Type	Description
str	A string containing the CIF representation of the structure.

bcif2structure(bcif_file)

Read a binary CIF (bcif) file and return a gemmi Structure object.

This is slower than other formats because gemmi does not support reading bcif files directly. So we convert it to a cif string first using mmcif package and then read the cif string using gemmi.

Parameters:

Name	Type	Description	Default
bcif_file	Path	Path to the binary CIF file.	required

Returns:

Type	Description
Structure	A gemmi Structure object representing the structure in the bcif file.

bcifgz2structure(bcif_gz_file)

Read a binary CIF (bcif) gzipped file and return a gemmi Structure object.

This is slower than other formats because gemmi does not support reading bcif files directly. So we first gunzip the file to a temporary location, convert it to a cif string using mmcif package, and then read the cif string using gemmi.

Parameters:

Name	Type	Description	Default
bcif_gz_file	Path	Path to the binary CIF gzipped file.	required

Returns:

Type	Description
Structure	A gemmi Structure object representing the structure in the bcif.gz file.

gunzip_file(gz_file, output_file=None, keep_original=True)

Unzip a .gz file.

Parameters:

Name	Type	Description	Default
gz_file	Path	Path to the .gz file.	required
output_file	Path | None	Optional path to the output unzipped file. If None, the .gz suffix is removed from gz_file.	None
keep_original	bool	Whether to keep the original .gz file. Default is True.	True

Returns:

Type	Description
Path	Path to the unzipped file.

Raises:

Type	Description
ValueError	If output_file is None and gz_file does not end with .gz.

read_structure(file)

Read a structure from a file.

Parameters:

Name	Type	Description	Default
file	Path	Path to the input structure file. See StructureFileExtensions for supported extensions.	required

Returns:

Type	Description
Structure	A gemmi Structure object representing the structure in the file.

read_structure_as_cif_block(file)

Read a structure file as a raw mmCIF block when possible.

Useful because Gemmi structure objects do not preserve all mmCIF categories.

Parameters:

Name	Type	Description	Default
file	Path	Path to an input file intended to be readable by gemmi.cif.read_file.	required

Returns:

Type	Description
Block | None	The sole mmCIF block from the file, or None when the file cannot be
Block | None	parsed as mmCIF or contains no blocks.

structure2bcif(structure, bcif_file, uniprot_chain_mappings=None)

Write a gemmi Structure object to a binary CIF (bcif) file.

This is slower than other formats because gemmi does not support writing bcif files directly. So we convert it to a cif string first using gemmi and then convert cif to bcif using mmcif package.

Parameters:

Name	Type	Description	Default
structure	Structure	The gemmi Structure object to write.	required
bcif_file	Path	Path to the output binary CIF file.	required
uniprot_chain_mappings	UniprotChainMappings | None	Optional UniProt chain mappings in label system to emit as _pdbx_sifts_unp_segments for mmCIF outputs.	None

structure2bcifgz(structure, bcif_gz_file, uniprot_chain_mappings=None)

Write a gemmi Structure object to a binary CIF gzipped (bcif.gz) file.

This is slower than other formats because gemmi does not support writing bcif files directly. So we convert it to a cif string first using gemmi and then convert cif to bcif using mmcif package. Finally, we gzip the bcif file.

Parameters:

Name	Type	Description	Default
structure	Structure	The gemmi Structure object to write.	required
bcif_gz_file	Path	Path to the output binary CIF gzipped file.	required
uniprot_chain_mappings	UniprotChainMappings | None	Optional UniProt chain mappings in label system to emit as _pdbx_sifts_unp_segments for mmCIF outputs.	None

structure2cifgz(structure, uniprot_chain_mappings=None)

Render a gemmi Structure as gzipped mmCIF bytes.

Parameters:

Name	Type	Description	Default
structure	Structure	The gemmi Structure object to render.	required
uniprot_chain_mappings	UniprotChainMappings | None	Optional UniProt chain mappings in label system to emit as _pdbx_sifts_unp_segments for mmCIF outputs.	None

Returns:

Type	Description
bytes	Gzipped mmCIF bytes.

write_structure(structure, path, uniprot_chain_mappings=None)

Write a gemmi structure to a file.

Parameters:

Name	Type	Description	Default
structure	Structure	The gemmi structure to write.	required
path	Path	The file path to write the structure to. The format depends on the file extension. See StructureFileExtensions for supported extensions.	required
uniprot_chain_mappings	UniprotChainMappings | None	Optional UniProt chain mappings in label system to emit as _pdbx_sifts_unp_segments for mmCIF outputs.	None

Raises:

Type	Description
ValueError	If the file extension is not supported.