.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples/gallery/structure/biological_assembly.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_gallery_structure_biological_assembly.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_gallery_structure_biological_assembly.py:


Biological assembly of a structure
==================================

Often the biological assembly (or biological unit) reveals the complete
picture of a protein function, may it be a viral capsid or a
microfilament.
However, the usual atom records in an *PDB* or *PDBx* file usually
describe only the asymmetric unit.
For large complexes the asymmetric unit may only display one monomer or
one small subcomplex.
Multiple copies of the asymmetric unit must be geometrically arranged to
build the assembly.

In order to get the entire assembly, the *PDBx* files provided by the
*RCSB PDB* (either in *CIF* or *BinaryCIF* format) contain the following
fields:

    - ``pdbx_struct_assembly`` - General information about the
      assemblies
    - ``pdbx_struct_assembly_prop`` - More specific properties
    - ``pdbx_struct_oper_list`` - A list of tranformation operations
    - ``pdbx_struct_assembly_gen`` - Which tranformation operations from
      ``pdbx_struct_oper_list`` need to be applied for the assemblies

More information about biological assemblies is provided by the
*RCSB PDB* on
`this page <https://pdb101.rcsb.org/learn/guide-to-understanding-pdb-data/biological-assemblies>`_.

In this example, we will create the complete biological assembly of the
capsid from the *Sulfolobus turreted icosahedral virus*
- a hetero 1080-mer!

At first we will check, which assemblies are available to us.

.. GENERATED FROM PYTHON SOURCE LINES 36-55

.. code-block:: Python


    # Code source: Patrick Kunzmann
    # License: BSD 3 clause

    from tempfile import NamedTemporaryFile
    import biotite.structure as struc
    import biotite.structure.io.pdbx as pdbx
    import biotite.structure.io as strucio
    import biotite.database.rcsb as rcsb


    pdbx_file = pdbx.BinaryCIFFile.read(rcsb.fetch("3J31", "bcif"))

    assemblies = pdbx.list_assemblies(pdbx_file)
    print("ID    name")
    print()
    for assembly_id, name in assemblies.items():
        print(f"{assembly_id:2}    {name}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    ID    name

    1     complete icosahedral assembly
    2     icosahedral asymmetric unit
    3     icosahedral pentamer
    4     icosahedral 23 hexamer
    5     icosahedral asymmetric unit, std point frame




.. GENERATED FROM PYTHON SOURCE LINES 56-64

``'complete icosahedral assembly'`` sounds good.
In fact, often the first assembly is the complete one.
Hence, the :func:`get_assembly()` function builds the first assembly
by default.
Since we know the ID we want (``'1'``), we will provide it to this
function anyway.
It returns the chosen assembly as :class:`AtomArray`.
Note that the assembly ID is a string, not an integer.

.. GENERATED FROM PYTHON SOURCE LINES 64-68

.. code-block:: Python


    biological_unit = pdbx.get_assembly(pdbx_file, assembly_id="1", model=1)
    print("Number of protein chains:", struc.get_chain_count(biological_unit))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Number of protein chains: 1080




.. GENERATED FROM PYTHON SOURCE LINES 69-72

Now we could do some analysis on the biological unit.
But for this example we will simply save the entire assembly as *PDB*
file for later visualization.

.. GENERATED FROM PYTHON SOURCE LINES 72-79

.. code-block:: Python


    # For brevity, save only CA atoms to file for visualization
    biological_unit = biological_unit[biological_unit.atom_name == "CA"]
    temp = NamedTemporaryFile(suffix=".cif")
    strucio.save_structure(temp.name, biological_unit)
    # Visualization with PyMOL...

    temp.close()


.. image-sg:: /examples/gallery/structure/images/sphx_glr_biological_assembly_001.png
   :alt: biological assembly
   :srcset: /examples/gallery/structure/images/sphx_glr_biological_assembly_001.png
   :class: sphx-glr-single-img






.. _sphx_glr_download_examples_gallery_structure_biological_assembly.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: biological_assembly.ipynb <biological_assembly.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: biological_assembly.py <biological_assembly.py>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_