CPPStructurePlot.plot_combined

CPPStructurePlot.plot_combined(df_feat, pdb=None, uniprot=None, col_imp='feat_impact', col_val='mean_dif', shap_plot=True, tmd_len=20, start=1, chain=None, sequence=None, mode='impact', focus='zoom', focus_region=None, size_by_impact=True, normalize_by_span=False, tmd_seq=None, jmd_n_seq=None, jmd_c_seq=None, feature_map_dpi=200, feature_map_kws=None)[source]

Show the 3D structure and the CPP feature map side by side.

Reproduces the deployed app’s signature layout: the left panel is the interactive py3Dmol cartoon painted with per-residue CPP feature impact (zoomed to the feature window), the right panel is the CPPPlot.feature_map() of the same df_feat (a high-resolution image). Both read the same per-residue impact, so the structure colours and the feature map tell one consistent story. Returns a CombinedView that renders inline and exports the pair with write_html(path).

Added in version 1.1.0.

Parameters:

  • df_feat (pd.DataFrame, shape (n_features, n_feature_info)) – Feature DataFrame with a feature column, the signed per-feature impact column col_imp, and the scale-information columns the feature map needs.

  • pdb (str, optional) – Path to a .pdb / .cif structure file. Exactly one of pdb or uniprot must be given.

  • uniprot (str, optional) – UniProt accession; the AlphaFold model is fetched into a temporary folder via StructurePreprocessor.fetch_alphafold(). Exactly one of pdb or uniprot must be given.

  • col_imp (str, default='feat_impact') – Column of df_feat holding the signed per-feature impact (painted on the structure and shown in the feature map).

  • col_val (str, default='mean_dif') – Column shown in the feature-map heatmap cells (passed to CPPPlot.feature_map()).

  • shap_plot (bool, default=True) – Passed to CPPPlot.feature_map() (sample-level CPP-SHAP layout if True).

  • tmd_len (int, default=20) – Length of the TMD (>=1). Must match the value used when the features were generated.

  • start (int, default=1) – Absolute residue number of the first JMD-N residue; shifts window-relative positions onto the structure’s numbering.

  • chain (str, optional) – Chain id to render. Default selects the best-matching chain when sequence is given, otherwise the first amino-acid chain.

  • sequence (str, optional) – Full protein sequence; enables best-matching-chain selection and a start sanity check against the structure.

  • mode ({'impact', 'plddt'}, default='impact') – Structure colouring: the feature-impact ramp or the AlphaFold pLDDT palette.

  • focus ({'whole', 'fade', 'zoom'}, default='zoom') – Structure framing: 'zoom' points the camera at the feature window, 'fade' ghosts residues outside it, 'whole' styles every residue equally.

  • focus_region (tuple or list of tuples, optional) – (start, stop) residue range (or list of ranges) defining the focus window. Default derives the window from the union of df_feat positions.

  • size_by_impact (bool, default=True) – If True, draw each impact residue’s stick scaled by |impact| (impact mode only).

  • normalize_by_span (bool, default=False) – Per-residue aggregation for the structure colouring; see map_structure().

  • tmd_seq (str, optional) – TMD / JMD-N / JMD-C sequences shown along the feature-map x-axis.

  • jmd_n_seq (str, optional) – TMD / JMD-N / JMD-C sequences shown along the feature-map x-axis.

  • jmd_c_seq (str, optional) – TMD / JMD-N / JMD-C sequences shown along the feature-map x-axis.

  • feature_map_dpi (int, default=200) – Resolution of the feature-map image shown beside the structure (>=50).

  • feature_map_kws (dict, optional) – Extra keyword arguments forwarded to CPPPlot.feature_map(). Keys already controlled by this method (e.g. df_feat, col_val, col_imp, tmd_len, start, shap_plot, the part sequences) are rejected.

Returns:

view – A wrapper showing the py3Dmol cartoon next to the feature-map image, exposing show(), write_html(path), and _repr_html_, plus the mapped dict_impact / max_abs.

Return type:

CombinedView

Raises:

  • ValueError – On invalid arguments (e.g. an unknown mode / focus, neither or both of pdb / uniprot, a df_feat missing col_imp, or a colliding feature_map_kws key).

  • RuntimeError – If py3Dmol is not installed, or an AlphaFold model for uniprot cannot be fetched.

See also

  • plot_linked(): the same two panels with live hover linking (column to residue).

  • explore(): build the per-site prediction and pick the output in one call.

Examples

Show the 3D structure and the CPP feature map side by side, reproducing the deployed cleavage app’s signature layout: the left panel is the interactive py3Dmol cartoon painted with per-residue CPP feature impact, the right panel is the CPPPlot.feature_map of the same df_feat. Both read the same per-residue impact. Returns a CombinedView that renders inline and exports the pair with write_html.

This is a pro feature (needs biopython + py3Dmol).

import pandas as pd
import aaanalysis as aa
import aaanalysis.utils as ut

aa.options["verbose"] = False

As in map_structure, we use the human lysozyme C AlphaFold model (uniprot='P61626') and a df_feat with a signed feat_impact (from CPP.run + ShapModel in practice).

df_cat = aa.load_scales(name='scales_cat').head(5).reset_index(drop=True)
splits = ['Segment(1,2)', 'Segment(2,2)', 'Segment(1,1)', 'Pattern(C,1)', 'Segment(1,4)']
parts = ['TMD', 'TMD', 'JMD_N', 'TMD', 'JMD_C']
df_feat = pd.DataFrame({
    ut.COL_FEATURE: [f"{parts[i]}-{splits[i]}-{r[ut.COL_SCALE_ID]}" for i, r in df_cat.iterrows()],
    'category': df_cat[ut.COL_CAT], 'subcategory': df_cat[ut.COL_SUBCAT],
    'scale_name': df_cat[ut.COL_SCALE_NAME],
    'abs_auc': [0.2, 0.15, 0.3, 0.1, 0.25], 'abs_mean_dif': [0.3, 0.2, 0.5, 0.4, 0.35],
    'mean_dif': [0.3, -0.2, 0.5, -0.4, 0.25], 'std_test': 0.1, 'std_ref': 0.1,
    'feat_impact': [0.8, -0.5, 1.2, -0.3, 0.6]})
aa.display_df(df_feat, n_rows=10, show_shape=True)

DataFrame shape: (5, 10)
  feature category subcategory scale_name abs_auc abs_mean_dif mean_dif std_test std_ref feat_impact
1 TMD-Segment(1,2)-LINS030110 ASA/Volume Accessible surface area (ASA) ASA (folded coil/turn) 0.200000 0.300000 0.300000 0.100000 0.100000 0.800000
2 TMD-Segment(2,2)-LINS030113 ASA/Volume Accessible surface area (ASA) ASA (folded coil/turn) 0.150000 0.200000 -0.200000 0.100000 0.100000 -0.500000
3 JMD_N-Segment(1,1)-JANJ780101 ASA/Volume Accessible surface area (ASA) ASA (folded protein) 0.300000 0.500000 0.500000 0.100000 0.100000 1.200000
4 TMD-Pattern(C,1)-JANJ780103 ASA/Volume Accessible surface area (ASA) ASA (folded protein) 0.100000 0.400000 -0.400000 0.100000 0.100000 -0.300000
5 JMD_C-Segment(1,4)-LINS030104 ASA/Volume Accessible surface area (ASA) ASA (folded protein) 0.250000 0.350000 0.250000 0.100000 0.100000 0.600000

mode (impact/plddt) and focus (whole/fade/zoom) style the structure; normalize_by_span controls the per-residue aggregation (see map_structure).

csp = aa.CPPStructurePlot(jmd_n_len=10, jmd_c_len=10, verbose=False)
view = csp.plot_combined(df_feat=df_feat, uniprot='P61626', col_imp='feat_impact',
                         tmd_len=10, start=40, mode='impact', focus='fade')
view

3Dmol.js failed to load for some reason. Please check your browser console for error messages.

size_by_impact scales each impact residue’s stick by |impact|; normalize_by_span switches the per-residue aggregation (app-fidelity vs the span-normalized sum used by CPPPlot.profile); feature_map_dpi sets the embedded image resolution. (A local .pdb file works in place of uniprot= via pdb=.)

csp.plot_combined(df_feat=df_feat, uniprot='P61626', col_imp='feat_impact', tmd_len=10, start=40,
                  size_by_impact=False, normalize_by_span=True, feature_map_dpi=150)

3Dmol.js failed to load for some reason. Please check your browser console for error messages.

Export the side-by-side structure + feature map as one self-contained page:

import tempfile, os
tmp = tempfile.mkdtemp()
view.write_html(os.path.join(tmp, 'combined.html'))   # interactive side-by-side page
view.savefig(os.path.join(tmp, 'combined.pdf'))       # static feature-map panel (PNG/PDF) for papers
print('wrote combined.html + combined.pdf to', tmp)

wrote combined.html + combined.pdf to /var/folders/sv/65tlch_10198qgmpwcp6408r0000gn/T/tmpq75f6198

For a live, re-predicting explorer (slider-driven), use CPPStructurePlot.interactive.