Common Keys

Overview

Common-key analysis takes the TSR keys of a set of structures and reports which keys they share.

The figure is the worked example in which Milon et al. (2024), §4.6, define the terms of the group's earlier common-key analysis. A dataset has two classes of proteins, X and Y: three proteins in class X and two in class Y. Each protein has a set of distinct TSR keys (panel a) and a count for each key (panel b). The capital letter matters:

A class's specific keys are therefore among its Specific keys. Panel g averages four counts over the proteins of each class and of the whole dataset: Distinct (distinct keys), Total (all key occurrences), Distinct_Common (common keys) and Total_Common (occurrences of the common keys).

BioTSR 1.0.0 defines four common-key quantities of its own, listed below. Its global common keys are the dataset's common keys in the sense of panel f, and its group-wise common keys a class's, as in panels d and e. It does not compute Common, Specific or specific keys.

Run it with BioTSR

The analysis method record, §3 defines the four.

Before you start

• BioTSR 1.0.0, installed as in Getting started. The plotting extra is not needed.
• Network access the first time, to download two entries from the RCSB.
• The analysis reads saved BioTSR results — each sample's .keys file and its completion record — not triplet files, so the samples can be computed with --no-triplets.

1. Compute the samples

Save this manifest as samples.csv. Each row is one chain; label names its group:

sample_id,pdb_id,method,chain,label
ubiquitin,1UBQ,protein,A,ubiquitin
barnase,1BRS,protein,A,barnase
barstar,1BRS,protein,D,barstar

python -m pip install "biotsr==1.0.0"
biotsr fetch 1UBQ 1BRS --pdb-dir structures
biotsr batch --manifest samples.csv --pdb-dir structures --output batch --no-triplets

This writes batch/ubiquitin.keys, batch/barnase.keys and batch/barstar.keys, each with its completion record (.run.json), and batch/batch_summary.csv.

2. Common keys, from the command line

biotsr analyze common-keys --from-results batch --output analysis_out

The three chains share 9,523 keys. The command always writes into analysis/common_keys/ under --output:

• analysis_out/analysis/common_keys/all_samples.csv has one row per sample: sample_id, method, total_keys (its distinct keys), common_keys, sum_common_keys_freq (how often the common keys occur in that sample) and three fingerprints. total_keys, common_keys and sum_common_keys_freq are the columns of the earlier scripts' common_keys.csv.
• all_samples.json holds the common keys themselves and each sample's settings.

With --group-by label the intersection is taken within each label instead, written as one CSV and one JSON file per label. In this manifest every sample has a label of its own, so each group is a single chain; give samples the same label to group them.

3. Occurrence percentages, from Python

import biotsr
from biotsr.analysis import (AnalysisSample, key_occurrence_percent,
                             key_occurrence_percent_one_vs_all)

names = ("ubiquitin", "barnase", "barstar")
samples = [AnalysisSample.from_result(biotsr.load_result(f"batch/{name}.keys"), name)
           for name in names]

# For every key, the percentage of the three samples it occurs in.
occurrence = key_occurrence_percent(samples)
print(occurrence.rows[0])

# The same percentage within each group, one column per group.
group = {"ubiquitin": "ubiquitin", "barnase": "complex", "barstar": "complex"}
by_group = key_occurrence_percent_one_vs_all(samples, lambda s: group[s.sample_id])
print(by_group.groups)

occurrence.rows has one row per key, with the number of samples it occurs in and the percentage. BioTSR 1.0 returns both tables in Python and does not write them as files.

Samples are compared only when their keys share a key space, and samples computed with different settings, such as a size filter, only when you say so. Tutorial 07 runs the same samples, and the command-line guide, §8 gives every option.