stcrpy 1.0.3__tar.gz → 1.0.6__tar.gz

stcrpy-1.0.6/PKG-INFO

@@ -0,0 +1,286 @@
+Metadata-Version: 2.4
+Name: stcrpy
+Version: 1.0.6
+Summary: Set of methods to parse, annotate, and calculate features of TCR structures
+Maintainer-email: Nele Quast <quast@stats.ox.ac.uk>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENCE
+License-File: stcrpy/tcr_geometry/TCRCoM_LICENCE
+Requires-Dist: biopython
+Requires-Dist: numpy==1.26.4
+Requires-Dist: lxml
+Requires-Dist: openbabel-wheel==3.1.1.21
+Requires-Dist: rdkit
+Requires-Dist: pyhmmer==0.11.4
+Requires-Dist: anarci-mhc
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: requests
+Requires-Dist: scikit-learn
+Requires-Dist: DockQ
+Provides-Extra: ml-datasets
+Requires-Dist: einops; extra == "ml-datasets"
+Requires-Dist: torch; extra == "ml-datasets"
+Requires-Dist: torch_geometric; extra == "ml-datasets"
+Dynamic: license-file
+
+
+
+<img src="./stcrpy_logo.png" alt="drawing" width="300"/>
+
+
+# STCRpy 
+[![stcrpy installation](https://github.com/npqst/STCRpy/actions/workflows/conda-workflow.yml/badge.svg)](https://github.com/npqst/STCRpy/actions/workflows/conda-workflow.yml)
+[![stcrpy unittests](https://github.com/npqst/STCRpy/actions/workflows/unittest-workflow.yml/badge.svg)](https://github.com/npqst/STCRpy/actions/workflows/unittest-workflow.yml)
+[![stcrpy_docs](https://readthedocs.org/projects/stcrpy/badge/?version=latest)](https://stcrpy.readthedocs.io/en/latest/)
+
+
+Structural TCR python (STCRpy) is a software suite for analysing and processing T-cell receptor structures. 
+
+Please feel free to reach out with any comments or feedback.
+
+Under review, please cite: 
+
+**Quast, N. , Deane, C., & Raybould, M. (2025). STCRpy: a software suite for TCR:pMHC structure parsing, interaction profiling, and machine learning dataset preparation. Bioinformatics. [https://doi.org/10.1093/bioinformatics/btaf566](https://doi.org/10.1093/bioinformatics/btaf566)**
+
+<img src="./stcrpy_main_fig.png" alt="drawing" width="1500"/>
+
+
+
+# Installation
+
+## TL;DR installation
+```
+pip install stcrpy
+pip install plip
+conda install pymol-open-source -y
+ANARCI --build_models           # this step will take a few minutes
+```
+
+## Step by step installation
+We recommend installing STCRpy in a [conda](https://www.anaconda.com/docs/getting-started/miniconda/install#macos-linux-installation) (or [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html)) environment using python 3.9 to 3.12. You can also use a python virtual environment if you do not need pymol visualisations. 
+
+<details> <summary>conda</summary>
+
+```
+conda create -n stcrpy_env python==3.12 -y
+conda activate stcrpy_env
+```
+
+</details>
+<details> <summary>mamba</summary>
+
+```
+mamba create -n stcrpy_env python==3.12 -y
+mamba activate stcrpy_env
+```
+
+</details>
+<details> <summary>venv</summary>
+
+```
+python -m venv stcrpy_env
+source stcrpy_env/bin/activate
+```
+
+</details>
+
+
+The core functionality of STCRpy can be installed as follows:
+```
+pip install stcrpy
+```
+
+After installing stcrpy, the anarci HMM models must be built to enable annotation.
+```
+ANARCI --build_models           # this step will take a few minutes
+```
+
+To enable interaction profiling, install PLIP (Adasme et. al., 2021):
+```
+pip install plip
+```
+
+To enable pymol visualisations, install pymol open source locally within the environment. Unfortunately, pymol currently needs to be installed even if you already have a pymol version. Be sure to install pymol within a managed conda (or mamba) environment to prevent interference with any existing versions. 
+```
+conda install pymol-open-source -y
+```
+
+To generate pytorch and pytorch-geometric compatible datasets (see the [pytorch docs](https://pytorch.org/get-started/locally/) for hardware specific instructions): 
+```
+pip install stcrpy[ml_datasets]
+```
+
+> Note that the installs for pytorch can be platform specific.
+> If errors are ecountered here it is best to manually install the depedencies following the [pytorch installation docs](https://pytorch.org/get-started/locally/).
+> For example:
+> ```
+> pip install torch --index-url https://download.pytorch.org/whl/cpu
+> pip install torch_geometric
+> ```
+> This installs the CPU version of pytorch (for GPU / CUDA versions follow the install [pytorch installation docs](https://pytorch.org/get-started/locally/)).
+>
+> The EGNN example also uses `einops`. Which can be manually installed as follows:
+> ```
+> pip install einops
+> ```
+
+# Documentation
+STCRpy [documentation](https://stcrpy.readthedocs.io/en/latest/) is hosted on ReadtheDocs.
+
+# Examples
+STCRpy generates and operates on TCR structure objects. The majority of the API can be accessed through functions of the format: `tcr.some_stcrpy_function()`. ([See TCR object docs here](https://stcrpy.readthedocs.io/en/latest/stcrpy.tcr_processing.html#stcrpy.tcr_processing.TCR.TCR)). TCR objects are associated with their MHC and antigen if these are presented in the structure. 
+
+A notebook with examples can be found under [examples/STCRpy_examples.ipynb](./examples/STCRpy_examples.ipynb)
+
+First import STCRpy:
+```
+import stcrpy
+```
+
+### To fetch a TCR structure from STCRDab or the PDB: 
+```
+multiple_tcrs = stcrpy.fetch_TCRs("8gvb")
+```
+This will return a list of all of the TCR structures found in the PDB file, represented as TCR structure objects.
+
+### To load a TCR structure from a PDB or MMCIF file:
+```
+tcr = stcrpy.load_TCR("filename.{pdb, cif}")
+```
+
+### To load multiple TCR structures from a list of files at once:
+```
+multiple_tcrs = stcrpy.load_TCRs([file_1, file_2, file_3])
+```
+
+### To save a TCR object to PDB or MMCIF files: 
+```
+tcr.save(filename.{pdb, cif})           # save the TCR and it's associated MHC and antigen
+tcr.save(filename.{pdb, cif}, TCR_only=True)           # save the TCR only
+```
+
+### To calculate the TCR to pMHC geometry:
+```
+tcr.calculate_geometry()            # change the 'mode' keyword argument to change the geometry calculation method. See paper / documentation for details.
+```
+
+### To score the TCR to pMHC geometry:
+```
+tcr.score_docking_geometry()
+```
+
+### To profile interactions: 
+```
+tcr.profile_peptide_interactions()          # interaction profiling parameters can be adjusted, see documentation for details
+```
+
+### To visualise interactions:
+```
+tcr.visualise_interactions()
+```
+
+### To run full analysis on a set of TCR structures: 
+```
+from stcrpy.tcr_methods.tcr_batch_operations import analyse_tcrs
+germlines_and_alleles_df, geometries_df, interactions_df = analyse_tcrs(list_or_dict_of_files)
+```
+
+### To generate graph datasets:
+```
+dataset = TCRGraphDataset(
+            root=PATH_TO_DATASET,
+            data_paths=PATH_TO_TCR_FILES
+        )
+```
+
+### To calculate TCR prediction metrics such as RMSD, interface RMSD (of the TCR:pMHC interface) or DockQ scores:
+
+```
+# RMSD
+from stcrpy.tcr_metrics import RMSD
+
+rmsd_calculator = RMSD()
+rmsd = rmsd_calculator.calculate_rmsd(pred_tcr, reference_tcr, save_alignment=False)      # Calculates the RMSD of each region of the TCR. To check the alignment set save_alignment to True.
+
+# To calculate RMSD for a set of predictions against a set of reference structures from files: 
+files = list(zip(prediction_files, reference_files))
+rmsd_df = rmsd_calculator.rmsd_from_files(files)
+
+
+
+# Interface RMSD of TCR:pMHC interface
+from stcrpy.tcr_metrics import InterfaceRMSD
+
+interface_rmsd_calculator = InterfaceRMSD()
+irmsds = interface_rmsd_calculator.get_interface_rmsd(tcr, reference_tcr)
+
+# DockQ
+from stcrpy.tcr_metrics.tcr_dockq import TCRDockQ
+
+dockq_calculator = TCRDockQ()               # by default this will merge the TCR and pMHC chains and calculate DockQ of the complete TCR:pMHC interface. To calculate DockQ scores per chain, use TCR_pMHC_interface=False
+dockq_results = dockq_calculator.tcr_dockq(tcr, reference_tcr, save_merged_complex=False)           # to investigate the merged TCR:pMHC structure set save_merged_complex=True 
+
+```
+
+### Torsion angles and internal coordinates
+STCRpy builds upon the Biopython PDB module, and you can calculate the internal coordinates, such as backbone torsion angles, using the [`internal_coordinates` function](https://biopython.org/docs/dev/api/Bio.PDB.internal_coords.html).
+
+```
+# internal coordinate calculations should be made per chain
+for c in tcr.get_chains():
+    c.atom_to_internal_coordinates()            # calculate the internal coordinates 
+
+# internal coordinates can be accessed per residue: 
+res = next(tcr.get_residues())
+res.internal_coord.get_angle("psi")         # retrieve angles via angle keys
+```
+
+### Domain angles between TCR chains
+STCRpy can be used to calculate the geometry and angles between the TCR variable domains of abTCRs and gdTCRs. This follows the ABangle implementation [(Dunbar et al. 2013)](https://academic.oup.com/peds/article/26/10/611/1509255).
+```
+tcr.get_TCR_angles()
+
+# returns dictionary of TCR domain angles and measurements.
+# For example: 
+# {
+#    'BA': -56.72234454750631,
+#    'BC1': 122.55277240895967,
+#    'AC1': 73.96532018128327,
+#    'BC2': 82.63524566165464,
+#    'AC2': 99.60327202896609,
+#    'dc': np.float64(15.606353954437227)
+# }
+
+```
+
+
+# Symmetry mate handling
+Some TCR:pMHC crystals are formed of repeating cell units in which the TCR and the antigen do not directly contact. 
+STCRpy generates symmetry mates in these cases to pair pMHC with TCRs in the structure. 
+Note that symmetry mate generation requires pymol to be installed. By default, symmetry mate generation is enabled, however, it can be toggled by setting: 
+`include_symmetry_mates=False` in `get_tcr_structure`. 
+
+## Example: 
+```
+tcr_6ulr_paired_antigen = stcrpy.fetch_TCRs("6ulr")
+tcr_6ulr_no_antigen = stcrpy.fetch_TCRs("6ulr", include_symmetry_mates=False)       # does not generate symmetry mates
+
+```
+
+
+
+# Limitations
+
+## Connected peptide chains
+STCRpy is currently not configured to handle cases where the antigen peptide is connected to the TCR or MHC chain - this is primarily because the parsing pipeline operates on chain objects and it can be tricky to consistently separate the peptide segment from the remainder of the TCR chain. A known case is PDB code 6MNO. 
+
+## Gamma-Delta TCR geometry
+STCRpy supports gamma-delta TCR parsing, interaction profiling and visusalisation, but is not currently configured to calculate gd-TCR geometry.
+
+## MHC Class II geometry scoring
+STCRpy can be used to calculate and characterise the geometries of TCRs to MHC class II antigen, however, due to the smaller number of complexes we have not fit parametric distributions to the geometry features, which means it is not possible to calculate a geometry score.
+
+

stcrpy-1.0.6/README.md

@@ -0,0 +1,258 @@
+
+
+<img src="./stcrpy_logo.png" alt="drawing" width="300"/>
+
+
+# STCRpy 
+[![stcrpy installation](https://github.com/npqst/STCRpy/actions/workflows/conda-workflow.yml/badge.svg)](https://github.com/npqst/STCRpy/actions/workflows/conda-workflow.yml)
+[![stcrpy unittests](https://github.com/npqst/STCRpy/actions/workflows/unittest-workflow.yml/badge.svg)](https://github.com/npqst/STCRpy/actions/workflows/unittest-workflow.yml)
+[![stcrpy_docs](https://readthedocs.org/projects/stcrpy/badge/?version=latest)](https://stcrpy.readthedocs.io/en/latest/)
+
+
+Structural TCR python (STCRpy) is a software suite for analysing and processing T-cell receptor structures. 
+
+Please feel free to reach out with any comments or feedback.
+
+Under review, please cite: 
+
+**Quast, N. , Deane, C., & Raybould, M. (2025). STCRpy: a software suite for TCR:pMHC structure parsing, interaction profiling, and machine learning dataset preparation. Bioinformatics. [https://doi.org/10.1093/bioinformatics/btaf566](https://doi.org/10.1093/bioinformatics/btaf566)**
+
+<img src="./stcrpy_main_fig.png" alt="drawing" width="1500"/>
+
+
+
+# Installation
+
+## TL;DR installation
+```
+pip install stcrpy
+pip install plip
+conda install pymol-open-source -y
+ANARCI --build_models           # this step will take a few minutes
+```
+
+## Step by step installation
+We recommend installing STCRpy in a [conda](https://www.anaconda.com/docs/getting-started/miniconda/install#macos-linux-installation) (or [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html)) environment using python 3.9 to 3.12. You can also use a python virtual environment if you do not need pymol visualisations. 
+
+<details> <summary>conda</summary>
+
+```
+conda create -n stcrpy_env python==3.12 -y
+conda activate stcrpy_env
+```
+
+</details>
+<details> <summary>mamba</summary>
+
+```
+mamba create -n stcrpy_env python==3.12 -y
+mamba activate stcrpy_env
+```
+
+</details>
+<details> <summary>venv</summary>
+
+```
+python -m venv stcrpy_env
+source stcrpy_env/bin/activate
+```
+
+</details>
+
+
+The core functionality of STCRpy can be installed as follows:
+```
+pip install stcrpy
+```
+
+After installing stcrpy, the anarci HMM models must be built to enable annotation.
+```
+ANARCI --build_models           # this step will take a few minutes
+```
+
+To enable interaction profiling, install PLIP (Adasme et. al., 2021):
+```
+pip install plip
+```
+
+To enable pymol visualisations, install pymol open source locally within the environment. Unfortunately, pymol currently needs to be installed even if you already have a pymol version. Be sure to install pymol within a managed conda (or mamba) environment to prevent interference with any existing versions. 
+```
+conda install pymol-open-source -y
+```
+
+To generate pytorch and pytorch-geometric compatible datasets (see the [pytorch docs](https://pytorch.org/get-started/locally/) for hardware specific instructions): 
+```
+pip install stcrpy[ml_datasets]
+```
+
+> Note that the installs for pytorch can be platform specific.
+> If errors are ecountered here it is best to manually install the depedencies following the [pytorch installation docs](https://pytorch.org/get-started/locally/).
+> For example:
+> ```
+> pip install torch --index-url https://download.pytorch.org/whl/cpu
+> pip install torch_geometric
+> ```
+> This installs the CPU version of pytorch (for GPU / CUDA versions follow the install [pytorch installation docs](https://pytorch.org/get-started/locally/)).
+>
+> The EGNN example also uses `einops`. Which can be manually installed as follows:
+> ```
+> pip install einops
+> ```
+
+# Documentation
+STCRpy [documentation](https://stcrpy.readthedocs.io/en/latest/) is hosted on ReadtheDocs.
+
+# Examples
+STCRpy generates and operates on TCR structure objects. The majority of the API can be accessed through functions of the format: `tcr.some_stcrpy_function()`. ([See TCR object docs here](https://stcrpy.readthedocs.io/en/latest/stcrpy.tcr_processing.html#stcrpy.tcr_processing.TCR.TCR)). TCR objects are associated with their MHC and antigen if these are presented in the structure. 
+
+A notebook with examples can be found under [examples/STCRpy_examples.ipynb](./examples/STCRpy_examples.ipynb)
+
+First import STCRpy:
+```
+import stcrpy
+```
+
+### To fetch a TCR structure from STCRDab or the PDB: 
+```
+multiple_tcrs = stcrpy.fetch_TCRs("8gvb")
+```
+This will return a list of all of the TCR structures found in the PDB file, represented as TCR structure objects.
+
+### To load a TCR structure from a PDB or MMCIF file:
+```
+tcr = stcrpy.load_TCR("filename.{pdb, cif}")
+```
+
+### To load multiple TCR structures from a list of files at once:
+```
+multiple_tcrs = stcrpy.load_TCRs([file_1, file_2, file_3])
+```
+
+### To save a TCR object to PDB or MMCIF files: 
+```
+tcr.save(filename.{pdb, cif})           # save the TCR and it's associated MHC and antigen
+tcr.save(filename.{pdb, cif}, TCR_only=True)           # save the TCR only
+```
+
+### To calculate the TCR to pMHC geometry:
+```
+tcr.calculate_geometry()            # change the 'mode' keyword argument to change the geometry calculation method. See paper / documentation for details.
+```
+
+### To score the TCR to pMHC geometry:
+```
+tcr.score_docking_geometry()
+```
+
+### To profile interactions: 
+```
+tcr.profile_peptide_interactions()          # interaction profiling parameters can be adjusted, see documentation for details
+```
+
+### To visualise interactions:
+```
+tcr.visualise_interactions()
+```
+
+### To run full analysis on a set of TCR structures: 
+```
+from stcrpy.tcr_methods.tcr_batch_operations import analyse_tcrs
+germlines_and_alleles_df, geometries_df, interactions_df = analyse_tcrs(list_or_dict_of_files)
+```
+
+### To generate graph datasets:
+```
+dataset = TCRGraphDataset(
+            root=PATH_TO_DATASET,
+            data_paths=PATH_TO_TCR_FILES
+        )
+```
+
+### To calculate TCR prediction metrics such as RMSD, interface RMSD (of the TCR:pMHC interface) or DockQ scores:
+
+```
+# RMSD
+from stcrpy.tcr_metrics import RMSD
+
+rmsd_calculator = RMSD()
+rmsd = rmsd_calculator.calculate_rmsd(pred_tcr, reference_tcr, save_alignment=False)      # Calculates the RMSD of each region of the TCR. To check the alignment set save_alignment to True.
+
+# To calculate RMSD for a set of predictions against a set of reference structures from files: 
+files = list(zip(prediction_files, reference_files))
+rmsd_df = rmsd_calculator.rmsd_from_files(files)
+
+
+
+# Interface RMSD of TCR:pMHC interface
+from stcrpy.tcr_metrics import InterfaceRMSD
+
+interface_rmsd_calculator = InterfaceRMSD()
+irmsds = interface_rmsd_calculator.get_interface_rmsd(tcr, reference_tcr)
+
+# DockQ
+from stcrpy.tcr_metrics.tcr_dockq import TCRDockQ
+
+dockq_calculator = TCRDockQ()               # by default this will merge the TCR and pMHC chains and calculate DockQ of the complete TCR:pMHC interface. To calculate DockQ scores per chain, use TCR_pMHC_interface=False
+dockq_results = dockq_calculator.tcr_dockq(tcr, reference_tcr, save_merged_complex=False)           # to investigate the merged TCR:pMHC structure set save_merged_complex=True 
+
+```
+
+### Torsion angles and internal coordinates
+STCRpy builds upon the Biopython PDB module, and you can calculate the internal coordinates, such as backbone torsion angles, using the [`internal_coordinates` function](https://biopython.org/docs/dev/api/Bio.PDB.internal_coords.html).
+
+```
+# internal coordinate calculations should be made per chain
+for c in tcr.get_chains():
+    c.atom_to_internal_coordinates()            # calculate the internal coordinates 
+
+# internal coordinates can be accessed per residue: 
+res = next(tcr.get_residues())
+res.internal_coord.get_angle("psi")         # retrieve angles via angle keys
+```
+
+### Domain angles between TCR chains
+STCRpy can be used to calculate the geometry and angles between the TCR variable domains of abTCRs and gdTCRs. This follows the ABangle implementation [(Dunbar et al. 2013)](https://academic.oup.com/peds/article/26/10/611/1509255).
+```
+tcr.get_TCR_angles()
+
+# returns dictionary of TCR domain angles and measurements.
+# For example: 
+# {
+#    'BA': -56.72234454750631,
+#    'BC1': 122.55277240895967,
+#    'AC1': 73.96532018128327,
+#    'BC2': 82.63524566165464,
+#    'AC2': 99.60327202896609,
+#    'dc': np.float64(15.606353954437227)
+# }
+
+```
+
+
+# Symmetry mate handling
+Some TCR:pMHC crystals are formed of repeating cell units in which the TCR and the antigen do not directly contact. 
+STCRpy generates symmetry mates in these cases to pair pMHC with TCRs in the structure. 
+Note that symmetry mate generation requires pymol to be installed. By default, symmetry mate generation is enabled, however, it can be toggled by setting: 
+`include_symmetry_mates=False` in `get_tcr_structure`. 
+
+## Example: 
+```
+tcr_6ulr_paired_antigen = stcrpy.fetch_TCRs("6ulr")
+tcr_6ulr_no_antigen = stcrpy.fetch_TCRs("6ulr", include_symmetry_mates=False)       # does not generate symmetry mates
+
+```
+
+
+
+# Limitations
+
+## Connected peptide chains
+STCRpy is currently not configured to handle cases where the antigen peptide is connected to the TCR or MHC chain - this is primarily because the parsing pipeline operates on chain objects and it can be tricky to consistently separate the peptide segment from the remainder of the TCR chain. A known case is PDB code 6MNO. 
+
+## Gamma-Delta TCR geometry
+STCRpy supports gamma-delta TCR parsing, interaction profiling and visusalisation, but is not currently configured to calculate gd-TCR geometry.
+
+## MHC Class II geometry scoring
+STCRpy can be used to calculate and characterise the geometries of TCRs to MHC class II antigen, however, due to the smaller number of complexes we have not fit parametric distributions to the geometry features, which means it is not possible to calculate a geometry score.
+
+

stcrpy-1.0.6/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stcrpy"
+version = "1.0.6"
+description = "Set of methods to parse, annotate, and calculate features of TCR structures"
+readme = "README.md"
+license-files = [
+    "LICENCE",
+    "stcrpy/tcr_geometry/TCRCoM_LICENCE",
+]
+maintainers = [
+  {name = "Nele Quast", email = "quast@stats.ox.ac.uk"}
+]
+requires-python = ">=3.10"
+dependencies = [
+  "biopython",
+  "numpy==1.26.4",      # required by DockQ
+  "lxml",
+  "openbabel-wheel==3.1.1.21",
+  "rdkit",
+  "pyhmmer==0.11.4",        # fix pyhmmer version to prevent string encoding bu. TODO:fix this within anarci-mhc directly and redeploy
+  "anarci-mhc",
+  "pandas",
+  "matplotlib",
+  "scipy",
+  "requests",
+  "scikit-learn",
+  "DockQ",
+]
+
+[project.optional-dependencies]
+ml_datasets = [
+    "einops",
+    "torch",
+    "torch_geometric",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+exclude = ["test", "test.*"]
+
+[tool.setuptools.package-data]
+stcrpy = ["tcr_geometry/reference_data/*", ]

{stcrpy-1.0.3 → stcrpy-1.0.6}/stcrpy/__init__.py

@@ -2,4 +2,4 @@ from .tcr_processing.TCRParser import TCRParser
 from .tcr_processing.TCRIO import TCRIO
 from .tcr_geometry.TCRDock import TCRDock
 from .tcr_geometry.TCRGeom import TCRGeom
-from .tcr_methods.tcr_methods import load_TCRs, fetch_TCR, yield_TCRs, load_TCR
+from .tcr_methods.tcr_methods import load_TCRs, fetch_TCRs, yield_TCRs, load_TCR

{stcrpy-1.0.3 → stcrpy-1.0.6}/stcrpy/tcr_formats/tcr_formats.py

@@ -99,7 +99,7 @@ def get_sequences(
             for chain in entity.get_chains()
         }
     except AttributeError as e:
-        if entity.level == "C":
+        if entity.level == "C" or entity.level == "F":  # covers chains and fragments
             sequences = {
                 entity.id: seq1(
                     "".join(
@@ -112,3 +112,22 @@ def get_sequences(
     if amino_acids_only:
         sequences = {k: seq.replace("X", "") for k, seq in sequences.items()}
     return sequences
+
+
+def merge_chains(chains, new_chain_id=None):
+    from Bio import PDB
+
+    if new_chain_id is None:
+        new_chain_id = f"{chains[0].id}_{chains[1].id}"
+    new_chain = PDB.Chain.Chain(new_chain_id)
+    new_res_id = 1
+
+    for chain in chains:
+        for residue in chain.get_residues():
+            new_residue = residue.copy()
+            new_residue.id = (" ", new_res_id, " ")
+
+            new_chain.add(new_residue)
+            new_res_id += 1
+
+    return new_chain