CODE/API MANUAL

User reference for the BackMAP package.

backmap

Main module. Example usage: backmap.R(), which is equal to backmap.backmap.R()

backmap.backmap.normalized_ramachandran_number(phi: float, psi: float, signed=False)

Return the normalized Ramachandran number for given backbone angles (phi and psi).

Parameters:

• phi (float) – Backbone phi angle in degrees of range [-180,180].

• psi (float) – Backbone psi angle in degrees of range [-180,180].

• signed (bool) – If True, return a signed value where psi < phi yields a negative number.

Returns:

Normalized Ramachandran number randing [0, 1], or [-1, 1] when signed is True.

Return type:

float

backmap.backmap.ramachandran_number(phi, psi, signed=False)

Different abbreviated ways to request the ramachandran number Refer to backmap.backmap.normalized_ramachandran_number() for usage details.

backmap.backmap.r(phi, psi, signed=False)

Different abbreviated ways to request the ramachandran number Refer to backmap.backmap.normalized_ramachandran_number() for usage details.

backmap.backmap.R(phi, psi, signed=False)

Different abbreviated ways to request the ramachandran number Refer to backmap.backmap.normalized_ramachandran_number() for usage details.

backmap.backmap.write_image(fn_base, figure_object=None, write=True, show=True)

Save a figure to disk and optionally display it.

Parameters:

• fn_base (str) – Base filename (without extension) for the output files.

• figure_object (matplotlib.figure.Figure | None) – Figure to save; defaults to the current figure when None.

• write (bool) – If True, write .eps and .png files to disk.

• show (bool) – If True, display the figure after saving.

Returns:

None

backmap.backmap.draw_xyz(X, Y, Z, ylim=False, cmap='Greys', missing_color='green', xlabel=False, ylabel=False, zlabel=False, title=False, vmin=None, vmax=None)

Render a heatmap-style plot for spatially indexed values.

Parameters:

• X (Sequence[float]) – X-coordinates corresponding to each value in Z.

• Y (Sequence[float]) – Y-coordinates corresponding to each value in Z.

• Z (Sequence[float]) – Values to plot at each (X, Y) location.

• ylim (tuple[float, float] | bool, optional) – Y-axis limits; falsy to leave unchanged.

• cmap (str or matplotlib.colors.Colormap, optional) – Colormap name or object to use.

• missing_color (str) – A color that will be used when a residue is missing (default: ‘green’)

• xlabel (str or bool, optional) – X-axis label; falsy to skip.

• ylabel (str or bool, optional) – Y-axis label; falsy to skip.

• zlabel (str or bool, optional) – Colorbar label; falsy to skip.

• title (str or bool, optional) – Plot title; falsy to skip.

• vmin (float, optional) – Lower bound for colormap normalization.

• vmax (float, optional) – Upper bound for colormap normalization.

Returns:

(True, ax) where ax is the axes containing the plot.

Return type:

tuple[bool, matplotlib.axes.Axes]

backmap.backmap.obtain_ramachandran_dataframe(coordinates_df, signed=False)

Aggregate residue-level dihedral angles from per-atom backbone coordinates.

Parameters:

• coordinates_df (pd.DataFrame) – Backbone atom coordinates with at least model, chain, resid, atom, X, Y, and Z columns.

• signed (bool) – Whether to compute the signed Ramachandran number R.

Returns:

Per-residue records containing model, chain, residue identity, phi, psi, and Ramachandran number values. Missing neighbors leave phi/psi/R as False.

Return type:

pd.DataFrame

backmap.backmap.read_pdb_from_pdbfn_or_filehandle(pdbfn_or_filehandle, structure_df=Empty DataFrame Columns: [] Index: [], signed=False)

Parse PDB content, compute Ramachandran metrics, and merge with an existing dataframe.

Parameters:

• pdbfn_or_filehandle – Path to a PDB file or an open file-like object accepted by utils.read_pdb.

• structure_df (pd.DataFrame) – Existing dataframe of processed structures to append to; empty by default.

Returns:

Per-residue records with model, chain, residue identity, phi, psi, and Ramachandran number columns. Returns an empty dataframe when no input PDBs are found.

Return type:

pd.DataFrame

backmap.backmap.process_PDB(pdbfn_or_filehandle, signed=False)

Collect residue-level Ramachandran data from one or more PDB inputs.

Accepts either an open file handle or a path to a PDB file/directory/archive, expands archives and directories into individual file handles, and aggregates the parsed structures into a single dataframe with optional signed torsion angles.

Parameters:

• pdbfn_or_filehandle – PDB path, directory containing PDBs, archive, or an open file-like object to parse.

• signed (bool) – Whether to compute signed Ramachandran angles.

Returns:

Combined dataframe of all parsed PDB residues with a pdbfn

attribute set on the dataframe metadata.

Return type:

pd.DataFrame

backmap.backmap.fill_in_missing_resids(structure_df, fill_with=False)

Insert placeholder rows for missing residue IDs per chain and model.

Parameters:

• structure_df (pd.DataFrame) – Backbone geometry table containing chain, model, and resid columns.

• fill_with (Any) – Value used to populate missing residue rows; defaults to False.

Returns:

Reindexed dataframe spanning continuous residue ranges for each chain and model, filled with fill_with where data was absent. An additional key-value pair is added to the structure_df.attrs: {‘filled_na’: True}, which prevents this function from being recalculated downstream

Return type:

pd.DataFrame

backmap.backmap.mark_figure(df, ax=None, mark_column='mark')

Add right-side markers to rows flagged in mark_column on the current plot.

Parameters:

• df (pd.DataFrame) – Table containing a resid column and a boolean column used to flag residues for annotation.

• ax (matplotlib.axes.Axes, optional) – Axes to annotate; defaults to the current matplotlib axes.

• mark_column (str) – Column name containing boolean markers; defaults to 'mark'.

Returns:

Axes with rectangle markers added for flagged rows.

Return type:

matplotlib.axes.Axes

backmap.backmap.get_pdbfn_name_and_dir(structure_df, output_dir='')

Infer PDB filename, directory, and base name from dataframe metadata.

Parameters:

• structure_df (pd.DataFrame) – Structure dataframe carrying a pdbfn entry in attrs when available.

• output_dir (str, optional) – Preferred output directory. Defaults to the PDB directory + /reports/ when unset.

Returns:

(name, pdbfn, output_dir) where name is the

PDB file stem, pdbfn is the full path (or empty string), and output_dir is the resolved reports directory. If a io.StringIO was provided instead of a filehandle, then the returned output_dir reverts to ‘./reports/’)

Return type:

tuple[str, str, str]

backmap.backmap.draw_per_residue_plot(structure_df, output_dir='', write=False, show=False, v_limit=(0, 1), cmap='SecondaryStructure')

Plot per-residue R values for each chain and optionally save/show images.

Parameters:

• structure_df (pd.DataFrame) – Structure dataframe containing model, resid, R, and chain columns.

• output_dir (str, optional) – Directory for written images. Defaults to the reports directory derived from structure_df metadata.

• write (bool, optional) – Whether to write images to disk. Defaults to False.

• show (bool, optional) – Whether to display plots interactively. Defaults to False.

• v_limit (tuple, optional) – (vmin, vmax) limits for the colormap. Defaults to (0, 1).

• cmap (str, optional) – Matplotlib colormap name. Defaults to ‘SecondaryStructure’.

Returns:

Mapping of chain identifiers to figure-like objects produced by write_image.

Return type:

dict[str, Any]

backmap.backmap.draw_per_residue_RMSF(structure_df, output_dir='', write=False, show=False, v_limit=(0, 1), cmap='Blues')

Plot per-residue RMSF (frame-to-frame change in R) for each chain.

Parameters:

• structure_df (pd.DataFrame) – Structure dataframe containing model, resid, R, and chain columns.

• output_dir (str, optional) – Directory for written images. Defaults to the reports directory derived from structure_df metadata.

• write (bool, optional) – Whether to write images to disk. Defaults to False.

• show (bool, optional) – Whether to display plots interactively. Defaults to False.

• v_limit (tuple, optional) – (vmin, vmax) limits for the colormap. Defaults to (0, 1).

• cmap (str, optional) – Matplotlib colormap name. Defaults to ‘Blues’.

Returns:

Mapping of chain identifiers to figure-like objects produced by write_image. Chains with a single model are skipped.

Return type:

dict[str, Any]

backmap.backmap.draw_per_residue_RMSD(structure_df, output_dir='', write=False, show=False, v_limit=(0, 1), cmap='Reds')

Plot per-residue RMSD versus the first model for each chain.

Parameters:

• structure_df (pd.DataFrame) – Structure dataframe containing model, resid, R, and chain columns.

• output_dir (str, optional) – Directory for written images. Defaults to the reports directory derived from structure_df metadata.

• write (bool, optional) – Whether to write images to disk. Defaults to False.

• show (bool, optional) – Whether to display plots interactively. Defaults to False.

• v_limit (tuple, optional) – (vmin, vmax) limits for the colormap. Defaults to (0, 1).

• cmap (str, optional) – Matplotlib colormap name. Defaults to ‘Reds’.

Returns:

Mapping of chain identifiers to figure-like objects produced by write_image. Chains with a single model are skipped.

Return type:

dict[str, Any]

backmap.backmap.draw_per_model_histogram(structure_df, output_dir='', write=False, show=False, bin_steps=0.2, v_limit=(0, 1), cmap='Greys')

Plot per-model histograms of Ramachandran values for each chain.

Parameters:

• structure_df (pd.DataFrame) – Structure dataframe containing model, chain, resid, and R columns.

• output_dir (str, optional) – Directory for written images. Defaults to the reports directory derived from structure_df metadata.

• write (bool, optional) – Whether to write images to disk. Defaults to False.

• show (bool, optional) – Whether to display plots interactively. Defaults to False.

• bin_steps (float, optional) – Y-axis tick spacing for the probability axis. Defaults to 0.2.

• v_limit (tuple, optional) – (vmin, vmax) limits for histogram values. Defaults to (0, 1).

• cmap (str, optional) – Matplotlib colormap name. Defaults to ‘Greys’.

Returns:

Mapping of chain identifiers to figure-like objects produced by write_image for each histogram.

Return type:

dict[str, Any]

backmap.backmap.draw_figures(structure_df, output_dir='', write=True, show=True)

Generate per-chain Ramachandran visualizations and optionally save/show them.

Parameters:

• structure_df (pd.DataFrame) – Per-residue Ramachandran data containing at least model, chain, resid, and R columns.

• output_dir (str, optional) – Directory to write figures; defaults to <pdbdir>/reports when empty and write is True.

• write (bool) – If True, save .eps and .png files for each plot.

• show (bool) – If True, display figures after creation.

Returns:

(True, figures) where figures maps plot labels to matplotlib figure objects for the value maps, histograms, RMSF, and RMSD heatmaps computed per chain.

Return type:

tuple[bool, dict]

utils

Utility functions important for loading and processing PDB files. Functions following calculate_dihedral_angle() are probably not very interesting to most.

backmap.utils.read_pdb(filename_or_filehandle: str | PathLike)

Reads a PDB and outputs graphs representing Ramachandran number plots.

Load a PDB file, preferring BioPython parsing with an in-house fallback.

The function first tries the BioPython-based parser when the library is installed and the file passes check_pdb. Files that look problematic or environments without BioPython fall back to the in-house parser to extract backbone atoms.

Parameters:

• filename_or_filehandle (str) – Path to a PDB file to read, or file handle.

• term. (Can be multiple structures separated by the MODEL)

Returns:

Backbone atoms (N, CA, C) with model, chain, residue identifiers and float32 coordinates.

Return type:

pandas.DataFrame

backmap.utils.bytecheck(fileblock)

Return fileblock as text, decoding bytes-like input with UTF-8 (if not UTF-8 already).

Parameters:

fileblock – Raw PDB content as str, bytes, or bytearray.

Returns:

Decoded text when given bytes-like input; unchanged string otherwise.

Return type:

str

backmap.utils.parse_PDB_lines(pdb_block)

Convert a PDB text block into a list of atom dictionaries. File parsing based on: https://www.cgl.ucsf.edu/chimera/docs/UsersGuide/tutorials/pdbintro.html

Parameters:

pdb_block (str) – Raw PDB contents containing ATOM records.

Returns:

One dict per atom with parsed fields atomno, atomtype, resname, chainname, resno, x, y, z, occupancy, tf, and segname.

Return type:

list[dict]

backmap.utils.read_pdb_inhouse(fn_or_filehandle: str | PathLike)

Parse a PDB file without BioPython and extract backbone atoms.

Parameters:

fn – Path to a PDB file or a readable file-like object understood by get_filename_and_filehandle.

Returns:

Backbone atoms (N, CA, C) for each model, chain, and residue with columns ['model','chain','resname','resid','atom','X','Y','Z'] where coordinates are float32.

Return type:

pandas.DataFrame

backmap.utils.check_pdb(fn: str | PathLike)

Heuristically validate that a PDB file is safe to parse with Biopython.

The check catches common CHARMM/PDB quirks (four-letter residue names shifting into the chain column or missing/placeholder chain identifiers). Any potential issue marks the file as problematic.

Parameters:

fn (str) – Path to the PDB file to examine.

Returns:

1 when the file appears well-formed, otherwise 0.

Return type:

int

backmap.utils.calculate_dihedral_angle(p: ndarray)

Compute the dihedral angle defined by four 3D points.

E.g., providing positions for four contiguous backbone (C-)(N)(CA)(C) would give you the phi backbone dihedral angle. Similarly, providing positions for (N)(CA)(C)(N+) would give you the psi dihedral angle.

Parameters:

• p (np.ndarray) – Array of four 3D coordinates with shape (4, 3) representing

• atoms. (four contigusous backbone)

Returns:

Signed dihedral angle in degrees in the range [-180, 180].

Return type:

float

backmap.utils.is_filehandle(x)

Determine whether an object behaves like a file handle.

Parameters:

x (Any) – Object to inspect.

Returns:

True if x is an instance of io.IOBase, otherwise False.

Return type:

bool

backmap.utils.get_pdb_filenames(pdbfn_or_dir: str)

Collect .pdb filenames from a file or directory and sort them numerically.

Parameters:

pdbfn_or_dir (str) – Path to a single PDB file or a directory containing PDB files.

Returns:

Sorted list of absolute .pdb file paths and the

directory path they reside in. If the path is neither a file nor a directory, an empty list and the derived directory path are returned.

Return type:

tuple[list[str], str]

backmap.utils.return_tgz_filehandle(pdbfn)

Return file-like handles for every regular file in a tar.gz or tgz archive.

Parameters:

pdbfn (str | os.PathLike) – Path to a .tar.gz/.tgz archive.

Returns:

Handle to the first file found in the archive.

Return type:

io.BufferedReader

backmap.utils.return_zip_file_handle(pdbfn, mode='r')

Open the first file inside a zip archive and return a readable handle.

Parameters:

• pdbfn (str | os.PathLike) – Path to the .zip archive containing a PDB file.

• mode (str, optional) – Mode passed to ZipFile.open (e.g., 'r' or 'rb'). Defaults to 'r'.

Returns:

Handle to the first file found in the archive.

Return type:

ZipExtFile

backmap.utils.return_gz_filehandle(pdb_fn, mode='rt')

Open a gzipped PDB file and return a file-like handle.

Parameters:

• pdb_fn (str | os.PathLike) – Path to the .pdb.gz file to open.

• mode (str, optional) – Mode passed to gzip.open (e.g., 'rt' for text or 'rb' for binary). Defaults to 'rt'.

Returns:

Handle to the gzipped file opened with the requested mode.

Return type:

io.BufferedReader | io.TextIOWrapper

backmap.utils.return_normal_filehandle(pdb, mode='rt')

Open an uncompressed PDB file and return it as a single-item list.

Parameters:

• pdb (str | os.PathLike) – Path to the PDB file to open.

• mode (str, optional) – Mode passed to open (e.g., 'rt' for text). Defaults to 'rt'.

Returns:

List containing the opened file handle.

Return type:

list[io.TextIOWrapper]

backmap.utils.return_filehandle_from_gz_zip_or_normal_file(pdbfn)

Return a readable handle for .pdb, .pdb.gz, or .pdb.zip inputs.

Parameters:

pdbfn (str) – Path to a PDB file, optionally gzipped or zipped. For zip archives, the first file in the archive is opened.

Returns:

File-like object opened with the appropriate handler for the

given extension, or None if the extension is unsupported.

Return type:

IOBase

backmap.utils.get_filename_and_filehandle(filename_or_filehandle)

Return lists of filenames and corresponding file handles.

Accepts either a path to a PDB file (plain or compressed) or an existing file-like object. Compressed archives (.gz, .zip, .tgz/.tar.gz) are expanded into multiple handles, so filenames and handles are always returned as parallel lists.

Parameters:

filename_or_filehandle (str | io.IOBase) – Path to a PDB-like file or an already opened file-like object.

Returns:

Filenames and readable handles.

Return type:

tuple[str, io.IOBase]

Raises:

TypeError – If input is neither a filepath string nor a file-like object.

backmap.utils.median_filter(vals, nearest_neighbors=1)

Apply a 1D median filter, leaving edge elements unchanged.

Parameters:

• vals (Sequence[float]) – Input values to smooth.

• nearest_neighbors (int, optional) – Number of neighbors to include on each side when computing the median. Defaults to 1.

Returns:

Filtered values where interior points are replaced by the

median of their neighborhood and edge points are left as-is.

Return type:

list[float]

backmap.utils.forceAspect(aspect, ax=False)

Set the axis data aspect ratio using current plot limits.

Parameters:

• aspect (float) – Desired width-to-height ratio for the data units. (E.g., if aspect == 2, then the x axis will have twice the length of the y)

• ax (matplotlib.axes.Axes, optional) – Axis to update. Defaults to the current axes.

backmap.utils.get_coord_by_key_value_match(key, value, list_of_dict)

Fetch the first matching record’s coordinates for a given key/value pair.

Parameters:

• key (str) – Dictionary key to compare against value.

• value – Target value to match within each dictionary.

• list_of_dict (list[dict]) – Sequence of records expected to include 'X', 'Y', and 'Z' entries.

Returns:

Coordinates [X, Y, Z] of the first matching record, or an empty list if none match.

Return type:

list[float]

cli

Console script for backmap.

This section provides a more detailed description of what the module does, its main functionalities, and any important context or background information. It can span multiple paragraphs.

Usage: python -m backmap –pdbfn <filename/dirname> <other options>

param pdbfn:

Location of a PDB file or a directory containing PDB file(s). Single file can contain multiple structures separated by the MODEL term.

param output-dir:

Where the generated figures will be stored. If absent, a report dir will be placed in the PDBs parent directory.

param no-write:

Don’t write figures to the report directory. [default: True]

param no-show:

Don’t show figures while the app is running. [default: True]

param signed:

Use the signed Ramachandran plot. [default: False]

param colortype:

Graph coloring options (options: [‘Chirality ‘, ‘SecondaryStructure’]). [default: Chirality]

param help:

Print the available options.

backmap.cli.main(pdbfn: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7fd0b7a8e810>], output_dir: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7fd0b7a7f3d0>] = '', write: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x7fd0b7a21fd0>] = True, show: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x7fd0b7b0d310>] = True, signed: ~typing.Annotated[bool, <typer.models.OptionInfo object at 0x7fd0cb5ab6d0>] = False, colortype: ~typing.Annotated[str, <typer.models.OptionInfo object at 0x7fd0cb5a9850>] = 'Chirality')

Entry point for the CLI; processes PDB input(s) and renders plots.

Parameters:

• pdbfn (str) – Path to a PDB file or directory containing PDBs to visualize.

• output_dir (str) – Destination directory for generated figures; defaults to a report folder beside the input PDB(s) when omitted.

• write (bool) – When True, writes figures to disk; disable with --no-write.

• show (bool) – When True, displays figures interactively; disable with --no-show.

• signed (bool) – Use the signed Ramachandran plot when enabled.

• colortype (str) – Coloring scheme for graphs; must match one of ColortypeOptions.

local_colormaps

A helper file that describes colormaps that are needed to create graphs

These colormaps are used either by either by backmap.backmap.draw_figures() or the stand along app run by backmap.cli

backmap.local_colormaps.cmaps = {'Chirality': <matplotlib.colors.LinearSegmentedColormap object>, 'ChiralityFourColor': <matplotlib.colors.LinearSegmentedColormap object>, 'Chirality_r': <matplotlib.colors.LinearSegmentedColormap object>, 'Chirality_rFourColor': <matplotlib.colors.LinearSegmentedColormap object>, 'SecondaryStructure': <matplotlib.colors.LinearSegmentedColormap object>, 'SecondaryStructureFourColor': <matplotlib.colors.LinearSegmentedColormap object>, 'SecondaryStructureHard': <matplotlib.colors.LinearSegmentedColormap object>}

Mapping of custom colormap names to LinearSegmentedColormap instances. Reference the Publications section of the manual to see how the colors are used to understand/represent the properties a protein backbone (often, over an ensemble or time). Also, to visualize these cmaps, refer to the backmap.local_colormaps.display_cmaps() function.

Keys:

Chirality:

A red-blue coloring method, where red is predominantly right handed and blue is predominantly left handed. Both colors fade to white as they leave the diagonal.

Chirality_r:

Similar to Chirality, but with the color-to-white gradient reversed (i.e., the diagonal is white, while the bottom left and top right portions are red and blue respectively).

ChiralityFourColor:

Similar to the properties above, but with two more colors that are needed to represent the negative values.

ChiralityFourColor_r:

Same as the other above and, but with inverted color-to-white gradients.

[SS]Hard:

[SS=SecondaryStructure] The helix, sheet, and ppII helices shown as red, blue and cyan. Boundaries are hard (i.e., without gradients)

SecondaryStructure:

Same as above, but with color-to-white gradients (so, a backbone with a darker red color is closer to the average helice’s position than a lighter red)

[SS]FourColor:

[SS=SecondaryStructure] Same as SecondaryStructureHard, but accomodating negative R numbers.

backmap.local_colormaps.cmap_ranges = {'Chirality': [0, 1], 'ChiralityFourColor': [-1, 1], 'Chirality_r': [0, 1], 'Chirality_rFourColor': [-1, 1], 'SecondaryStructureFourColor': [-1, 1], 'SecondaryStructureHard': [0, 1]}

Listing of custom colormap names to their expected ranges. Not using these ranges will result in inaccurate coloring.

backmap.local_colormaps.display_cmaps()

Display all custom colormaps defined in cmaps as horizontal colorbars.

The colormaps are shown in insertion order with their names as titles. The figure and axes are returned so callers can further customize or save the visualization.

Returns:

tuple

Return type:

Matplotlib figure and axes from plt.subplots used to render the colorbars.