proteusPy.DisulfideList

   1"""
   2This module is part of the proteusPy package, a Python package for 
   3the analysis and modeling of protein structures, with an emphasis on disulfide bonds.
   4This work is based on the original C/C++ implementation by Eric G. Suchanek. \n
   5
   6The module provides the implmentation and interface for the [DisulfideList](#DisulfideList)
   7object, used extensively by Disulfide class.
   8
   9Author: Eric G. Suchanek, PhD
  10Last revision: 3/18/2024 -egs-
  11"""
  12
  13try:
  14    # Check if running in Jupyter
  15    shell = get_ipython().__class__.__name__
  16    if shell == "ZMQInteractiveShell":
  17        from tqdm.notebook import tqdm
  18    else:
  19        from tqdm import tqdm
  20except NameError:
  21    from tqdm import tqdm
  22
  23from collections import UserList
  24from pathlib import Path
  25
  26import numpy as np
  27import pandas
  28import plotly.express as px
  29import plotly.graph_objects as go
  30import pyvista as pv
  31from Bio.PDB import PDBParser
  32from plotly.subplots import make_subplots
  33
  34import proteusPy
  35from proteusPy import Disulfide
  36from proteusPy.atoms import *
  37from proteusPy.ProteusGlobals import MODEL_DIR, PBAR_COLS, WINSIZE
  38from proteusPy.utility import get_jet_colormap, grid_dimensions
  39
  40# Set the figure sizes and axis limits.
  41DPI = 220
  42WIDTH = 6.0
  43HEIGHT = 6.0
  44TORMIN = -179.0
  45TORMAX = 180.0
  46
  47
  48Torsion_DF_Cols = [
  49    "source",
  50    "ss_id",
  51    "proximal",
  52    "distal",
  53    "chi1",
  54    "chi2",
  55    "chi3",
  56    "chi4",
  57    "chi5",
  58    "energy",
  59    "ca_distance",
  60    "cb_distance",
  61    "phi_prox",
  62    "psi_prox",
  63    "phi_dist",
  64    "psi_dist",
  65    "torsion_length",
  66    "rho",
  67]
  68
  69Distance_DF_Cols = [
  70    "source",
  71    "ss_id",
  72    "proximal",
  73    "distal",
  74    "energy",
  75    "ca_distance",
  76    "cb_distance",
  77]
  78
  79
  80class DisulfideList(UserList):
  81    """
  82    The class provides a sortable list for Disulfide objects.
  83    Indexing and slicing are supported, as well as typical list operations like
  84    ``.insert()``, ``.append()`` and ``.extend().`` The DisulfideList object must be initialized
  85    with an iterable (tuple, list) and a name. Sorting is keyed by torsional energy.
  86
  87    The class can also render Disulfides to a pyVista window using the
  88    [display()](#DisulfideList.display) and [display_overlay()](#DisulfideList.display_overlay)methods.
  89    See below for examples.\n
  90
  91    Examples:
  92    >>> from proteusPy import Disulfide, DisulfideLoader, DisulfideList, Load_PDB_SS
  93
  94    Instantiate some variables. Note: the list is initialized with an iterable and a name (optional)
  95
  96    >>> SS = Disulfide('tmp')
  97
  98    The list is initialized with an iterable, a name and resolution. Name and resolution
  99    are optional.
 100    >>> SSlist = DisulfideList([],'ss', -1.0)
 101
 102    Load the database.
 103    >>> PDB_SS = Load_PDB_SS(verbose=False, subset=True)
 104
 105    Get the first disulfide via indexing.
 106    >>> SS = PDB_SS[0]
 107
 108    # assert str(SS) == "<Disulfide 4yys_22A_65A, Source: 4yys, Resolution: 1.35 Å>"
 109
 110    >>> SS4yys = PDB_SS['4yys']
 111
 112    # assert str(SS4yys) == "[<Disulfide 4yys_22A_65A, Source: 4yys, Resolution: 1.35 Å>, <Disulfide 4yys_56A_98A, Source: 4yys, Resolution: 1.35 Å>, <Disulfide 4yys_156A_207A, Source: 4yys, Resolution: 1.35 Å>]"
 113
 114    Make some empty disulfides.
 115    >>> ss1 = Disulfide('ss1')
 116    >>> ss2 = Disulfide('ss2')
 117
 118    Make a DisulfideList containing ss1, named 'tmp'
 119    >>> sslist = DisulfideList([ss1], 'tmp')
 120    >>> sslist.append(ss2)
 121
 122    Extract the first disulfide
 123    >>> ss1 = PDB_SS[0]
 124
 125    # assert str(ss1.pprint_all()) == "<Disulfide 4yys_22A_65A, Source: 4yys, Resolution: 1.35 Å\n Proximal Chain fullID: <('4yys', 0, 'A', (' ', 22, ' '))> Distal Chain fullID: <('4yys', 0, 'A', (' ', 65, ' '))>\nProximal Coordinates:\n   N: <Vector -2.36, -20.48, 5.21>\n   Cα: <Vector -2.10, -19.89, 3.90>\n   C: <Vector -1.12, -18.78, 4.12>\n   O: <Vector -1.30, -17.96, 5.03>\n   Cβ: <Vector -3.38, -19.31, 3.32>\n   Sγ: <Vector -3.24, -18.40, 1.76>\n   Cprev <Vector -2.67, -21.75, 5.36>\n   Nnext: <Vector -0.02, -18.76, 3.36>\n Distal Coordinates:\n   N: <Vector -0.60, -18.71, -1.62>\n   Cα: <Vector -0.48, -19.10, -0.22>\n   C: <Vector 0.92, -19.52, 0.18>\n   O: <Vector 1.10, -20.09, 1.25>\n   Cβ: <Vector -1.48, -20.23, 0.08>\n   Sγ: <Vector -3.22, -19.69, 0.18>\n   Cprev <Vector -0.73, -17.44, -2.01>\n   Nnext: <Vector 1.92, -19.18, -0.63>\n<BLANKLINE>\n Proximal Internal Coords:\n   N: <Vector -0.41, 1.40, -0.00>\n   Cα: <Vector 0.00, 0.00, 0.00>\n   C: <Vector 1.50, 0.00, 0.00>\n   O: <Vector 2.12, 0.71, -0.80>\n   Cβ: <Vector -0.50, -0.70, -1.25>\n   Sγ: <Vector 0.04, -2.41, -1.50>\n   Cprev <Vector -2.67, -21.75, 5.36>\n   Nnext: <Vector -0.02, -18.76, 3.36>\nDistal Internal Coords:\n   N: <Vector 1.04, -5.63, 1.17>\n   Cα: <Vector 1.04, -4.18, 1.31>\n   C: <Vector 1.72, -3.68, 2.57>\n   O: <Vector 1.57, -2.51, 2.92>\n   Cβ: <Vector -0.41, -3.66, 1.24>\n   Sγ: <Vector -1.14, -3.69, -0.43>\n   Cprev <Vector -0.73, -17.44, -2.01>\n   Nnext: <Vector 1.92, -19.18, -0.63>\n Χ1-Χ5: 174.63°, 82.52°, -83.32°, -62.52° -73.83°, 138.89°, 1.70 kcal/mol\n Cα Distance: 4.50 Å\n Torsion length: 231.53 deg>"
 126
 127    Get a list of disulfides via slicing
 128    >>> subset = DisulfideList(PDB_SS[0:10],'subset')
 129
 130    Display the subset disulfides overlaid onto the same coordinate frame,
 131    (proximal N, Ca, C').
 132
 133    The disulfides are colored individually to facilitate inspection.
 134
 135    >>> subset.display_overlay()
 136    """
 137
 138    def __init__(self, iterable, id: str, res=-1.0, quiet=True):
 139        """
 140        Initialize the DisulfideList
 141
 142        :param iterable: an iterable e.g. []
 143        :type iterable: iterable
 144        :param id: Name for the list
 145        :type id: str
 146
 147        Example:
 148        >>> from proteusPy import DisulfideList, Disulfide
 149
 150        Initialize some empty disulfides.
 151        >>> ss1 = Disulfide('ss1')
 152        >>> ss2 = Disulfide('ss2')
 153        >>> ss3 = Disulfide('ss3')
 154
 155        Make a list containing the disulfides.
 156        >>> sslist = DisulfideList([ss1, ss2], 'sslist')
 157        >>> sslist
 158        [<Disulfide ss1, Source: 1egs, Resolution: -1.0 Å>, <Disulfide ss2, Source: 1egs, Resolution: -1.0 Å>]
 159        >>> sslist.append(ss3)
 160        >>> sslist
 161        [<Disulfide ss1, Source: 1egs, Resolution: -1.0 Å>, <Disulfide ss2, Source: 1egs, Resolution: -1.0 Å>, <Disulfide ss3, Source: 1egs, Resolution: -1.0 Å>]
 162        """
 163
 164        super().__init__(self.validate_ss(item) for item in iterable)
 165
 166        self.pdb_id = id
 167        self.quiet = quiet
 168        total = 0
 169        count = 0
 170
 171        if res == -1:
 172            for ss in iterable:
 173                if ss.resolution is not None:
 174                    total += ss.resolution
 175                    count += 1
 176            if count != 0:
 177                self.res = total / count
 178            else:
 179                self.res = -1.0
 180        else:
 181            self.res = res
 182
 183    def __getitem__(self, item):
 184        """
 185        Retrieve a disulfide from the list. Internal only.
 186
 187        :param item: Index or slice
 188        :return: Sublist
 189        """
 190        if isinstance(item, slice):
 191            indices = range(*item.indices(len(self.data)))
 192            name = self.data[0].pdb_id
 193            sublist = [self.data[i] for i in indices]
 194            return DisulfideList(sublist, name)
 195        return UserList.__getitem__(self, item)
 196
 197    def __setitem__(self, index, item):
 198        self.data[index] = self.validate_ss(item)
 199
 200    # Rendering engine calculates and instantiates all bond
 201    # cylinders and atomic sphere meshes. Called by all high level routines
 202
 203    def _render(self, style, panelsize=256) -> pv.Plotter:
 204        """
 205        Display a window showing the list of disulfides in the given style.
 206        :param style: one of 'cpk', 'bs', 'sb', 'plain', 'cov', 'pd'
 207        :return: Window in the relevant style
 208        """
 209        ssList = self.data
 210        name = self.id
 211        tot_ss = len(ssList)  # number off ssbonds
 212        rows, cols = grid_dimensions(tot_ss)
 213        winsize = (panelsize * cols, panelsize * rows)
 214
 215        pl = pv.Plotter(window_size=winsize, shape=(rows, cols))
 216        i = 0
 217
 218        for r in range(rows):
 219            for c in range(cols):
 220                pl.subplot(r, c)
 221                if i < tot_ss:
 222                    # ss = Disulfide()
 223                    ss = ssList[i]
 224                    src = ss.pdb_id
 225                    enrg = ss.energy
 226                    title = f"{src} {ss.proximal}{ss.proximal_chain}-{ss.distal}{ss.distal_chain}: E: {enrg:.2f}, Cα: {ss.ca_distance:.2f} Å, Tors: {ss.torsion_length:.2f}°"
 227                    pl.add_title(title=title, font_size=FONTSIZE)
 228                    ss._render(
 229                        pl,
 230                        style=style,
 231                        bondcolor=BOND_COLOR,
 232                        bs_scale=BS_SCALE,
 233                        spec=SPECULARITY,
 234                        specpow=SPEC_POWER,
 235                    )
 236                i += 1
 237        return pl
 238
 239    @property
 240    def Average_Distance(self):
 241        """
 242        Return the Average distance (Å) between the atoms in the list.
 243
 244        :return: Average distance (Å) between all atoms in the list
 245
 246        """
 247        sslist = self.data
 248        tot = len(sslist)
 249        cnt = 1
 250
 251        total = 0.0
 252        for ss1 in sslist:
 253            for ss2 in sslist:
 254                if ss2 == ss1:
 255                    continue
 256                total += ss1.Distance_RMS(ss2)
 257                cnt += 1
 258
 259        return total / cnt
 260
 261    @property
 262    def Average_Energy(self):
 263        """
 264        Return the Average energy (kcal/mol) for the Disulfides in the list.
 265
 266        :return: Average energy (kcal/mol) between all atoms in the list
 267
 268        """
 269        sslist = self.data
 270        tot = len(sslist)
 271
 272        total = 0.0
 273        for ss1 in sslist:
 274            total += ss1.energy
 275
 276        return total / tot
 277
 278    @property
 279    def Average_Conformation(self):
 280        """
 281        Return the Average conformation for the Disulfides in the list.
 282
 283        :return: Average conformation: [x1, x2, x3, x4, x5]
 284        """
 285
 286        sslist = self.data
 287        tot = len(sslist)
 288
 289        tors = self.build_torsion_df()
 290
 291        res = np.zeros(5)
 292
 293        for ss, i in zip(sslist, range(tot)):
 294            res += ss.torsion_array
 295
 296        return res / tot
 297
 298    def append(self, item):
 299        """
 300        Append the list with item
 301
 302        :param item: Disulfide to add
 303        :type item: Disulfide
 304        """
 305        self.data.append(self.validate_ss(item))
 306
 307    @property
 308    def Average_Resolution(self) -> float:
 309        """
 310        Compute and return the average structure resolution for the given list.
 311
 312        :return: Average resolution (A)
 313        """
 314        res = 0.0
 315        cnt = 1
 316
 317        for ss in self.data:
 318            _res = ss.resolution
 319            if _res is not None and _res != -1.0:
 320                res += _res
 321                cnt += 1
 322        return res / cnt if cnt else -1.0
 323
 324    @property
 325    def Average_Torsion_Distance(self):
 326        """
 327        Return the average distance in torsion space (degrees), between all pairs in the
 328        DisulfideList
 329
 330        :return: Torsion Distance (degrees)
 331        """
 332        sslist = self.data
 333        tot = len(sslist)
 334        total = 0
 335        cnt = 1
 336
 337        for ss1 in sslist:
 338            for ss2 in sslist:
 339                if ss2 == ss1:
 340                    continue
 341                total += ss1.Torsion_Distance(ss2)
 342                cnt += 1
 343
 344        return total / cnt
 345
 346    def build_distance_df(self) -> pandas.DataFrame:
 347        """
 348        Create a dataframe containing the input DisulfideList Cα-Cα distance, energy.
 349        This can take several minutes for the entire database.
 350
 351        :return: DataFrame containing Ca distances
 352        :rtype: pandas.DataFrame
 353        """
 354
 355        # create a dataframe with the following columns for the disulfide
 356        # conformations extracted from the structure
 357
 358        SS_df = pandas.DataFrame(columns=Distance_DF_Cols)
 359        sslist = self.data
 360
 361        pbar = tqdm(sslist, ncols=PBAR_COLS)
 362        for ss in pbar:
 363            new_row = [
 364                ss.pdb_id,
 365                ss.name,
 366                ss.proximal,
 367                ss.distal,
 368                ss.energy,
 369                ss.ca_distance,
 370            ]
 371            # add the row to the end of the dataframe
 372            SS_df.loc[len(SS_df.index)] = new_row
 373
 374        return SS_df
 375
 376    def build_torsion_df(self) -> pandas.DataFrame:
 377        """
 378        Create a dataframe containing the input DisulfideList torsional parameters,
 379        Cα-Cα distance, energy, and phi-psi angles. This can take several minutes for the
 380        entire database.
 381
 382        :param SSList: DisulfideList - input list of Disulfides
 383        :return: pandas.Dataframe containing the torsions
 384        """
 385        # create a dataframe with the following columns for the disulfide
 386        # conformations extracted from the structure
 387
 388        SS_df = pandas.DataFrame(columns=Torsion_DF_Cols)
 389        sslist = self.data
 390        if self.quiet or len(sslist) < 100:
 391            pbar = sslist
 392        else:
 393            pbar = tqdm(sslist, ncols=PBAR_COLS, leave=False)
 394
 395        for ss in pbar:
 396            new_row = [
 397                ss.pdb_id,
 398                ss.name,
 399                ss.proximal,
 400                ss.distal,
 401                ss.chi1,
 402                ss.chi2,
 403                ss.chi3,
 404                ss.chi4,
 405                ss.chi5,
 406                ss.energy,
 407                ss.ca_distance,
 408                ss.cb_distance,
 409                ss.psiprox,
 410                ss.psiprox,
 411                ss.phidist,
 412                ss.psidist,
 413                ss.torsion_length,
 414                ss.rho,
 415            ]
 416            # add the row to the end of the dataframe
 417            SS_df.loc[len(SS_df.index)] = new_row
 418
 419        return SS_df
 420
 421    def by_chain(self, chain: str):
 422        """
 423        Return a DisulfideList from the input chain identifier.
 424
 425        :param chain: chain identifier, 'A', 'B, etc
 426        :return: DisulfideList containing disulfides within that chain.
 427        """
 428
 429        reslist = DisulfideList([], chain)
 430        sslist = self.data
 431
 432        for ss in sslist:
 433            pchain = ss.proximal_chain
 434            dchain = ss.distal_chain
 435            if pchain == dchain:
 436                if pchain == chain:
 437                    reslist.append(ss)
 438            else:
 439                print(f"Cross chain SS: {ss.repr_compact}:")
 440        return reslist
 441
 442    def calculate_torsion_statistics(self):
 443        df = self.build_torsion_df()
 444
 445        df_subset = df.iloc[:, 4:]
 446        df_stats = df_subset.describe()
 447
 448        # print(df_stats.head())
 449
 450        mean_vals = df_stats.loc["mean"].values
 451        std_vals = df_stats.loc["std"].values
 452
 453        tor_cols = ["chi1", "chi2", "chi3", "chi4", "chi5", "torsion_length"]
 454        dist_cols = ["ca_distance", "cb_distance", "energy"]
 455        tor_stats = {}
 456        dist_stats = {}
 457
 458        for col in tor_cols:
 459            tor_stats[col] = {"mean": df[col].mean(), "std": df[col].std()}
 460
 461        for col in dist_cols:
 462            dist_stats[col] = {"mean": df[col].mean(), "std": df[col].std()}
 463
 464        tor_stats = pandas.DataFrame(tor_stats, columns=tor_cols)
 465        dist_stats = pandas.DataFrame(dist_stats, columns=dist_cols)
 466
 467        return tor_stats, dist_stats
 468
 469    def display(self, style="sb", light=True, panelsize=512):
 470        """
 471        Display the Disulfide list in the specific rendering style.
 472
 473        :param single: Display the bond in a single panel in the specific style.
 474        :param style:  Rendering style: One of:\n
 475            - 'sb' - split bonds
 476            - 'bs' - ball and stick
 477            - 'cpk' - CPK style
 478            - 'pd' - Proximal/Distal style - Red=proximal, Green=Distal
 479            - 'plain' - boring single color
 480        :light: If True, light background, if False, dark
 481        """
 482        id = self.pdb_id
 483        ssbonds = self.data
 484        tot_ss = len(ssbonds)  # number off ssbonds
 485        avg_enrg = self.Average_Energy
 486        avg_dist = self.Average_Distance
 487        resolution = self.resolution
 488
 489        if light:
 490            pv.set_plot_theme("document")
 491        else:
 492            pv.set_plot_theme("dark")
 493
 494        title = f"<{id}> {resolution:.2f} Å: ({tot_ss} SS), Avg E: {avg_enrg:.2f} kcal/mol, Avg Dist: {avg_dist:.2f} Å"
 495
 496        pl = pv.Plotter()
 497        pl = self._render(style, panelsize)
 498        pl.enable_anti_aliasing("msaa")
 499        pl.add_title(title=title, font_size=FONTSIZE)
 500        pl.link_views()
 501        pl.reset_camera()
 502        pl.show()
 503
 504    def display_torsion_statistics(
 505        self,
 506        display=True,
 507        save=False,
 508        fname="ss_torsions.png",
 509        stats=False,
 510        light=True,
 511    ):
 512        """
 513        Display torsion and distance statistics for a given Disulfide list.
 514
 515        :param display: Whether to display the plot in the notebook. Default is True.
 516        :type display: bool
 517        :param save: Whether to save the plot as an image file. Default is False.
 518        :type save: bool
 519        :param fname: The name of the image file to save. Default is 'ss_torsions.png'.
 520        :type fname: str
 521        :param stats: Whether to return the DataFrame representing the statistics for `self`. Default is False.
 522        :type stats: bool
 523        :param light: Whether to use the 'plotly_light' or 'plotly_dark' template. Default is True.
 524        :type light: bool
 525        :return: None
 526        """
 527        title = f"{self.id}: {self.length} members"
 528
 529        df = self.torsion_df
 530        df_subset = df.iloc[:, 4:]
 531        df_stats = df_subset.describe()
 532
 533        # print(df_stats.head())
 534
 535        mean_vals = df_stats.loc["mean"].values
 536        std_vals = df_stats.loc["std"].values
 537
 538        fig = make_subplots(
 539            rows=2, cols=2, vertical_spacing=0.125, column_widths=[1, 1]
 540        )
 541        fig.update_layout(template="plotly" if light else "plotly_dark")
 542
 543        fig.update_layout(
 544            title={
 545                "text": title,
 546                "xanchor": "center",
 547                # 'y':.9,
 548                "x": 0.5,
 549                "yanchor": "top",
 550            },
 551            width=1024,
 552            height=1024,
 553        )
 554
 555        fig.add_trace(
 556            go.Bar(
 557                x=["X1", "X2", "X3", "X4", "X5"],
 558                y=mean_vals[:5],
 559                name="Torsion Angle,(°) ",
 560                error_y=dict(type="data", array=std_vals[:5], visible=True),
 561            ),
 562            row=1,
 563            col=1,
 564        )
 565
 566        fig.add_trace(
 567            go.Bar(
 568                x=["rho"],
 569                y=[mean_vals[13]],
 570                name="ρ, (°)",
 571                error_y=dict(type="data", array=[std_vals[13]], visible=True),
 572            ),
 573            row=1,
 574            col=1,
 575        )
 576
 577        # Update the layout of the subplot
 578        # Cα N, Cα, Cβ, C', Sγ Å °
 579
 580        fig.update_yaxes(
 581            title_text="Torsion Angle (°)", range=[-200, 200], row=1, col=1
 582        )
 583        fig.update_yaxes(range=[0, 320], row=2, col=2)
 584
 585        # Add another subplot for the mean values of energy
 586        fig.add_trace(
 587            go.Bar(
 588                x=["Strain Energy (kcal/mol)"],
 589                y=[mean_vals[5]],
 590                name="Energy (kcal/mol)",
 591                error_y=dict(
 592                    type="data",
 593                    array=[std_vals[5].tolist()],
 594                    width=0.25,
 595                    visible=True,
 596                ),
 597            ),
 598            row=1,
 599            col=2,
 600        )
 601        fig.update_traces(width=0.25, row=1, col=2)
 602
 603        # Update the layout of the subplot
 604        # fig.update_xaxes(title_text="Energy", row=1, col=2)
 605        fig.update_yaxes(
 606            title_text="kcal/mol", range=[0, 20], row=1, col=2
 607        )  # max possible DSE
 608
 609        # Add another subplot for the mean values of ca_distance
 610        fig.add_trace(
 611            go.Bar(
 612                x=["Cα Distance, (Å)", "Cβ Distance, (Å)"],
 613                y=[mean_vals[6], mean_vals[7]],
 614                name="Cβ Distance (Å)",
 615                error_y=dict(
 616                    type="data",
 617                    array=[std_vals[6].tolist(), std_vals[7].tolist()],
 618                    width=0.25,
 619                    visible=True,
 620                ),
 621            ),
 622            row=2,
 623            col=1,
 624        )
 625        # Update the layout of the subplot
 626        fig.update_yaxes(title_text="Distance (A)", range=[0, 10], row=2, col=1)  #
 627        fig.update_traces(width=0.25, row=2, col=1)
 628
 629        # Add a scatter subplot for torsion length column
 630        fig.add_trace(
 631            go.Bar(
 632                x=["Torsion Length, (Å)"],
 633                y=[mean_vals[12]],
 634                name="Torsion Length, (Å)",
 635                error_y=dict(
 636                    type="data", array=[std_vals[12]], width=0.25, visible=True
 637                ),
 638            ),
 639            row=2,
 640            col=2,
 641        )
 642        # Update the layout of the subplot
 643        fig.update_yaxes(title_text="Torsion Length", range=[0, 350], row=2, col=2)
 644        fig.update_traces(width=0.25, row=2, col=2)
 645
 646        # Update the error bars
 647        fig.update_traces(
 648            error_y_thickness=2,
 649            error_y_color="gray",
 650            texttemplate="%{y:.2f} ± %{error_y.array:.2f}",
 651            textposition="outside",
 652        )  # , row=1, col=1)
 653
 654        if display:
 655            fig.show()
 656        if save:
 657            fig.write_image(Path(fname))
 658
 659        if stats:
 660            return df_stats
 661
 662        return
 663
 664    @property
 665    def distance_df(self) -> pandas.DataFrame:
 666        """
 667        Build and return the distance dataframe for the input list.
 668        This can take considerable time for the entire list.
 669
 670        :return: Dataframe containing the Cα-Cα distances for the given list.
 671
 672        Example:
 673        >>> from proteusPy import Disulfide, Load_PDB_SS, DisulfideList
 674        >>> PDB_SS = Load_PDB_SS()
 675
 676        """
 677        return self.build_distance_df()
 678
 679    def display_overlay(
 680        self,
 681        screenshot=False,
 682        movie=False,
 683        verbose=True,
 684        fname="ss_overlay.png",
 685        light=True,
 686    ):
 687        """
 688        Display all disulfides in the list overlaid in stick mode against
 689        a common coordinate frames. This allows us to see all of the disulfides
 690        at one time in a single view. Colors vary smoothy between bonds.
 691
 692        :param screenshot: Save a screenshot, defaults to False
 693        :param movie: Save a movie, defaults to False
 694        :param verbose: Verbosity, defaults to True
 695        :param fname: Filename to save for the movie or screenshot, defaults to 'ss_overlay.png'
 696        :param light: Background color, defaults to True for White. False for Dark.
 697        """
 698
 699        id = self.pdb_id
 700        ssbonds = self.data
 701        tot_ss = len(ssbonds)  # number off ssbonds
 702        avg_enrg = self.Average_Energy
 703        avg_dist = self.Average_Distance
 704        resolution = self.resolution
 705
 706        res = 100
 707
 708        if tot_ss > 100:
 709            res = 60
 710        if tot_ss > 200:
 711            res = 30
 712        if tot_ss > 300:
 713            res = 8
 714
 715        title = f"<{id}> {resolution:.2f} Å: ({tot_ss} SS), Avg E: {avg_enrg:.2f} kcal/mol, Avg Dist: {avg_dist:.2f} Å"
 716
 717        if light:
 718            pv.set_plot_theme("document")
 719        else:
 720            pv.set_plot_theme("dark")
 721
 722        if movie:
 723            pl = pv.Plotter(window_size=WINSIZE, off_screen=True)
 724        else:
 725            pl = pv.Plotter(window_size=WINSIZE, off_screen=False)
 726
 727        pl.add_title(title=title, font_size=FONTSIZE)
 728        pl.enable_anti_aliasing("msaa")
 729        # pl.add_camera_orientation_widget()
 730        pl.add_axes()
 731
 732        mycol = np.zeros(shape=(tot_ss, 3))
 733        mycol = get_jet_colormap(tot_ss)
 734
 735        # scale the overlay bond radii down so that we can see the individual elements better
 736        # maximum 90% reduction
 737
 738        brad = BOND_RADIUS if tot_ss < 10 else BOND_RADIUS * 0.75
 739        brad = brad if tot_ss < 25 else brad * 0.8
 740        brad = brad if tot_ss < 50 else brad * 0.8
 741        brad = brad if tot_ss < 100 else brad * 0.6
 742
 743        # print(f'Brad: {brad}')
 744        pbar = tqdm(range(tot_ss), ncols=PBAR_COLS)
 745
 746        for i, ss in zip(pbar, ssbonds):
 747            color = [int(mycol[i][0]), int(mycol[i][1]), int(mycol[i][2])]
 748            ss._render(
 749                pl,
 750                style="plain",
 751                bondcolor=color,
 752                translate=False,
 753                bond_radius=brad,
 754                res=res,
 755            )
 756
 757        pl.reset_camera()
 758
 759        if screenshot:
 760            pl.show(auto_close=False)  # allows for manipulation
 761            pl.screenshot(fname)
 762
 763        elif movie:
 764            if verbose:
 765                print(f" -> display_overlay(): Saving mp4 animation to: {fname}")
 766
 767            pl.open_movie(fname)
 768            path = pl.generate_orbital_path(n_points=360)
 769            pl.orbit_on_path(path, write_frames=True)
 770            pl.close()
 771
 772            if verbose:
 773                print(f" -> display_overlay(): Saved mp4 animation to: {fname}")
 774        else:
 775            pl.show()
 776
 777        return
 778
 779    def extend(self, other):
 780        """
 781        Extend the Disulfide list with other.
 782
 783        :param other: extension
 784        :type item: DisulfideList
 785        """
 786
 787        if isinstance(other, type(self)):
 788            self.data.extend(other)
 789        else:
 790            self.data.extend(self.validate_ss(item) for item in other)
 791
 792    def get_by_name(self, name):
 793        """
 794        Returns the Disulfide with the given name from the list.
 795        """
 796        for ss in self.data:
 797            if ss.name == name:
 798                return ss.copy()  # or ss.copy() !!!
 799        return None
 800
 801    def get_chains(self):
 802        """
 803        Return the chain IDs for chains within the given Disulfide.
 804        :return: Chain IDs for given Disulfide
 805        """
 806
 807        res_dict = {"xxx"}
 808        sslist = self.data
 809
 810        for ss in sslist:
 811            pchain = ss.proximal_chain
 812            dchain = ss.distal_chain
 813            res_dict.update(pchain)
 814            res_dict.update(dchain)
 815
 816        res_dict.remove("xxx")
 817
 818        return res_dict
 819
 820    def get_torsion_array(self):
 821        """
 822        Returns a 2D NumPy array representing the dihedral angles in the given disulfide list.
 823
 824        :return: A 2D NumPy array of shape (n, 5), where n is the number of disulfide bonds in the list. Each row
 825                of the array represents the dihedral angles of a disulfide bond, in the following order:
 826                [X1_i, X2_i, X3_i, X4_i, X5_i], where i is the index of the disulfide bond in the list.
 827        """
 828        sslist = self.data
 829        tot = len(sslist)
 830        res = np.zeros(shape=(tot, 5))
 831
 832        for idx, ss in enumerate(sslist):
 833            row = ss.torsion_array
 834            res[idx, :] = row
 835
 836        return res
 837
 838    def has_chain(self, chain) -> bool:
 839        """
 840        Returns True if given chain contained in Disulfide, False otherwise.
 841        :return: Returns True if given chain contained in Disulfide, False otherwise.
 842        """
 843
 844        chns = {"xxx"}
 845        chns = self.get_chains()
 846        if chain in chns:
 847            return True
 848        else:
 849            return False
 850
 851    @property
 852    def id(self):
 853        """
 854        PDB ID of the list
 855        """
 856        return self.pdb_id
 857
 858    @id.setter
 859    def id(self, value):
 860        """
 861        Set the DisulfideList ID
 862
 863        Parameters
 864        ----------
 865        value : str
 866            List ID
 867        """
 868        self.pdb_id = value
 869
 870    @property
 871    def resolution(self):
 872        """
 873        Resolution of the parent sturcture (A)
 874        """
 875        return self.res
 876
 877    @resolution.setter
 878    def resolution(self, value):
 879        """
 880        Set the resolution of the list
 881
 882        :param value: Resolution (A)
 883        """
 884        self.res = value
 885
 886    def TorsionGraph(
 887        self, display=True, save=False, fname="ss_torsions.png", light=True
 888    ):
 889        # tor_stats, dist_stats = self.calculate_torsion_statistics()
 890        self.display_torsion_statistics(
 891            display=display, save=save, fname=fname, light=light
 892        )
 893
 894    def insert(self, index, item):
 895        """
 896        Insert a Disulfide into the list at the specified index
 897
 898        :param index: insertion point
 899        :type index: int
 900        :param item: Disulfide to insert
 901        :type item: Disulfide
 902        """
 903        self.data.insert(index, self.validate_ss(item))
 904
 905    @property
 906    def length(self):
 907        return len(self.data)
 908
 909    @property
 910    def min(self) -> Disulfide:
 911        """
 912        Return Disulfide from the list with the minimum energy
 913
 914        :return: Disulfide with the minimum energy.
 915        """
 916        sslist = sorted(self.data)
 917        return sslist[0]
 918
 919    @property
 920    def max(self) -> Disulfide:
 921        """
 922        Return Disulfide from the list with the maximum energy
 923
 924        :return: Disulfide with the maximum energy.
 925        """
 926        sslist = sorted(self.data)
 927        return sslist[-1]
 928
 929    def minmax_distance(self):
 930        """
 931        Return the Disulfides with the minimum and
 932        maximum Cα distances in the list.
 933
 934        :return: SSmin, SSmax
 935        """
 936
 937        _min = 99999.9
 938        _max = -99999.9
 939
 940        sslist = self.data
 941        ssmin = 0
 942        ssmax = 0
 943        idx = 0
 944
 945        pbar = tqdm(sslist, ncols=PBAR_COLS)
 946        for ss in pbar:
 947            dist = ss.ca_distance
 948
 949            if dist >= _max:
 950                ssmax = idx
 951                _max = dist
 952
 953            if dist <= _min:
 954                ssmin = idx
 955                _min = dist
 956            idx += 1
 957
 958        return sslist[ssmin], sslist[ssmax]
 959
 960    @property
 961    def minmax_energy(self):
 962        """
 963        Return the Disulfides with the minimum and maximum energies
 964        from the DisulfideList.
 965
 966        :return: Disulfide with the given ID
 967        """
 968        sslist = sorted(self.data)
 969        return sslist[0], sslist[-1]
 970
 971    def nearest_neighbors(
 972        self,
 973        chi1: float,
 974        chi2: float,
 975        chi3: float,
 976        chi4: float,
 977        chi5: float,
 978        cutoff: float,
 979    ):
 980        """
 981        Given a torsional array of chi1-chi5,
 982
 983        :param chi1: Chi1 (degrees)
 984        :param chi2: Chi2 (degrees)
 985        :param chi3: Chi3 (degrees)
 986        :param chi4: Chi4 (degrees)
 987        :param chi5: Chi5 (degrees)
 988        :param cutoff: Distance cutoff, degrees
 989        :return: DisulfideList of neighbors
 990        """
 991
 992        sslist = self.data
 993        modelss = proteusPy.Disulfide("model")
 994
 995        modelss.build_model(chi1, chi2, chi3, chi4, chi5)
 996        res = DisulfideList([], "neighbors")
 997        res = modelss.Torsion_neighbors(sslist, cutoff)
 998
 999        return res
1000
1001    def nearest_neighbors_ss(self, ss, cutoff: float):
1002        """
1003        Given an input Disulfide and overall torsional cutoff, return
1004        the list of Disulfides within the cutoff
1005
1006        :param ss: Disulfide to compare to
1007        :param chi5: Chi5 (degrees)
1008        :param cutoff: Distance cutoff, degrees
1009        :return: DisulfideList of neighbors
1010        """
1011
1012        chi1 = ss.chi1
1013        chi2 = ss.chi2
1014        chi3 = ss.chi3
1015        chi4 = ss.chi4
1016        chi5 = ss.chi5
1017
1018        sslist = self.data
1019        modelss = proteusPy.Disulfide("model")
1020
1021        modelss.build_model(chi1, chi2, chi3, chi4, chi5)
1022        res = DisulfideList([], "neighbors")
1023        res = modelss.Torsion_neighbors(sslist, cutoff)
1024
1025        return res
1026
1027    def pprint(self):
1028        """
1029        Pretty print self.
1030        """
1031        sslist = self.data
1032        for ss in sslist:
1033            ss.pprint()
1034
1035    def pprint_all(self):
1036        """
1037        Pretty print full disulfide descriptions in self.
1038        """
1039        sslist = self.data
1040        for ss in sslist:
1041            ss.pprint_all()
1042
1043    @property
1044    def torsion_df(self):
1045        return self.build_torsion_df()
1046
1047    @property
1048    def torsion_array(self):
1049        return self.get_torsion_array()
1050
1051    def validate_ss(self, value):
1052        return value
1053
1054    # class ends
1055
1056
1057# utility functions
1058from proteusPy.DisulfideExceptions import DisulfideConstructionWarning
1059
1060
1061def load_disulfides_from_id(
1062    struct_name: str,
1063    pdb_dir=MODEL_DIR,
1064    model_numb=0,
1065    verbose=False,
1066    quiet=False,
1067    dbg=False,
1068) -> DisulfideList:
1069    """
1070    Loads the Disulfides by PDB ID and returns a ```DisulfideList``` of Disulfide objects.
1071    Assumes the file is downloaded in the pdb_dir path.
1072
1073    *NB:* Requires EGS-Modified BIO.parse_pdb_header.py from https://github.com/suchanek/biopython
1074
1075    :param struct_name: the name of the PDB entry.
1076    :param pdb_dir: path to the PDB files, defaults to MODEL_DIR - this is: PDB_DIR/good and are
1077    the pre-parsed PDB files that have been scanned by the DisulfideDownloader program.
1078    :param model_numb: model number to use, defaults to 0 for single structure files.
1079    :param verbose: print info while parsing
1080    :return: a list of Disulfide objects initialized from the file.
1081
1082    Example:
1083
1084    PDB_DIR defaults to os.getenv('PDB').
1085    To load the Disulfides from the PDB ID 5rsa we'd use the following:
1086
1087    >>> from proteusPy import DisulfideList, load_disulfides_from_id
1088    >>> SSlist = DisulfideList([],'5rsa')
1089    >>> SSlist = load_disulfides_from_id('5rsa', verbose=False)
1090    >>> SSlist
1091    [<Disulfide 5rsa_26A_84A, Source: 5rsa, Resolution: 2.0 Å>, <Disulfide 5rsa_40A_95A, Source: 5rsa, Resolution: 2.0 Å>, <Disulfide 5rsa_58A_110A, Source: 5rsa, Resolution: 2.0 Å>, <Disulfide 5rsa_65A_72A, Source: 5rsa, Resolution: 2.0 Å>]
1092    """
1093    import copy
1094    import warnings
1095
1096    from proteusPy.Disulfide import Disulfide, parse_ssbond_header_rec
1097
1098    i = 1
1099    proximal = distal = -1
1100    resolution = -1.0
1101
1102    _chaina = None
1103    _chainb = None
1104
1105    parser = PDBParser(PERMISSIVE=True)
1106
1107    # Biopython uses the Structure -> Model -> Chain hierarchy to organize
1108    # structures. All are iterable.
1109
1110    structure = parser.get_structure(struct_name, file=f"{pdb_dir}pdb{struct_name}.ent")
1111    model = structure[model_numb]
1112
1113    if verbose:
1114        print(f"-> load_disulfide_from_id() - Parsing structure: {struct_name}:")
1115
1116    ssbond_dict = structure.header["ssbond"]  # NB: this requires the modified code
1117    resolution = structure.header["resolution"]
1118
1119    SSList = DisulfideList([], struct_name, resolution)
1120
1121    # list of tuples with (proximal distal chaina chainb)
1122    ssbonds = parse_ssbond_header_rec(ssbond_dict)
1123
1124    with warnings.catch_warnings():
1125        if quiet:
1126            warnings.filterwarnings("ignore")
1127        for pair in ssbonds:
1128            # in the form (proximal, distal, chain)
1129            proximal = pair[0]
1130            distal = pair[1]
1131            chain1_id = pair[2]
1132            chain2_id = pair[3]
1133
1134            if not proximal.isnumeric() or not distal.isnumeric():
1135                mess = f" -> load_disulfides_from_id(): Cannot parse SSBond record (non-numeric IDs):\
1136                {struct_name} Prox: {proximal} {chain1_id} Dist: {distal} {chain2_id}, ignoring."
1137                warnings.warn(mess, DisulfideConstructionWarning)
1138                continue
1139            else:
1140                proximal = int(proximal)
1141                distal = int(distal)
1142
1143            if proximal == distal:
1144                mess = f" -> load_disulfides_from_id(): Cannot parse SSBond record (proximal == distal):\
1145                {struct_name} Prox: {proximal} {chain1_id} Dist: {distal} {chain2_id}, ignoring."
1146                warnings.warn(mess, DisulfideConstructionWarning)
1147                continue
1148
1149            _chaina = model[chain1_id]
1150            _chainb = model[chain2_id]
1151
1152            if (_chaina is None) or (_chainb is None):
1153                mess = f" -> load_disulfides_from_id(): NULL chain(s): {struct_name}: {proximal} {chain1_id}\
1154                - {distal} {chain2_id}, ignoring!"
1155                warnings.warn(mess, DisulfideConstructionWarning)
1156                continue
1157
1158            if chain1_id != chain2_id:
1159                if verbose:
1160                    mess = f" -> load_disulfides_from_id(): Cross Chain SS for: Prox: {proximal} {chain1_id}\
1161                    Dist: {distal} {chain2_id}"
1162                    warnings.warn(mess, DisulfideConstructionWarning)
1163                pass  # was break
1164
1165            try:
1166                prox_res = _chaina[proximal]
1167                dist_res = _chainb[distal]
1168
1169            except KeyError:
1170                mess = f"Cannot parse SSBond record (KeyError): {struct_name} Prox:\
1171                {proximal} {chain1_id} Dist: {distal} {chain2_id}, ignoring!"
1172                warnings.warn(mess, DisulfideConstructionWarning)
1173                continue
1174
1175            # make a new Disulfide object, name them based on proximal and distal
1176            # initialize SS bond from the proximal, distal coordinates
1177
1178            if _chaina[proximal].is_disordered() or _chainb[distal].is_disordered():
1179                mess = f" -> load_disulfides_from_id(): Disordered chain(s): {struct_name}: {proximal} {chain1_id}\
1180                - {distal} {chain2_id}, ignoring!"
1181                warnings.warn(mess, DisulfideConstructionWarning)
1182                continue
1183            else:
1184                if verbose:
1185                    print(
1186                        f" -> load_disulfides_from_id(): SSBond: {i}: {struct_name}: {proximal} {chain1_id}\
1187                    - {distal} {chain2_id}"
1188                    )
1189                ssbond_name = f"{struct_name}_{proximal}{chain1_id}_{distal}{chain2_id}"
1190                new_ss = Disulfide(ssbond_name)
1191                new_ss.initialize_disulfide_from_chain(
1192                    _chaina, _chainb, proximal, distal, resolution, quiet=quiet
1193                )
1194                SSList.append(new_ss)
1195        i += 1
1196    return copy.deepcopy(SSList)
1197
1198
1199if __name__ == "__main__":
1200    import doctest
1201
1202    doctest.testmod()
1203
1204# end of file
1205# end of file