iphasimulator.visualisation.visualiser
======================================

.. py:module:: iphasimulator.visualisation.visualiser

.. autoapi-nested-parse::

   PHA visualisation utilities.
   This module contains helper functions for visualising available PHA monomer
   units and generated polymers.

   It currently uses RDKit to render 2D molecular depictions from SMILES strings.



Functions
---------

.. autoapisummary::

   iphasimulator.visualisation.visualiser.load_available_PHA_monomers
   iphasimulator.visualisation.visualiser.smiles_to_mol
   iphasimulator.visualisation.visualiser.plot_available_PHA_monomers
   iphasimulator.visualisation.visualiser.show_available_PHA_monomers
   iphasimulator.visualisation.visualiser.show_PHA_monomer
   iphasimulator.visualisation.visualiser.load_polymer_smiles
   iphasimulator.visualisation.visualiser.plot_available_PHA_polymers
   iphasimulator.visualisation.visualiser.show_available_PHA_polymers
   iphasimulator.visualisation.visualiser.show_PHA_polymer


Module Contents
---------------

.. py:function:: load_available_PHA_monomers(residue_codes_csv)

   Load available PHA monomer units from residue_codes.csv.

   :param residue_codes_csv: Path to the residue code CSV file.
   :type residue_codes_csv: str or pathlib.Path

   :returns: List of ``(PHA_type, smiles)`` tuples for each available mainchain
             monomer unit.
   :rtype: list[tuple[str, str]]


.. py:function:: smiles_to_mol(smiles, name=None)

   Convert a SMILES string into an RDKit molecule.

   :param smiles: SMILES string to convert.
   :type smiles: str
   :param name: Optional molecule name used only for clearer error messages.
   :type name: str, optional

   :returns: RDKit molecule object.
   :rtype: rdkit.Chem.rdchem.Mol


.. py:function:: plot_available_PHA_monomers(residue_codes_csv='structure_database/residue_codes.csv', output_file='available_PHA_monomers.png', mols_per_row=4, image_size=(300, 220))

   Plot all available PHA monomer units from residue_codes.csv.
   The function reads the mainchain monomer SMILES for each registered PHA
   type, converts each SMILES string to an RDKit molecule and writes a grid
   image to disk.

   :param residue_codes_csv: Path to residue_codes.csv.
   :type residue_codes_csv: str or pathlib.Path, optional
   :param output_file: Path where the output image should be written.
   :type output_file: str or pathlib.Path, optional
   :param mols_per_row: Number of structures shown per row.
   :type mols_per_row: int, optional
   :param image_size: Size of each molecule panel in pixels.
   :type image_size: tuple[int, int], optional

   :returns: Path to the generated image.
   :rtype: pathlib.Path


.. py:function:: show_available_PHA_monomers(residue_codes_csv='structure_database/residue_codes.csv', mols_per_row=4)

   Display all available PHA monomer units.



.. py:function:: show_PHA_monomer(PHA_type, residue_codes_csv='structure_database/residue_codes.csv', image_size=(300, 220))

   Display one PHA monomer structure from residue_codes.csv.

   :param PHA_type: PHA type to display, e.g. "3HB" or "4HB".
   :type PHA_type: str
   :param residue_codes_csv: Path to residue_codes.csv.
   :type residue_codes_csv: str or pathlib.Path, optional
   :param image_size: Size of the rendered molecule image.
   :type image_size: tuple[int, int], optional

   :returns: Rendered RDKit molecule image.
   :rtype: PIL.Image.Image


.. py:function:: load_polymer_smiles(polymer_smiles_csv)

   Load polymer SMILES from polymer_smiles.csv.

   :param polymer_smiles_csv: Path to polymer_smiles.csv.
   :type polymer_smiles_csv: str or pathlib.Path

   :returns: List of ``(polymer_name, smiles)`` tuples.
   :rtype: list[tuple[str, str]]


.. py:function:: plot_available_PHA_polymers(polymer_smiles_csv='structure_database/polymer_smiles.csv', output_file='available_PHA_polymers.png', mols_per_row=3, image_size=(500, 280))

   Plot all available PHA polymers from polymer_smiles.csv.


.. py:function:: show_available_PHA_polymers(polymer_smiles_csv='structure_database/polymer_smiles.csv', mols_per_row=3, image_size=(500, 280))

   Display all available PHA polymers from polymer_smiles.csv.


.. py:function:: show_PHA_polymer(polymer_name, polymer_smiles_csv='structure_database/polymer_smiles.csv', image_size=(900, 300))

   Display one PHA polymer structure from polymer_smiles.csv.