kdock 2025.10.31__py3-none-any.whl

kdock/core/ligand.py

@@ -0,0 +1,294 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/03_ligand.ipynb.
+
+# %% auto 0
+__all__ = ['plot_drug', 'rdkit_conformer', 'tanimoto', 'get_rdkit', 'get_rdkit_3d', 'get_rdkit_all', 'remove_hi_corr',
+           'preprocess', 'get_rdkit_df', 'get_fp', 'compress_fp', 'tanimoto_numba', 'hash_fp', 'get_same_mol_group']
+
+# %% ../../nbs/core/03_ligand.ipynb 3
+import pandas as pd, numpy as np
+from rdkit import Chem,RDLogger,DataStructs
+from rdkit.Chem import Draw, rdDepictor, Descriptors,Descriptors3D, AllChem
+from skfp.fingerprints import AtomPairFingerprint, ECFPFingerprint, MACCSFingerprint
+import hashlib,numba
+from .data import *
+
+from tqdm.contrib.concurrent import process_map
+from tqdm import tqdm
+RDLogger.DisableLog('rdApp.warning')
+
+# %% ../../nbs/core/03_ligand.ipynb 5
+def plot_drug(drug_dict, flip_list=None, save_path=None):
+    flip_list = flip_list or []
+    mols = []
+
+    for name, smi in drug_dict.items():
+        mol = Chem.MolFromSmiles(smi)
+        rdDepictor.Compute2DCoords(mol)
+
+        # Flip horizontally if requested
+        if name in flip_list:
+            conf = mol.GetConformer()
+            for i in range(conf.GetNumAtoms()):
+                x, y, z = conf.GetAtomPosition(i)
+                conf.SetAtomPosition(i, (-x, y, z))
+
+        mol.SetProp("_Name", name)
+        mols.append(mol)
+
+    # Draw to SVG
+    svg_obj = Draw.MolsToGridImage(
+        mols,
+        molsPerRow=3,
+        subImgSize=(300, 250),
+        legends=[m.GetProp("_Name") for m in mols],
+        useSVG=True
+    )
+
+    svg_str = getattr(svg_obj, "data", getattr(svg_obj, "GetDrawingText", lambda: svg_obj)())
+
+    if save_path:
+        with open(save_path, "w", encoding="utf-8") as f:
+            f.write(svg_str)
+        print(f"✅ Saved structure grid to: {save_path}")
+    else:
+        # from IPython.display import SVG, display
+        # display(SVG(svg_str))
+        return svg_obj
+
+# %% ../../nbs/core/03_ligand.ipynb 8
+def rdkit_conformer(SMILES, # SMILES string
+                    output=None, # file ".sdf" to be saved
+                    method='ETKDG', # Optimization method, can be 'UFF', 'MMFF' or 'ETKDGv3'
+                    visualize=True, #whether or not to visualize the compound
+                    seed = 3,# randomness of the 3D conformation
+                    ):
+
+    "Gemerate 3D conformers from SMILES"
+    
+    np.random.seed(seed) 
+    mol = Chem.MolFromSmiles(SMILES)
+    
+    # Generate a 3D conformation of the molecule
+    AllChem.EmbedMolecule(mol)
+    
+
+    # Optimize the 3D conformation using the specified force field method
+    if method == 'UFF':
+        AllChem.UFFOptimizeMolecule(mol)
+    elif method == 'MMFF':
+        AllChem.MMFFOptimizeMolecule(mol)
+    elif method == 'ETKDG':
+        AllChem.EmbedMultipleConfs(mol, numConfs=1, useExpTorsionAnglePrefs=True, 
+                                   useBasicKnowledge=True, enforceChirality=True,randomSeed=seed)
+        AllChem.ETKDGv3()
+        AllChem.UFFOptimizeMolecule(mol)
+
+    else:
+        raise ValueError('Invalid method specified')
+        
+
+    # Remove hydrogens from the molecule
+    # mol = Chem.RemoveHs(mol)
+
+    if output is not None:
+        Path(output).parent.mkdir(parents=True,exist_ok=True)
+    
+        w = Chem.SDWriter(output)
+        w.write(mol)
+        w.close()
+    return mol
+
+# %% ../../nbs/core/03_ligand.ipynb 10
+def tanimoto(df, # df with SMILES and ID columns
+             smiles_col='SMILES', # colname of SMILES
+             id_col='ID', # colname of compound ID
+             target_col=None, # colname of compound values (e.g., IC50)
+             radius=2, # radius of the Morgan fingerprint.
+             ):
+    "Calculates the Tanimoto similarity scores between all pairs of molecules in a pandas DataFrame."
+    
+    df = df.copy()
+    # Convert SMILES to molecule objects
+    df['Molecule'] = df[smiles_col].apply(lambda x: Chem.MolFromSmiles(x))
+
+    # Calculate fingerprints
+    df['Fingerprint'] = df['Molecule'].apply(lambda x: AllChem.GetMorganFingerprintAsBitVect(x, radius))
+
+    # Calculate similarity scores
+    similarity_scores = []
+    for i in range(len(df)):
+        for j in range(i+1, len(df)):
+            sim_score = DataStructs.TanimotoSimilarity(df['Fingerprint'][i], df['Fingerprint'][j])
+            if target_col is not None:
+                similarity_scores.append((df[id_col][i], df[id_col][j], df[smiles_col][i], df[smiles_col][j], sim_score, df[target_col][i], df[target_col][j]))
+            else:
+                similarity_scores.append((df[id_col][i], df[id_col][j], df[smiles_col][i], df[smiles_col][j], sim_score))
+
+    # Create a new DataFrame with the similarity scores
+    if target_col is not None:
+        result_df = pd.DataFrame(similarity_scores, columns=['ID1', 'ID2', 'SMILES1', 'SMILES2', 'SimilarityScore', 'Target1', 'Target2'])
+    else:
+        result_df = pd.DataFrame(similarity_scores, columns=['ID1', 'ID2', 'SMILES1', 'SMILES2', 'SimilarityScore'])
+
+    # Sort by similarity score in descending order
+    result_df.sort_values('SimilarityScore', ascending=False, inplace=True)
+    result_df = result_df.reset_index(drop=True)
+
+    return result_df
+
+# %% ../../nbs/core/03_ligand.ipynb 14
+def get_rdkit(SMILES:str):
+    """
+    Extract chemical features from SMILES
+    Reference: https://greglandrum.github.io/rdkit-blog/posts/2022-12-23-descriptor-tutorial.html
+    """
+    mol = Chem.MolFromSmiles(SMILES)
+    return Descriptors.CalcMolDescriptors(mol)
+
+# %% ../../nbs/core/03_ligand.ipynb 15
+def get_rdkit_3d(SMILES:str):
+    "Extract 3d features from SMILES"
+    mol = Chem.MolFromSmiles(SMILES)
+    mol = Chem.AddHs(mol)
+    AllChem.EmbedMolecule(mol, AllChem.ETKDG())
+    AllChem.UFFOptimizeMolecule(mol)
+    return Descriptors3D.CalcMolDescriptors3D(mol)
+
+# %% ../../nbs/core/03_ligand.ipynb 16
+def get_rdkit_all(SMILES:str):
+    "Extract chemical features and 3d features from SMILES"
+    feat = get_rdkit(SMILES)
+    feat_3d = get_rdkit_3d(SMILES)
+    return feat|feat_3d
+
+# %% ../../nbs/core/03_ligand.ipynb 17
+def remove_hi_corr(df: pd.DataFrame, 
+                   thr=0.99 # threshold
+                   ):
+    "Remove highly correlated features in a dataframe given a pearson threshold"
+    corr_matrix = df.corr().abs()
+    upper = corr_matrix.where(np.triu(np.ones(corr_matrix.shape), k=1).astype(bool))
+    to_drop = [column for column in upper.columns if any(upper[column] > thr)]
+    return df.drop(to_drop, axis=1), to_drop
+
+# %% ../../nbs/core/03_ligand.ipynb 18
+def preprocess(df: pd.DataFrame, thr=0.99):
+    "Remove features with no variance, and highly correlated features based on threshold."
+    col_ori = df.columns
+
+    # Remove columns with std == 0
+    std_zero_cols = df.columns[df.std() == 0].tolist()
+    
+    if std_zero_cols:
+        n=len(std_zero_cols)
+        print(f"\n {n} Columns with zero std: {std_zero_cols}")
+    df = df.loc[:, df.std() != 0].copy()
+
+    # Remove highly correlated columns
+    df, high_corr_cols = remove_hi_corr(df, thr)
+    if high_corr_cols:
+        n=len(high_corr_cols)
+        print(f"\n {n} Columns removed due to high similarity (pearson>{thr}): {high_corr_cols}")
+
+    dropping_col = set(col_ori) - set(df.columns)
+    n = len(dropping_col)
+    print(f"\n Total removed columns: {n}")
+    
+    return df
+
+# %% ../../nbs/core/03_ligand.ipynb 19
+def get_rdkit_df(df: pd.DataFrame,
+                 include_3d=False,
+                 col='SMILES',
+                 postprocess=False,
+                 chunksize=128, # for parallel process_map 
+                 ):
+    "Extract rdkit features (optionally in parallel with 3D) from SMILES in a df"
+    func = get_rdkit_all if include_3d else get_rdkit
+    smiles_list = df[col].tolist()
+
+    features = process_map(func, smiles_list,chunksize=chunksize)
+
+    out = pd.DataFrame(features)
+
+    if postprocess:
+        out = StandardScaler().fit_transform(out)
+        out = preprocess(out) # remove redundant
+
+    return out
+
+# %% ../../nbs/core/03_ligand.ipynb 25
+def get_fp(SMILES, 
+           name='ecfp',
+           ELEMENTS_PER_WORKER = 1_000_000):
+    "Super fast method to get molecule fingerprints using scikit-fingerprints"
+    if name == 'ecfp':
+        fp_transformer = ECFPFingerprint(fp_size=2048, radius=3, n_jobs=-1)
+    elif name == 'ap':
+        fp_transformer = AtomPairFingerprint(fp_size=2048, n_jobs=-1)
+    elif name == 'maccs':
+        fp_transformer = MACCSFingerprint(n_jobs=-1)
+    else:
+        raise Exception('Wrong fingerprint name!')
+    
+    middle_parts = []
+    k_splits = len(SMILES) // ELEMENTS_PER_WORKER
+        
+    for i in tqdm(range(k_splits)):
+        middle_parts.append(fp_transformer.transform(SMILES[i * ELEMENTS_PER_WORKER: (i + 1) * ELEMENTS_PER_WORKER]))
+        
+    if len(SMILES) % ELEMENTS_PER_WORKER > 0:   
+        middle_parts.append(fp_transformer.transform(SMILES[k_splits * ELEMENTS_PER_WORKER:]))
+    
+    return np.concatenate(middle_parts)
+
+# %% ../../nbs/core/03_ligand.ipynb 29
+def compress_fp(array):
+    "Compress binary finterprints using np.packbits"
+    return np.packbits(array,axis=1)
+
+# %% ../../nbs/core/03_ligand.ipynb 47
+@numba.njit(parallel=True)
+def tanimoto_numba(fps):
+    "Get a NxN matrix of tanimoto similarity among N compounds."
+    n = fps.shape[0]
+    result = np.zeros((n, n), dtype=np.float32)
+    
+    for i in numba.prange(n):
+        for j in range(i, n):  # only upper triangle
+            inter = np.bitwise_and(fps[i], fps[j]).sum()
+            union = np.bitwise_or(fps[i], fps[j]).sum()
+            sim = inter / union if union > 0 else 0.0
+            result[i, j] = sim
+            result[j, i] = sim  # fill symmetric position
+    return result
+
+# %% ../../nbs/core/03_ligand.ipynb 50
+def hash_fp(fp_row):
+    "Hash a binary fingerprint row using SHA256"
+    return hashlib.sha256(fp_row.tobytes()).hexdigest()
+
+# %% ../../nbs/core/03_ligand.ipynb 52
+def get_same_mol_group(df, smi_col='SMILES'):
+    "Assign a group number to the same compounds by utilizing hash sha256 to encode morgan fp and find same molecule."
+    df = df.copy()
+    smiles = df[smi_col].tolist()
+    
+    fps = get_fp(smiles)
+    
+    # Hash each fingerprint
+    # hashes = [hash_fp(fp) for fp in fps] # non-parallel
+    hashes = process_map(hash_fp, fps, chunksize=256) # if parallel
+    
+    # Assign a group number based on hash buckets
+    hash_to_group = {}
+    group_ids = []
+    group_counter = 0
+    for h in hashes:
+        if h not in hash_to_group:
+            hash_to_group[h] = group_counter
+            group_counter += 1
+        group_ids.append(hash_to_group[h])
+    
+    df['group'] = group_ids
+    return df

kdock/core/plot.py

@@ -0,0 +1,89 @@
+"""Functions to plot on 2D"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/04_plot.ipynb.
+
+# %% auto 0
+__all__ = ['reduce_feature', 'set_sns', 'plot_2d', 'plot_corr']
+
+# %% ../../nbs/core/04_plot.ipynb 3
+import pandas as pd, seaborn as sns
+from fastcore.meta import delegates
+from matplotlib import pyplot as plt
+
+# # kdock
+# from kdock.core.data import *
+
+# dimentional reduction
+from sklearn.decomposition import PCA
+from sklearn.manifold import TSNE
+from umap import UMAP
+
+# %% ../../nbs/core/04_plot.ipynb 6
+def reduce_feature(data, # df or numpy array
+                   method='pca', # dimensionality reduction method, accept both capital and lower case
+                   complexity=20, # None for PCA; perfplexity for TSNE, recommend: 30; n_neigbors for UMAP, recommend: 15
+                   n=2, # n_components
+                   seed: int=123, # seed for random_state
+                   **kwargs, # arguments from PCA, TSNE, or UMAP depends on which method to use
+                  ):
+    
+    "Reduce the dimensionality given a dataframe of values"
+    
+    method = method.lower()
+    assert method in ['pca','tsne','umap'], "Please choose a method among PCA, TSNE, and UMAP"
+
+    if method == 'pca':
+        reducer = PCA(n_components=n, random_state=seed,**kwargs)
+    elif method == 'tsne':
+        reducer = TSNE(n_components=n,
+                       random_state=seed, 
+                       perplexity = complexity, # default from official is 30 
+                      **kwargs)
+    elif method == 'umap':
+        reducer = UMAP(n_components=n, 
+                       random_state=seed, 
+                       n_neighbors=complexity, # default from official is 15, try 15-200
+                      **kwargs)
+    else:
+        raise ValueError('Invalid method specified')
+
+    proj = reducer.fit_transform(data)
+    embedding_df = pd.DataFrame(proj).set_index(data.index) if isinstance(data,pd.DataFrame) else pd.DataFrame(proj)
+    embedding_df.columns = [f"{method.upper()}{i}" for i in range(1, n + 1)]
+
+    return embedding_df
+
+# %% ../../nbs/core/04_plot.ipynb 10
+def set_sns():
+    sns.set(rc={"figure.dpi":300, 'savefig.dpi':300})
+    sns.set_context('notebook')
+    sns.set_style("ticks")
+
+# %% ../../nbs/core/04_plot.ipynb 12
+@delegates(sns.scatterplot)
+def plot_2d(X: pd.DataFrame, # a dataframe that has first column to be x, and second column to be y
+            **kwargs, # arguments for sns.scatterplot
+            ):
+    "Make 2D plot from a dataframe that has first column to be x, and second column to be y"
+    plt.figure(figsize=(7,7))
+    sns.scatterplot(data = X,x=X.columns[0],y=X.columns[1],alpha=0.7,**kwargs)
+
+# %% ../../nbs/core/04_plot.ipynb 14
+def plot_corr(x,#a column of df
+              y,#a column of df
+              xlabel=None,# x axis label
+              ylabel=None,# y axis label
+              order=3, # polynomial level, if straight, order=1 
+             ):
+    sns.regplot(x=x,
+            y=y,
+            order=order,
+            line_kws={'color': 'gray'}
+           )
+    
+    if xlabel is not None:
+        plt.xlabel(xlabel)
+        
+    if ylabel is not None:
+        plt.ylabel(ylabel)
+    # plt.text(x=0.8, y=0.1, s=f'Spearman: {correlation:.2f}', transform=plt.gca().transAxes, ha='center', va='center');

kdock/core/protein.py

@@ -0,0 +1,293 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/core/02_protein.ipynb.
+
+# %% auto 0
+__all__ = ['get_uniprot_seq', 'get_uniprot_features', 'get_uniprot_kd', 'get_uniprot_type', 'apply_mut_single',
+           'apply_mut_complex', 'compare_seq']
+
+# %% ../../nbs/core/02_protein.ipynb 3
+import pandas as pd
+import requests,re
+from functools import lru_cache
+
+# for compare seq
+from Bio.Align import PairwiseAligner
+
+# %% ../../nbs/core/02_protein.ipynb 5
+@lru_cache()
+def get_uniprot_seq(uniprot_id):
+    "Queries the UniProt database to retrieve the protein sequence for a given UniProt ID."
+    
+    url = f"https://www.uniprot.org/uniprot/{uniprot_id}.fasta"
+    response = requests.get(url)
+
+    # Check if the request was successful (status code 200)
+    if response.status_code == 200:
+        data = response.text
+        # The sequence starts after the first line, which is a description
+        sequence = ''.join(data.split('\n')[1:]).strip()
+        return sequence
+    else:
+        return f"Error: Unable to retrieve sequence for UniProt ID {uniprot_id}. Status code: {response.status_code}"
+
+# %% ../../nbs/core/02_protein.ipynb 7
+@lru_cache()
+def get_uniprot_features(uniprot_id):
+    "Given uniprot_id, get specific region for uniprot features."
+    # uniprot REST API
+    url = f"https://rest.uniprot.org/uniprotkb/{uniprot_id}.json"
+    response = requests.get(url)
+
+    if response.status_code == 200:
+        data = response.json()
+        # Extract the "features" section which contains information
+        features = data.get('features', [])
+        
+        protein_name = (
+            data.get("proteinDescription", {})
+                .get("recommendedName", {})
+                .get("fullName", {})
+                .get("value")
+        )
+
+        gene_name = (
+            data.get("genes", [{}])[0]
+                .get("geneName", {})
+                .get("value")
+        )
+        return {
+            "uniprot_id": uniprot_id,
+            "protein_name": protein_name,
+            "gene_name": gene_name,
+            "features": features
+        }
+    else:
+        raise ValueError(f"Failed to retrieve UniProt features for {uniprot_id}")
+
+# %% ../../nbs/core/02_protein.ipynb 9
+def get_uniprot_kd(uniprot_id):
+    "Query 'Domain: Protein kinase' based on UniProt ID and get its sequence info."
+    data = get_uniprot_features(uniprot_id)
+    seq = get_uniprot_seq(uniprot_id)
+    out = []
+
+    for feature in data['features']:
+        if feature.get("type") == "Domain" and "Protein kinase" in feature.get("description", ""):
+            start = feature['location']['start']['value']
+            end = feature['location']['end']['value']
+            out.append({
+                "uniprot_id": uniprot_id,
+                "protein_name": data["protein_name"],
+                "gene_name": data["gene_name"],
+                "start": start,
+                "end": end,
+                "description": feature.get("description", ""),
+                "sequence": seq[start-1:end]
+            })
+
+    return out
+
+# %% ../../nbs/core/02_protein.ipynb 11
+def get_uniprot_type(uniprot_id,type_='Signal'):
+    "Get region sequences based on UniProt ID features."
+    data = get_uniprot_features(uniprot_id)
+    seq = get_uniprot_seq(uniprot_id)
+
+    out = []
+
+    for feature in data['features']:
+        if feature.get("type") == type_:
+            start = feature['location']['start']['value']
+            end = feature['location']['end']['value']
+            region = {
+                'uniprot_id': uniprot_id,
+                'type': feature['type'],
+                "protein_name": data["protein_name"],
+                "gene_name": data["gene_name"],
+                'start': start,
+                'end': end,
+                'description': feature['description'],
+                'sequence': seq[start-1:end]
+            }
+            out.append(region)
+
+    if not out:
+        available = sorted({f.get("type") for f in data['features'] if f.get("type")})
+        print(f"No feature of type '{type_}' found for {uniprot_id}.")
+        print(f"Available feature types: {', '.join(available)}")
+        return available
+
+    return out
+
+# %% ../../nbs/core/02_protein.ipynb 16
+def apply_mut_single(seq, # protein sequence
+           *mutations, # e.g., E709A
+           start_pos=1, # if the protein sequence does not start from index 1, indicate the start index to match the mutations
+           ):
+    "Apply mutations to a protein sequence."
+    seq_list = list(seq)  # convert to list for mutability
+    
+    for mut in mutations:
+        # check mutation format
+        if len(mut) < 3: raise ValueError(f"Invalid mutation format: {mut}")
+        
+        from_aa,pos,to_aa = mut[0],int(mut[1:-1])-start_pos,mut[-1]
+
+        # make sure position is within the sequence length
+        if pos < 0 or pos >= len(seq_list): raise IndexError(f"Position {pos + 1} out of range for sequence length {len(seq_list)}")
+        # make sure aa from mutations matches the residue on the sequence
+        if seq_list[pos] != from_aa: raise ValueError(f"Expected {from_aa} at position {pos + 1}, found {seq_list[pos]}")
+        
+        seq_list[pos] = to_aa
+        print('Converted:', mut)
+        
+    return ''.join(seq_list)
+
+# %% ../../nbs/core/02_protein.ipynb 18
+def apply_mut_complex(seq, # protein sequence
+                      mut, # mutation (e.g., G776delinsVC/S783C, G778dupGSP)
+                      start_pos=1, # if truncated protein sequence, indicate where it starts to match the position of mutation
+                      ):
+    """
+    Apply a composite mutation like 'G776delinsVC/S783C' to `seq`,
+    assuming `seq[0]` corresponds to residue number `start_pos`.
+
+    * At most one delins **or** dup is allowed.
+    * Point substitutions are executed first; the indel/dup is done last.
+    """
+    _sub_pat    = re.compile(r'^([A-Z])(\d+)([A-Z])$')          # e.g. S783C
+    _delins_pat = re.compile(r'^([A-Z])(\d+)delins([A-Z]+)$')   # e.g. G776delinsVC
+    _dup_pat    = re.compile(r'^([A-Z])(\d+)dup([A-Z]+)$')      # e.g. G778dupGSP
+
+    seq = list(seq)
+    tokens = mut.split('/')
+
+    # ---------- 1) substitutions (length-neutral) ----------
+    for m in tokens:
+        if _sub_pat.match(m):
+            orig, pos, new = _sub_pat.match(m).groups()
+            idx = int(pos) - start_pos
+            if seq[idx] != orig:
+                raise ValueError(
+                    f"Mismatch at position {pos}: expected {orig}, got {seq[idx]}"
+                )
+            seq[idx] = new
+
+    # ---------- 2) the single length-changing event ----------
+    for m in tokens:
+        if _delins_pat.match(m):
+            orig, pos, ins = _delins_pat.match(m).groups()
+            idx = int(pos) - start_pos
+            if seq[idx] != orig:
+                raise ValueError(
+                    f"Mismatch at position {pos}: expected {orig}, got {seq[idx]}"
+                )
+            seq[idx : idx + 1] = list(ins)         # replace 1 residue with many
+            break
+
+        if _dup_pat.match(m):
+            orig, pos, dup = _dup_pat.match(m).groups()
+            idx = int(pos) - start_pos
+            if seq[idx] != orig:
+                raise ValueError(
+                    f"Mismatch at position {pos}: expected {orig}, got {seq[idx]}"
+                )
+            seq[idx + 1 : idx + 1] = list(dup)     # insert right after the residue
+            break
+
+    return ''.join(seq)
+
+# %% ../../nbs/core/02_protein.ipynb 22
+def compare_seq(
+    seq1: str,  # original
+    seq2: str,  # mutant
+    *,
+    start_pos: int = 1,
+    label1: str = "Original",
+    label2: str = "Mutant",
+    visualize: bool = True
+):
+    """
+    Align two protein sequences and summarise differences.
+    """
+
+    # ----- global alignment using PairwiseAligner -----
+    aligner = PairwiseAligner()
+    aligner.mode = "global"
+    aligner.match_score = 2
+    aligner.mismatch_score = -1
+    aligner.open_gap_score = -5
+    aligner.extend_gap_score = -0.5
+
+    alignment = aligner.align(seq1, seq2)[0]
+    aln1 = alignment.aligned[0]
+    aln2 = alignment.aligned[1]
+
+    # Reconstruct aligned strings from aligned segments
+    aligned_seq1 = []
+    aligned_seq2 = []
+    i1, i2 = 0, 0
+
+    for (start1, end1), (start2, end2) in zip(aln1, aln2):
+        # Add gaps to make sequences align
+        while i1 < start1:
+            aligned_seq1.append(seq1[i1])
+            aligned_seq2.append('-')
+            i1 += 1
+        while i2 < start2:
+            aligned_seq1.append('-')
+            aligned_seq2.append(seq2[i2])
+            i2 += 1
+
+        # Add aligned part
+        for j in range(end1 - start1):
+            aligned_seq1.append(seq1[i1])
+            aligned_seq2.append(seq2[i2])
+            i1 += 1
+            i2 += 1
+
+    # Remaining tails
+    while i1 < len(seq1):
+        aligned_seq1.append(seq1[i1])
+        aligned_seq2.append('-')
+        i1 += 1
+    while i2 < len(seq2):
+        aligned_seq1.append('-')
+        aligned_seq2.append(seq2[i2])
+        i2 += 1
+
+    aln1_str = ''.join(aligned_seq1)
+    aln2_str = ''.join(aligned_seq2)
+
+    # ----- find differences -----
+    diffs, raw_i1, raw_i2 = [], 0, 0
+    for a1, a2 in zip(aln1_str, aln2_str):
+        if a1 != '-' and a2 != '-':
+            if a1 != a2:
+                diffs.append((start_pos + raw_i1, a1, a2, 'substitution'))
+            raw_i1 += 1
+            raw_i2 += 1
+        elif a1 == '-' and a2 != '-':
+            diffs.append((start_pos + raw_i1, '-', a2, 'insertion'))
+            raw_i2 += 1
+        elif a1 != '-' and a2 == '-':
+            diffs.append((start_pos + raw_i1, a1, '-', 'deletion'))
+            raw_i1 += 1
+
+    # ----- visualization -----
+    if visualize:
+        for block in range(0, len(aln1_str), 80):
+            s1_block = aln1_str[block:block + 80]
+            s2_block = aln2_str[block:block + 80]
+            marker = ''.join(' ' if x == y else '^' for x, y in zip(s1_block, s2_block))
+            left_idx = start_pos + aln1_str[:block].replace('-', '').__len__()
+            right_idx = left_idx + s1_block.replace('-', '').__len__() - 1
+            print(f"{label1:<10} {left_idx:>5}-{right_idx:<5}: {s1_block}")
+            print(f"{label2:<10} {'':>11}: {s2_block}")
+            print(f"{'':>22}  {marker}\n")
+
+    # ----- summary list -----
+    print("Differences:")
+    for pos, ref, new, kind in diffs:
+        print(f"  {kind:<12} at {pos:>4}: {ref} → {new}")
+
+    # return diffs