Novel β-Barrel Domain Discovery

A computational workflow for prioritising previously uncharacterised candidate regions that may encode transmembrane β-barrel domains. The pipeline combines protein-domain co-occurrence, inter-domain gap extraction, topology prediction, sequence clustering, profile-HMM comparison with OMPdb, and whole-protein structural annotation using AlphaFold DB, TED/CATH and Foldseek.

Scope of the repository
This repository supports candidate discovery, annotation and prioritisation. A computational label such as NOVEL_CANDIDATE, UNCHARACTERIZED or TRULY_NOVEL must not be interpreted as experimental proof of a new protein family. The strongest defensible conclusion is that a cluster is a putative novel candidate with no detectable relationship under the searches applied.

Scientific rationale

Known bacterial outer-membrane β-barrel proteins are frequently found in recurring multidomain architectures. The working hypothesis of this project is that Pfam domains that significantly co-occur with curated OMPdb β-barrel domains may act as contextual markers for related outer-membrane proteins. Long unannotated regions within proteins carrying those contextual domains can therefore be prioritised as candidate β-barrel regions.

The workflow does not rely on a single predictor. Candidate regions are assessed through several complementary evidence layers:

Domain context: Pfam–OMPdb co-occurrence.
Unannotated sequence: inter-domain regions longer than 80 amino acids.
Topology: PRED-TMBB2 β-barrel prediction.
Family support: CD-HIT clustering and cluster-level enrichment.
Known-family sensitivity: OMPdb profile-HMM rescanning with a permissive domain i-Evalue threshold.
Structural context: AlphaFold DB model availability, TED/CATH assignments and Foldseek/PDB100 similarity.

The co-occurrence tables are calculated only from proteins retained after the domain-annotation stage because they contain at least one unannotated region longer than 80 amino acids. They must therefore not be described as contingency tables over all proteins in all source proteomes.

Workflow overview

flowchart TD
    A[Pfam-A HMM library] --> C[Remove profiles already represented in OMPdb]
    B[OMPdb HMM library] --> C
    C --> D[HMMER annotation of proteomes]
    B --> D
    D --> E[Retain proteins with unannotated regions >80 aa]
    E --> F[Pfam–OMPdb co-occurrence tables]
    F --> G[Statistical association testing]
    G --> H[Extract candidate gap sequences]
    H --> I[PRED-TMBB2 topology prediction]
    I --> J[CD-HIT clustering at 40% identity]
    J --> K[Select clusters with >=5 members and >=70% predicted positives]
    K --> L[OMPdb profile-HMM rescan; domain i-Evalue <0.1]
    L --> M[AlphaFold DB and ESM Atlas lookup]
    M --> N[TED/CATH domain annotation]
    N --> O[Foldseek search against PDB100]
    O --> P[Cluster evidence table and conservative prioritisation]

Repository structure

novel-beta-barrel-domain-discovery/
├── README.md
├── requirements.txt
├── scripts/
│   ├── 01_database_preparation/
│   │   └── 01_filter_pfam_ompdb_redundancy.py
│   ├── 02_domain_annotation/
│   │   ├── 02_annotate_proteomes_and_detect_gaps.py
│   │   └── 03_extract_unique_pfam_domains.py
│   ├── 03_cooccurrence_analysis/
│   │   ├── 04_calculate_domain_cooccurrence.py
│   │   ├── 05_merge_cooccurrence_partitions.py
│   │   └── 06_test_domain_associations.py
│   ├── 04_candidate_extraction/
│   │   └── 07_extract_candidate_gap_sequences.py
│   ├── 05_topology_prediction/
│   │   └── 08_parse_pred_tmbb2_results.py
│   ├── 06_sequence_clustering/
│   │   ├── 09_number_fasta_headers_for_cdhit.py
│   │   ├── 10_restore_cdhit_cluster_headers.py
│   │   └── 11_select_beta_barrel_enriched_clusters.py
│   └── 07_candidate_validation/
│       ├── 12_rescan_clusters_against_ompdb.py
│       ├── 13_annotate_clusters_structurally.py
│       ├── 14_classify_candidate_clusters.py
│       ├── 15_build_cluster_summary_table.py
│       └── 16_build_final_evidence_table.py
├── results/
│   ├── summary/
│   ├── final/
│   └── structure_validation/
└── tests/
    └── test_build_final_evidence_table.py

The repository contains compact result files from the archived analysis. Raw proteomes, Pfam-A, the OMPdb HMM library, PRED-TMBB2 installations and large downloaded structural databases are not redistributed.

Software and databases

Python dependencies

The Python dependencies recorded in requirements.txt are:

pandas
numpy
scipy
tqdm
requests
beautifulsoup4

External command-line software

The full workflow additionally requires:

Python 3.10 or newer;
HMMER 3 (hmmscan, hmmpress);
CD-HIT (cd-hit);
PRED-TMBB2;
Git.

External biological resources

The workflow uses locally downloaded or remotely queried data from:

Pfam-A profile HMMs;
OMPdb profile HMMs, with the archived analysis using OMPdb_2022_11_17.hmm;
AlphaFold Protein Structure Database;
TED/CATH;
Foldseek/PDB100;
ESM Metagenomic Atlas as a fallback when supported.

Database snapshots and retrieval dates should be reported in any manuscript because these resources evolve over time.

Installation

1. Clone the repository

git clone https://github.com/programmereua/novel-beta-barrel-domain-discovery.git
cd novel-beta-barrel-domain-discovery

2. Create a Python environment

On Git Bash for Windows:

python -m venv .venv
source .venv/Scripts/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

On Linux or macOS:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

3. Confirm the external tools

hmmscan -h | head
hmmpress -h | head
cd-hit -h | head

PRED-TMBB2 must be installed and executed according to its own distribution instructions.

Input data

The full analysis expects the following user-supplied resources:

Pfam-A.hmm
OMPdb_2022_11_17.hmm
ompdb_domain_names.csv
fasta_files/                      # input proteome FASTA files

The original compute-intensive annotation was divided into four mutually exclusive proteome partitions. Each protein should belong to exactly one partition to prevent double counting when partition-level results are merged.

Several scripts use fixed relative filenames rather than command-line arguments. Run each script in a working directory containing the filenames documented in its module docstring, or edit those filename variables deliberately and record the changes.

Pipeline stages

1. Remove Pfam profiles already represented in OMPdb

Script: scripts/01_database_preparation/01_filter_pfam_ompdb_redundancy.py

Purpose: avoid counting the same curated OMP family through both the Pfam and OMPdb libraries.

Expected files in the current working directory:

Pfam-A.hmm
OMPdb_2022_11_17.hmm

Run:

python scripts/01_database_preparation/01_filter_pfam_ompdb_redundancy.py
hmmpress filtered_PFAM.hmm
hmmpress OMPdb_2022_11_17.hmm

Output:

filtered_PFAM.hmm

2. Annotate proteins and detect long unannotated regions

Script: scripts/02_domain_annotation/02_annotate_proteomes_and_detect_gaps.py

For each proteome, the script:

runs hmmscan against filtered Pfam and OMPdb profiles;
retains hits passing the profile trusted cutoff where available;
combines Pfam and OMPdb annotations per protein;
detects unannotated regions longer than 80 amino acids;
retains proteins with at least one such region.

Because the original workload was distributed, run the stage once per proteome partition and rename the generated files with partition suffixes 1–4.

Principal outputs per partition:

filtered_pfam_outputN.csv
ompdb_outputN.csv
filtered_combined_outputN.csv
combined_outputN.csv

filtered_combined_outputN.csv is the downstream input used for co-occurrence and candidate extraction.

3. Extract unique Pfam domains per partition

Script: scripts/02_domain_annotation/03_extract_unique_pfam_domains.py

Edit the input and output suffix in the script for each partition, then run:

python scripts/02_domain_annotation/03_extract_unique_pfam_domains.py

Outputs:

unique_pfam_domains_part_01.csv
unique_pfam_domains_part_02.csv
unique_pfam_domains_part_03.csv
unique_pfam_domains_part_04.csv

4. Calculate Pfam–OMPdb co-occurrence

Script: scripts/03_cooccurrence_analysis/04_calculate_domain_cooccurrence.py

For each Pfam domain in a partition, the script constructs a 2×2 table:

	OMPdb present	OMPdb absent
Pfam present	`Pfam_and_Barrel`	`Only_Domain`
Pfam absent	`Only_Barrel`	`No_Domain_No_Barrel`

Edit the partition suffix and run once for each partition:

python scripts/03_cooccurrence_analysis/04_calculate_domain_cooccurrence.py

Outputs:

pfam_ompdb_cooccurrence_part_01.csv
pfam_ompdb_cooccurrence_part_02.csv
pfam_ompdb_cooccurrence_part_03.csv
pfam_ompdb_cooccurrence_part_04.csv

5. Merge partition-level contingency tables

Script: scripts/03_cooccurrence_analysis/05_merge_cooccurrence_partitions.py

python scripts/03_cooccurrence_analysis/05_merge_cooccurrence_partitions.py

Output:

pfam_ompdb_cooccurrence_aggregated.csv

6. Test domain associations

Script: scripts/03_cooccurrence_analysis/06_test_domain_associations.py

The archived script calculates:

sample odds ratio;
a normal-approximation two-sided p-value for the log odds ratio;
Fisher's exact p-value;
Pearson chi-square p-value with continuity correction.

The archived selection rule is:

odds ratio > 1 and unadjusted normal-approximation p-value < 0.05

Run:

python scripts/03_cooccurrence_analysis/06_test_domain_associations.py

Outputs:

pfam_ompdb_cooccurrence_aggregated.csv
significant_pfam_ompdb_associations.csv
pfam_domains_with_ompdb_cooccurrence.csv

For manuscript reporting, state the implemented rule exactly. The archived implementation does not apply a multiple-testing correction.

7. Extract candidate inter-domain regions

Script: scripts/04_candidate_extraction/07_extract_candidate_gap_sequences.py

A protein is retained when it:

carries at least one Pfam domain from significant_pfam_ompdb_associations.csv;
lacks a known OMPdb domain annotation;
contains one or more previously detected gap regions.

Run:

python scripts/04_candidate_extraction/07_extract_candidate_gap_sequences.py

Outputs:

final_filtered_results.fasta
candidate_gap_sequences.fasta

candidate_gap_sequences.fasta merges all matching contextual Pfam domains for the same protein-gap pair and is the input to PRED-TMBB2.

8. Predict β-barrel topology with PRED-TMBB2

Run PRED-TMBB2 on:

candidate_gap_sequences.fasta

Save the raw predictor output as:

pred_tmbb2_raw_output.txt

Parse it with:

python scripts/05_topology_prediction/08_parse_pred_tmbb2_results.py

Output:

pred_tmbb2_candidate_probabilities.csv

A positive PRED-TMBB2 call is treated as a predicted β-barrel candidate, not as confirmation of a new domain or family.

9. Cluster candidate sequences

Number the FASTA headers:

python scripts/06_sequence_clustering/09_number_fasta_headers_for_cdhit.py \
  candidate_gap_sequences.fasta \
  candidate_gap_sequences_numbered.fasta

Cluster at 40% sequence identity:

cd-hit \
  -i candidate_gap_sequences_numbered.fasta \
  -o candidate_gap_sequences_cdhit40.fasta \
  -c 0.40 \
  -n 2 \
  -d 0

The CD-HIT cluster file is expected as:

candidate_gap_sequences_cdhit40_clusters.clstr

Restore original headers when required:

python scripts/06_sequence_clustering/10_restore_cdhit_cluster_headers.py

10. Select β-barrel-enriched sequence clusters

Script: scripts/06_sequence_clustering/11_select_beta_barrel_enriched_clusters.py

The archived high-confidence cluster rule is:

cluster size >= 5 members
and
70%–100% of members called positive by PRED-TMBB2

Run:

python scripts/06_sequence_clustering/11_select_beta_barrel_enriched_clusters.py

Outputs:

cdhit40_clusters_with_pred_tmbb2_predictions.txt
high_confidence_clusters_70pct.txt
high_confidence_clusters_70pct_summary.txt
high_confidence_clusters_70pct_with_sequences.txt

11. Rescan selected clusters against OMPdb

Script: scripts/07_candidate_validation/12_rescan_clusters_against_ompdb.py

Each selected candidate region is scanned against the OMPdb profile-HMM library. The archived inclusion criterion is:

domain i-Evalue < 0.1

Run in a directory containing high_confidence_clusters_70pct_with_sequences.txt and the OMPdb HMM library:

python scripts/07_candidate_validation/12_rescan_clusters_against_ompdb.py

Output:

high_confidence_clusters_with_ompdb_hits.txt

This is a sensitive screen for possible weak or remote relationships. A permissive hit is not by itself a definitive family assignment.

Structural validation

12. Whole-protein structural annotation

Script: scripts/07_candidate_validation/13_annotate_clusters_structurally.py

The script retrieves or queries:

AlphaFold DB models;
ESM Atlas fallback models where supported;
TED/CATH domain annotations;
Foldseek matches against PDB100.

Example:

python scripts/07_candidate_validation/13_annotate_clusters_structurally.py \
  --input results/final/high_confidence_clusters_with_ompdb_hits.txt \
  --outdir structural_annotation_run

For a local TED/CATH domain-summary table:

python scripts/07_candidate_validation/13_annotate_clusters_structurally.py \
  --input results/final/high_confidence_clusters_with_ompdb_hits.txt \
  --outdir structural_annotation_run \
  --ted-tsv /path/to/ted_365m.domain_summary.cath.globularity.taxid.tsv.gz

To skip Foldseek temporarily:

python scripts/07_candidate_validation/13_annotate_clusters_structurally.py \
  --input results/final/high_confidence_clusters_with_ompdb_hits.txt \
  --outdir structural_annotation_run \
  --skip-foldseek

The annotation script caches results, allowing interrupted runs to resume.

Interpretation boundary: structural searches are performed using complete proteins that contain candidate regions. A whole-protein Foldseek or CATH match may arise from another domain in the same protein. Therefore, this stage provides cluster-level structural context and prioritisation; it does not prove that the extracted candidate coordinates themselves form the matched fold.

13. Build the cluster summary table

python scripts/07_candidate_validation/15_build_cluster_summary_table.py \
  results/structure_validation/annotated_high_confidence_clusters.txt \
  results/structure_validation/cluster_summary_table.tsv

14. Classify candidate clusters

python scripts/07_candidate_validation/14_classify_candidate_clusters.py \
  results/structure_validation/cluster_summary_table.tsv \
  results/structure_validation/cluster_classification.tsv

The classifier combines Foldseek descriptions, CATH assignments, Pfam context and structure availability. Its labels are heuristic prioritisation labels, not experimental family definitions.

Corrected OMPdb evidence table

The final publication-style table is rebuilt using the member-level OMPdb results rather than assigning OMPdb_hit=YES to every cluster.

Script: scripts/07_candidate_validation/16_build_final_evidence_table.py

python scripts/07_candidate_validation/16_build_final_evidence_table.py \
  --simple-table results/structure_validation/cluster_evidence_summary.tsv \
  --ompdb-clusters results/final/high_confidence_clusters_with_ompdb_hits.txt \
  --output results/structure_validation/cluster_evidence_summary.tsv \
  --detailed-output results/structure_validation/cluster_evidence_summary_detailed.tsv \
  --allow-missing

Definition of `OMPdb_hit`

YES: at least one PRED-TMBB2-positive member has an OMPdb profile-HMM hit with domain i-Evalue < 0.1;
NO: the cluster is represented in the OMPdb result file, but none of its PRED-TMBB2-positive members has such a hit;
UNKNOWN: the cluster is absent from the available OMPdb-annotated cluster file.

The detailed table additionally reports:

OMPdb_any_member_hit
OMPdb_PRED_YES_members
OMPdb_PRED_YES_members_with_hit
OMPdb_hit_fraction_of_PRED_YES
OMPdb_all_members_with_hit
OMPdb_best_profile
OMPdb_best_iEvalue
OMPdb_profile_member_counts
OMPdb_header_reported_hit_members
OMPdb_count_consistent

Run the included test with:

python -m unittest discover \
  -s tests \
  -p "test_build_final_evidence_table.py" \
  -v

Archived result summary

The compact repository contains the following archived outputs:

Stage	Archived count
Pfam domains in the aggregated co-occurrence table	14,462
Pfam domains retained by the archived association rule	159
Candidate regions evaluated by PRED-TMBB2	174,840
PRED-TMBB2-positive candidate regions	19,191
Clusters represented in the OMPdb-annotated final cluster file	306
Clusters in the structurally evaluated subset	152
Protein-region members in the structural subset	1,998
Unique UniProt accessions in the structural subset	1,850
AlphaFold DB models available	1,626 / 1,850
Accessions without an AlphaFold DB model	224 / 1,850
Foldseek/PDB100 results available	1,626 / 1,850

Corrected OMPdb summary for the 152-cluster structural subset

`OMPdb_hit`	Clusters
`YES`	108
`NO`	42
`UNKNOWN`	2

The two UNKNOWN clusters are absent from the available OMPdb-annotated cluster file and are therefore not assigned an inferred binary result.

Refined archived structural classification

Category	Clusters
`KNOWN_PDB`	105
`KNOWN_CATH`	38
`KNOWN_PFAM_AF`	2
`MULTI_DOMAIN_with_barrel`	1
`UNCHARACTERIZED`	6
`AMBIGUOUS`	0
`TRULY_NOVEL`	0

Collapsed publication table:

Category	Clusters
`KNOWN`	146
`UNCHARACTERIZED`	6
`NOVEL`	0

The six structurally unresolved clusters are:

216, 161, 181, 314, 215, 6867

They lack available structural models in the archived lookup and therefore require additional modelling or other follow-up analysis before a structural novelty conclusion can be made.

Interpretation of the evidence

What the workflow can support

The repository can support statements such as:

candidate β-barrel regions were prioritised through domain context and topology prediction;
clusters were enriched for PRED-TMBB2-positive members;
OMPdb profile-HMM hits identified possible known or remote sequence relationships;
whole-protein AlphaFold/TED/CATH/Foldseek evidence provided structural context;
clusters lacking sufficient evidence were retained as unresolved candidates for follow-up.

What the workflow does not establish by itself

The repository does not by itself establish:

experimental membrane localisation;
a confirmed transmembrane β-barrel fold;
absolute absence of evolutionary homology;
a newly established protein family;
biological function.

Recommended wording

Use:

“putative transmembrane β-barrel candidate”

or:

“candidate cluster with no detectable sequence- or structure-level relationship under the searches applied.”

Avoid:

“proved novel,” “truly novel,” or “confirmed new family”

unless supported by additional domain-coordinate-specific structural analysis, broader homology searches and experimental evidence.

Reproducibility

For a reproducible run, record:

Git commit hash;
Python version and pip freeze output;
HMMER, CD-HIT and PRED-TMBB2 versions;
Pfam and OMPdb database releases;
proteome source and download date;
the four partition definitions;
all thresholds and command lines;
AlphaFold DB, TED/CATH and Foldseek query dates;
any interrupted or resumed API calls;
checksums for large input and result files.

Useful commands:

git rev-parse HEAD
python --version
python -m pip freeze > environment_freeze.txt
hmmscan -h | head -n 3
cd-hit -h | head -n 3
sha256sum results/structure_validation/cluster_evidence_summary.tsv

Online resources are versioned independently of this repository. Re-running structural annotation later may therefore produce updated results.

Limitations

Predictive evidence: PRED-TMBB2 positives are computational candidates, not experimentally confirmed barrels.
Permissive OMPdb screen: i-Evalue < 0.1 is designed to retain weak relationships and must be interpreted together with recurrence, alignment coverage and biological context.
Whole-protein structural searches: Foldseek and CATH evidence may correspond to a domain outside the extracted candidate coordinates.
Database dependence: absence of a hit means no detectable hit in the database snapshot and search configuration used, not absence of homology.
Archived statistical rule: the included association output uses an unadjusted p-value criterion and does not include a multiple-testing correction.
Heuristic cluster categories: classifier labels are prioritisation aids and should not replace manual inspection or domain-specific validation.
Raw data availability: the compact repository does not redistribute the original proteome collection or large HMM/structure databases.

Citation

A manuscript citation should be added here when available.

Suggested temporary repository citation:

Kourtzelli, E. Novel β-Barrel Domain Discovery: a domain-context, topology-prediction and structural-annotation workflow. GitHub repository, accessed YYYY-MM-DD.

When using external tools and databases, also cite their original publications and the specific releases used in the analysis.

Contact

For questions, reproducibility reports or proposed improvements, open an issue in this repository.

Name		Name	Last commit message	Last commit date
results		results
scripts		scripts
tests		tests
.gitignore		.gitignore
OMPDB_FINAL_TABLE_UPDATE.md		OMPDB_FINAL_TABLE_UPDATE.md
README.md		README.md
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

Novel β-Barrel Domain Discovery

Contents

Scientific rationale

Workflow overview

Repository structure

Software and databases

Python dependencies

External command-line software

External biological resources

Installation

1. Clone the repository

2. Create a Python environment

3. Confirm the external tools

Input data

Pipeline stages

1. Remove Pfam profiles already represented in OMPdb

2. Annotate proteins and detect long unannotated regions

3. Extract unique Pfam domains per partition

4. Calculate Pfam–OMPdb co-occurrence

5. Merge partition-level contingency tables

6. Test domain associations

7. Extract candidate inter-domain regions

8. Predict β-barrel topology with PRED-TMBB2

9. Cluster candidate sequences

10. Select β-barrel-enriched sequence clusters

11. Rescan selected clusters against OMPdb

Structural validation

12. Whole-protein structural annotation

13. Build the cluster summary table

14. Classify candidate clusters

Corrected OMPdb evidence table

Definition of OMPdb_hit

Archived result summary

Corrected OMPdb summary for the 152-cluster structural subset

Refined archived structural classification

Interpretation of the evidence

What the workflow can support

What the workflow does not establish by itself

Recommended wording

Reproducibility

Limitations

Citation

Contact

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Definition of `OMPdb_hit`