StructurePreprocessor.get_dssp

StructurePreprocessor.get_dssp(df_seq, pdb_folder, features=None, ss_mode='ss3', gap_handling='pad')[source]

Run Define Secondary Structure of Proteins (DSSP) and append per-residue list columns to df_seq.

Runs the DSSP algorithm [Kabsch83] (via the mkdssp binary [Touw15]) on each entry’s PDB file and aligns the output to the target sequence in df_seq, appending per-residue list columns (secondary structure, Accessible Surface Area (ASA), backbone dihedrals, hydrogen bonds) plus a boolean dssp_ok flag. The result is the intermediate input that encode_dssp() consumes; call this method first to inspect the raw DSSP streams before encoding.

Added in version 1.1.0.

Parameters:

df_seq (pd.DataFrame, shape (n_samples, n_seq_info)) – DataFrame containing an entry column with unique protein identifiers and a sequence column with full protein sequences. entry is used as the PDB-file basename (<entry>.pdb) and sequence is the target sequence to which DSSP output is aligned.
pdb_folder (str or pathlib.Path) – Directory containing one <entry>.pdb file per row of df_seq. Missing files emit a UserWarning and produce dssp_ok=False for that row.
features (list of str, default=['ss', 'asa', 'phi_psi', 'hbonds']) – Which DSSP feature streams to extract. Any subset of {'ss', 'asa', 'phi_psi', 'hbonds'}. Only the requested columns are appended; dssp_ok is always appended.
ss_mode ({'ss3', 'ss8'}, default='ss3') – Secondary-structure encoding for the ss column.
gap_handling ({'pad', 'omit'}, default='pad') – How to handle positions without DSSP coverage. 'pad' preserves length-alignment to df_seq[sequence] and fills with ut.STR_SS_GAP / NaN; 'omit' drops them across all requested streams simultaneously.

Returns:

df_out – A copy of df_seq with appended list columns for each requested feature stream plus a boolean dssp_ok column.

Return type:

pd.DataFrame

Raises:

RuntimeError – If mkdssp / dssp is not on PATH.
ValueError – On invalid arguments or pre-existing output columns in df_seq.

Examples

get_dssp runs DSSP on each entry’s PDB / CIF file and returns a copy of df_seq with the raw, inspectable per-residue DSSP output (one list per residue column: ss, asa, phi, psi, hydrogen-bond offsets and energies) plus a dssp_ok flag. It is the curatable intermediate that encode_dssp turns into a dict_num. The chain whose ATOM sequence best matches df_seq['sequence'] is selected automatically and aligned back to the full sequence.

Requires aaanalysis[pro] plus a mkdssp (or legacy dssp) binary on PATH. The structures are AlphaFold models fetched with fetch_alphafold.

import warnings
import tempfile
from pathlib import Path
import aaanalysis as aa
aa.options['verbose'] = False
warnings.filterwarnings('ignore')

# Three short human proteins from the bundled gamma-secretase set; their ``entry``
# values are UniProt accessions, which is what AlphaFold DB is keyed by.
df_seq = aa.load_dataset(name='DOM_GSEC', n=10)
df_seq = df_seq[df_seq['entry'].isin(['Q14802', 'O43914', 'P01135'])].reset_index(drop=True)

strp = aa.StructurePreprocessor(verbose=False)
af_dir = Path(tempfile.mkdtemp()) / 'alphafold'   # use a persistent project folder in real work

strp.fetch_alphafold(df_seq=df_seq, out_folder=af_dir)

df_dssp = strp.get_dssp(df_seq=df_seq, pdb_folder=af_dir)
print('added columns:', [c for c in df_dssp.columns if c not in df_seq.columns])
aa.display_df(df_dssp[['entry', 'gene', 'ss', 'asa', 'dssp_ok']], n_rows=10, show_shape=True, char_limit=40)

added columns: ['ss', 'asa', 'phi', 'psi', 'hbond_donor_offset', 'hbond_donor_energy', 'hbond_acceptor_offset', 'hbond_acceptor_energy', 'dssp_ok']
DataFrame shape: (3, 5)

	entry	gene	ss	asa	dssp_ok
1	Q14802	FXYD3	['-', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', '-', '-', '-', '-', '-', 'C', 'C', 'C', 'C', 'C', 'C', 'C', '-', '-', '-', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'C', 'C', 'C', 'C', 'C', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-', '-']	[186.0, 156.0, 160.0, 89.00000000000001, 73.0, 112.00000000000001, 35.0, 101.0, 106.0, 95.0, 65.0, 96.0, 75.0, 46.00000000000001, 89.0, 89.0, 113.0, 106.0, 155.0, 70.0, 130.0, 87.0, 131.0, 170.0, 75.0, 160.0, 138.0, 52.0, 117.0, 170.0, 68.0, 144.0, 63.0, 153.0, 126.00000000000001, 48.0, 115.0, 131.0, 26.0, 31.0, 40.0, 135.0, 38.0, 67.0, 59.0, 41.0, 44.0, 99.0, 83.0, 45.0, 104.0, 33.0, 97.00000000000001, 89.0, 101.00000000000001, 92.0, 103.0, 65.0, 67.0, 177.0, 77.99999999999999, 186.0, 98.0, 181.0, 197.0, 64.0, 153.0, 193.0, 82.0, 65.0, 158.0, 152.0, 114.0, 55.0, 150.0, 121.0, 112.0, 99.0, 164.0, 140.0, 132.0, 125.0, 67.0, 97.0, 106.0, 166.0, 130.0]	True
2	P01135	TGFA	['-', 'C', 'C', 'C', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'C', 'C', 'C', 'C', '-', '-', '-', '-', 'C', 'C', 'C', 'C', '-', '-', '-', '-', 'E', 'E', 'C', 'C', 'C', 'H', 'H', 'H', 'C', 'C', 'C', '-', 'C', 'C', 'E', 'E', 'E', 'E', 'E', 'E', 'C', 'C', 'C', 'C', 'E', 'E', 'E', 'E', 'E', 'E', 'C', 'C', 'C', 'E', 'E', 'C', 'C', 'C', 'C', '-', 'E', 'E', '-', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', '-', 'C', 'C', '-', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'C', 'C', 'C', '-', '-', '-', 'C', '-', '-', '-', '-', '-', '-', '-', 'C', '-', '-', '-', '-', '-', '-', '-']	[188.0, 134.0, 54.0, 69.0, 46.0, 40.0, 92.0, 68.0, 51.0, 124.0, 140.0, 16.0, 110.0, 38.0, 122.0, 67.0, 98.0, 60.0, 59.0, 59.0, 129.0, 54.0, 72.0, 110.0, 122.00000000000001, 80.0, 69.0, 72.0, 98.0, 148.0, 72.0, 72.0, 135.0, 100.0, 96.0, 122.0, 89.0, 80.0, 88.0, 85.0, 141.0, 29.0, 149.0, 67.0, 91.0, 152.0, 22.0, 64.0, 142.0, 97.0, 76.0, 77.00000000000001, 156.0, 55.0, 14.0, 108.0, 78.0, 15.0, 89.00000000000001, 29.0, 84.0, 39.0, 51.0, 61.99999999999999, 172.0, 109.0, 128.0, 111.00000000000001, 31.0, 24.0, 18.0, 70.0, 42.0, 100.0, 121.0, 11.0, 83.0, 70.0, 36.0, 87.0, 77.0, 0.0, 114.0, 112.99999999999999, 73.0, 42.99999999999999, 133.0, 132.0, 34.0, 78.0, 68.0, 63.0, 36.0, 42.0, 107.99999999999999, 121.0, 142.0, 119.0, 51.0, 103.0, 87.0, 52.0, 81.0, 83.0, 83.0, 98.0, 63.0, 108.00000000000001, 84.0, 46.0, 86.0, 43.0, 84.0, 56.99999999999999, 108.00000000000001, 90.00000000000001, 61.0, 74.0, 72.0, 41.0, 37.0, 118.0, 24.0, 57.0, 102.0, 98.0, 151.0, 191.0, 160.0, 27.0, 167.0, 188.0, 7.0, 169.0, 49.0, 99.0, 113.0, 85.0, 212.0, 175.0, 168.0, 183.0, 118.0, 122.0, 91.0, 162.0, 164.0, 205.0, 55.0, 248.0, 130.0, 67.0, 131.0, 106.0, 162.0, 103.0, 153.0, 135.0, 111.99999999999999, 142.0]	True
3	O43914	TYROBP	['-', '-', '-', 'C', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'C', 'C', '-', '-', '-', '-', 'C', 'C', 'C', 'C', 'C', '-', '-', '-', '-', '-', '-', '-', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'C', '-', '-', 'C', 'C', 'C', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'C', 'C', '-', '-', '-', '-', '-', '-', '-', 'C', 'C', 'C', 'C', 'C', 'C', 'C', 'C', '-', '-', 'C', '-', '-', '-', '-', '-', '-', '-', '-']	[188.0, 84.0, 56.0, 120.0, 107.00000000000001, 72.0, 82.0, 58.0, 167.0, 117.0, 112.00000000000001, 81.0, 110.0, 74.0, 105.0, 110.0, 118.0, 48.0, 90.0, 60.0, 61.0, 139.0, 188.0, 109.0, 119.0, 189.0, 66.0, 152.0, 106.0, 189.0, 57.0, 163.0, 99.0, 130.0, 95.0, 111.0, 142.0, 110.0, 78.0, 108.0, 55.0, 89.00000000000001, 102.0, 59.0, 42.0, 113.0, 94.0, 106.0, 37.0, 99.00000000000001, 111.00000000000001, 65.0, 95.0, 67.0, 87.0, 97.0, 95.0, 62.0, 82.0, 59.0, 78.0, 129.0, 98.99999999999999, 109.0, 54.00000000000001, 172.0, 132.0, 80.0, 105.0, 168.0, 64.0, 229.0, 46.00000000000001, 58.0, 73.0, 92.0, 41.0, 63.0, 94.0, 156.0, 149.0, 159.0, 217.0, 111.0, 117.0, 170.0, 98.0, 176.0, 112.0, 107.0, 199.0, 177.0, 192.0, 127.0, 192.0, 69.0, 163.0, 233.0, 60.0, 142.0, 116.0, 222.0, 91.0, 150.0, 164.0, 149.0, 142.0, 150.0, 207.0, 111.0, 201.0, 222.0, 205.0]	True

Each list column has one element per residue of the full sequence, so the secondary-structure string lines up with the sequence:

for entry, seq, ss in zip(df_dssp['entry'], df_dssp['sequence'], df_dssp['ss']):
    print(entry)
    print('  seq', seq[:60])
    print('  ss ', ''.join(ss[:60]))

Q14802
  seq MQKVTLGLLVFLAGFPVLDANDLEDKNSPFYYDWHSLQVGGLICAGVLCAMGIIIVMSAK
  ss  -HHHHHHHHHHHHHHHHH-----CCCCCCC---HHHHHHHHHHHHHHHHHHHHHHHHHHH
P01135
  seq MVPSAGQLALFALGIVLAACQALENSTSPLSADPPVAAAVVSHFNDCPDSHTQFCFHGTC
  ss  -CCCHHHHHHHHHHHHHHHHHHHHHHHCCCC----CCCC----EECCCHHHCCC-CCEEE
O43914
  seq MGGLEPCSRLLLLPLLLAVSGLRPVQAQAQSDCSCSTVSPGVLAGIVMGDLVLTVLIALA
  ss  ---CHHHHHHHHHHHHHHHHHCC----CCCCC-------HHHHHHHHHHHHHHHHHHHHH

features restricts the DSSP columns that are added (any subset of 'ss', 'asa', 'phi_psi', 'hbonds'); ss_mode chooses the three-state ('ss3': helix / strand / coil) or the native eight-state ('ss8') alphabet; gap_handling controls residues DSSP skips: 'pad' keeps the full sequence length with placeholders, 'omit' drops them so the lists are shorter than the sequence.

df_dssp8 = strp.get_dssp(df_seq=df_seq, pdb_folder=af_dir, features=['ss', 'asa'],
                         ss_mode='ss8', gap_handling='omit')
print('eight-state codes:', ''.join(df_dssp8['ss'].iloc[0][:60]))
print('list length vs sequence length:', len(df_dssp8['ss'].iloc[0]), 'vs', len(df_dssp8['sequence'].iloc[0]))
aa.display_df(df_dssp8[['entry', 'ss', 'asa', 'dssp_ok']], n_rows=10, show_shape=True, char_limit=40)

eight-state codes: HHHHHHHHHHHHHGGGGSSTTSTTHHHHHHHHHHHHHHHHHHHHHHHHHHHHTTTSS
list length vs sequence length: 57 vs 87
DataFrame shape: (3, 4)

	entry	ss	asa	dssp_ok
1	Q14802	['H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'G', 'G', 'G', 'G', 'S', 'S', 'T', 'T', 'S', 'T', 'T', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'T', 'T', 'T', 'S', 'S']	[156.0, 160.0, 89.00000000000001, 73.0, 112.00000000000001, 35.0, 101.0, 106.0, 95.0, 65.0, 96.0, 75.0, 46.00000000000001, 89.0, 89.0, 113.0, 106.0, 170.0, 75.0, 160.0, 138.0, 52.0, 117.0, 170.0, 153.0, 126.00000000000001, 48.0, 115.0, 131.0, 26.0, 31.0, 40.0, 135.0, 38.0, 67.0, 59.0, 41.0, 44.0, 99.0, 83.0, 45.0, 104.0, 33.0, 97.00000000000001, 89.0, 101.00000000000001, 92.0, 103.0, 65.0, 67.0, 177.0, 77.99999999999999, 186.0, 98.0, 181.0, 197.0, 64.0]	True
2	P01135	['P', 'P', 'P', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'T', 'T', 'T', 'S', 'T', 'T', 'S', 'S', 'E', 'E', 'P', 'P', 'P', 'G', 'G', 'G', 'T', 'T', 'T', 'S', 'S', 'E', 'E', 'E', 'E', 'E', 'E', 'T', 'T', 'T', 'T', 'E', 'E', 'E', 'E', 'E', 'E', 'P', 'T', 'T', 'E', 'E', 'S', 'T', 'T', 'S', 'E', 'E', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'T', 'T', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'T', 'T', 'S', 'S', 'S']	[134.0, 54.0, 69.0, 46.0, 40.0, 92.0, 68.0, 51.0, 124.0, 140.0, 16.0, 110.0, 38.0, 122.0, 67.0, 98.0, 60.0, 59.0, 59.0, 129.0, 54.0, 72.0, 110.0, 122.00000000000001, 80.0, 69.0, 72.0, 98.0, 148.0, 72.0, 122.0, 89.0, 80.0, 88.0, 67.0, 91.0, 152.0, 22.0, 64.0, 142.0, 97.0, 76.0, 77.00000000000001, 156.0, 55.0, 108.0, 78.0, 15.0, 89.00000000000001, 29.0, 84.0, 39.0, 51.0, 61.99999999999999, 172.0, 109.0, 128.0, 111.00000000000001, 31.0, 24.0, 18.0, 70.0, 42.0, 100.0, 121.0, 11.0, 83.0, 70.0, 36.0, 87.0, 77.0, 0.0, 112.99999999999999, 73.0, 133.0, 132.0, 34.0, 78.0, 68.0, 63.0, 36.0, 42.0, 107.99999999999999, 121.0, 142.0, 119.0, 51.0, 103.0, 87.0, 52.0, 81.0, 83.0, 83.0, 98.0, 63.0, 108.00000000000001, 84.0, 46.0, 86.0, 43.0, 84.0, 56.99999999999999, 108.00000000000001, 90.00000000000001, 61.0, 74.0, 72.0, 41.0, 37.0, 118.0, 24.0, 57.0, 102.0, 98.0, 191.0, 160.0, 167.0, 188.0, 7.0, 169.0, 49.0, 99.0, 113.0, 85.0, 212.0, 175.0, 168.0, 91.0, 131.0]	True
3	O43914	['S', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'S', 'S', 'S', 'S', 'S', 'S', 'S', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'S', 'T', 'T', 'S', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'H', 'S', 'S', 'T', 'T', 'S', 'S', 'S', 'T', 'T', 'T', 'S']	[120.0, 107.00000000000001, 72.0, 82.0, 58.0, 167.0, 117.0, 112.00000000000001, 81.0, 110.0, 74.0, 105.0, 110.0, 118.0, 48.0, 90.0, 60.0, 61.0, 139.0, 188.0, 152.0, 106.0, 189.0, 57.0, 163.0, 108.0, 55.0, 89.00000000000001, 102.0, 59.0, 42.0, 113.0, 94.0, 106.0, 37.0, 99.00000000000001, 111.00000000000001, 65.0, 95.0, 67.0, 87.0, 97.0, 95.0, 62.0, 82.0, 59.0, 78.0, 129.0, 98.99999999999999, 109.0, 54.00000000000001, 172.0, 132.0, 80.0, 64.0, 229.0, 46.00000000000001, 58.0, 73.0, 92.0, 41.0, 63.0, 94.0, 156.0, 149.0, 159.0, 217.0, 111.0, 117.0, 170.0, 98.0, 192.0, 69.0, 163.0, 233.0, 60.0, 142.0, 116.0, 222.0, 164.0]	True