CPPStructurePlot.plot_linked

CPPStructurePlot.plot_linked(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, highlight=None, tmd_seq=None, jmd_n_seq=None, jmd_c_seq=None, feature_map_dpi=150, feature_map_kws=None, width=520, height=460)[source]

Build a self-contained HTML view with the feature map and structure linked.

Reproduces the deployed app’s signature interaction: the CPPPlot.feature_map() is shown beside an interactive 3Dmol cartoon, and hovering a feature-map column highlights the corresponding residue in the structure (the column’s position maps to the absolute residue via start). Returns a LinkedView that renders inline where embedded scripts run (classic Notebook, nbviewer, Read the Docs) and exports a standalone, shareable .html via write_html(path) — ideal for exploring a site and as a publication-figure source. In JupyterLab (which sandboxes output scripts), use write_html and open the page in a browser.

Added in version 1.1.0.

Parameters:

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

  • pdb (str, optional) – Path to a .pdb / .cif file. Exactly one of pdb or uniprot is required.

  • uniprot (str, optional) – UniProt accession; the AlphaFold model is fetched automatically. Exactly one of pdb or uniprot is required.

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

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

  • shap_plot (bool, default=True) – Passed to CPPPlot.feature_map().

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

  • start (int, default=1) – Absolute residue number of the first JMD-N residue; maps feature-map columns to residues.

  • chain (str, optional) – Chain id to render (default best-matching / first amino-acid chain).

  • sequence (str, optional) – Full protein sequence; enables best-matching-chain selection + a start check.

  • 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' frames the feature window, 'fade' ghosts the rest.

  • focus_region (tuple or list of tuples, optional) – (start, stop) focus window; default from the union of df_feat positions.

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

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

  • highlight (tuple or list of tuple, optional) – One or more (start, stop) residue ranges (1-based, inclusive, absolute structure numbering) whose residues are all painted in COLOR_LINK_HIGHLIGHT (cyan) on top of the impact colouring. Same shape as AAPredPlot.predict_sample()’s highlight, so a region shaded cyan on the sequence plot mirrors here with the identical argument. Distinct from focus_region (which zooms / fades); each start / stop must be an integer with start <= stop.

  • tmd_seq (str, optional) – Part sequences shown along the feature-map x-axis.

  • jmd_n_seq (str, optional) – Part sequences shown along the feature-map x-axis.

  • jmd_c_seq (str, optional) – Part sequences shown along the feature-map x-axis.

  • feature_map_dpi (int, default=150) – Resolution of the embedded feature-map image (>=50).

  • feature_map_kws (dict, optional) – Extra keyword arguments forwarded to CPPPlot.feature_map() (keys this method already controls are rejected).

  • width (int, default 520, 460) – Pixel size of the 3D viewer panel.

  • height (int, default 520, 460) – Pixel size of the 3D viewer panel.

Returns:

view – A wrapper exposing show(), write_html(path), and _repr_html_ over the linked feature-map + structure HTML, plus dict_impact / max_abs.

Return type:

LinkedView

Raises:

  • ValueError – On invalid arguments (unknown mode / focus, neither/both of pdb / uniprot, 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_combined(): the same two panels as a static side-by-side (no live linking).

  • explore(): pass sites=[...] to bake a multi-site live linked HTML.

  • AAPredPlot.predict_sample(): shades the same highlight (start, stop) regions cyan on the sequence viewer; pass the identical highlight here to mirror the selection in 3D (shared COLOR_LINK_HIGHLIGHT).

Examples

The deployed cleavage app’s signature interaction: the CPPPlot.feature_map and the 3D structure are linked — hover a feature-map column and the corresponding residue lights up in the structure. plot_linked returns a LinkedView that renders inline and exports a self-contained, shareable .html via write_html — for exploring a site and as a publication-figure source.

This is a pro feature (needs biopython + py3Dmol). It is interactive — open the rendered view (or the exported HTML) in a browser and move the mouse across the feature-map columns.

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

aa.options["verbose"] = False

As in the other examples 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

focus='zoom' frames the feature window; mode (impact/plddt) and size_by_impact style the structure as in map_structure. Hover a column of the feature map → that residue is highlighted (magenta) in the cartoon.

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

width / height (px) size the 3D viewer panel; size_by_impact and normalize_by_span control residue styling as in the other methods. highlight paints one or more (start, stop) residue ranges in bright cyan (here (42, 45)), the same shape and colour AAPredPlot.predict_sample shades on the sequence viewer.

csp.plot_linked(df_feat=df_feat, uniprot='P61626', col_imp='feat_impact', tmd_len=10, start=40,
                width=600, height=500, size_by_impact=False, normalize_by_span=True,
                highlight=(42, 45))

Export the linked feature-map + structure as one self-contained page (shareable, and a source for a paper figure):

import tempfile, os
out = os.path.join(tempfile.mkdtemp(), 'linked.html')
view.write_html(out)
print('wrote', os.path.basename(out), '(', os.path.getsize(out), 'bytes )')

wrote linked.html ( 173704 bytes )

For a static side-by-side figure use CPPStructurePlot.plot_combined; for the 3D structure alone, CPPStructurePlot.map_structure; for a live notebook explorer, CPPStructurePlot.interactive.