structuredca 1.0.0__tar.gz

structuredca-1.0.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c), 2026, Matsvei Tsishyn
+Copyright (c), 2026, Hugo Talibart
+Copyright (c), 2026, Marianne Rooman
+Copyright (c), 2026, Fabrizio Pucci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

structuredca-1.0.0/MANIFEST.in

@@ -0,0 +1,20 @@
+# Include files required for building C++ extension
+include structuredca/dca_model/dca_solvers/plmdca/include/*
+include structuredca/dca_model/dca_solvers/plmdca/lbfgs/include/*
+recursive-include structuredca/dca_model/dca_solvers/plmdca *.cpp
+
+# Exclude files and directories that should not be in the package
+exclude Logo.png
+exclude conda-env.yml
+exclude test_data/*
+exclude tutorials/*
+global-exclude *.py[cod]
+global-exclude __pycache__/*
+global-exclude 0_*
+global-exclude *.so
+global-exclude *.a
+global-exclude *.o
+
+# Exclude build artifacts
+global-exclude structuredca/dca_model/dca_solvers/plmdca/build/*
+global-exclude *.egg-info/*

structuredca-1.0.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: structuredca
+Version: 1.0.0
+Summary: Structure-Informed Direct Couplings Analysis.
+Author-email: Matsvei Tsishyn <matsvei.tsishyn@protonmail.com>, Hugo Talibart <hugo.talibart@protonmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/3BioCompBio/StructureDCA
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: C
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: biopython>=1.75
+Requires-Dist: littlecsv
+Dynamic: license-file
+
+
+# StructureDCA
+
+[![PyPi Version](https://img.shields.io/pypi/v/structuredca.svg)](https://pypi.org/project/structuredca/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](
+https://colab.research.google.com/github/3BioCompBio/StructureDCA/blob/main/colab_notebook_StructureDCA.ipynb)
+<div style="text-align: center;">
+<img src="Logo.png" alt="[StructureDCA Logo]" height="400"/>
+</div>
+
+The `structuredca` Python package implements **Structure-Informed Direct Coupling Analysis** (StructureDCA) to predict the **effects of missense mutations on proteins**.
+
+Standard DCA methods use **Multiple Sequence Alignments (MSAs)** to build a **statistical evolutionary model** of homologous protein families. They rely on single-site fields `h` and pairwise couplings `J` that capture co-evolution between residue positions.
+StructureDCA extends this framework by incorporating the **residue–residue contact map** derived from the protein **3D structure** to infer a **sparse DCA model**, in which couplings between spatially distant residue pairs are removed.
+This approach leverages the observation that functionally relevant, co-evolving residues are most often structurally in contact.
+
+The package includes a **pseudolikelihood-maximization DCA solver** capable of inferring sparse DCA models, where selected coupling coefficients `Jij` are constrained to zero.
+StructureDCA combines a flexible, user-friendly Python interface with the high computational efficiency of its C++ backend.
+This model was initially developed to improve classical DCA methods for predicting the effects of missense mutations in proteins. However, StructureDCA can be applied to any DCA-based analysis (except for contact predictions...) and provides the full functionality of both standard and sparse DCA models.
+
+**Please cite**:
+- [Matsvei Tsishyn, Hugo Talibart, Marianne Rooman, Fabrizio Pucci. Inferring Protein Mutational Landscape with Structure-Informed Direct Coupling Analysis. BioRxiv](https://www.biorxiv.org/).
+
+
+## Installation and Usage
+
+### Colab Notebook
+
+You can instantly try StructureDCA in this [Colab Notebook](https://colab.research.google.com/github/3BioCompBio/StructureDCA/blob/main/colab_notebook_StructureDCA.ipynb). This notebook acts as a **user-friendly web server** / **graphical interface**, offering helpers to **automatically fetch or generate the MSA and 3D structure** for your target protein.
+You can then **visualize** your mutational landscape predictions as a DMS heatmap or mapped to the 3D structure.
+
+### Installation
+Installation with `pip`:
+```bash
+pip install structuredca
+```
+
+### CLI usage
+Use StructureDCA with a Command Line Interface (CLI).
+For example, from the directory `./test_data/`, run:
+```bash
+structuredca ./6acv_A_29-94.fasta ./6acv_A_29-94.pdb A -o ./6acv_A_29-94_structuredca.csv
+```
+
+To show CLI usage and optional arguments, run:
+```bash
+structuredca --help
+```
+
+### Python usage
+Make sure the first sequence in your MSA file is the target sequence to mutate (otherwise have a look at tutorial 1).  
+From directory `./test_data/` execute the following Python code:
+```python
+# Import
+from structuredca import StructureDCA
+
+# Log basic usage and arguments
+StructureDCA.help()
+
+# Initialize StructureDCA model
+sdca = StructureDCA(
+    msa_path='./6acv_A_29-94.fasta',
+    pdb_path='./6acv_A_29-94.pdb', chains='A',
+    use_contacts_plddt_filter=False, # use only if 3D structure is an AlphaFold model (or similar) to remove low pLDDT regions from contacts
+)
+
+# Evaluate the evolutionary energy difference (ΔE) of mutations
+# scores can be reweighted by Relative Solvent Accessibility-complement (RSAc) -> advised to predict stability changes (ΔΔG)
+# * dE = 0 means neutral mutation
+# * dE >> 0 means destabilizing / deleterious mutation
+dE_mut1 = sdca.eval_mutation('K13H', reweight_by_rsa=True)
+dE_mut2 = sdca.eval_mutation('K13H:K12G', reweight_by_rsa=True)
+
+# Evaluate ΔE of all single mutations and save results to a file
+dE_all = sdca.eval_mutations_table(
+    save_path='./6acv_A_29-94_structuredca.csv',
+    log_output_sample=True,
+)
+
+# Evaluate absolute evolutionary energy (E) of a sequence
+seq_to_evaluate = 'A' * sdca.msa_length # arbitrary example: AAAAA...
+E_only_alanine = sdca.eval_sequence(seq_to_evaluate, reweight_by_rsa=True)
+
+# Evaluate relative probabilities for the 20 Amino Acids at this position given a background sequence 
+fasta_position = 10 # as in FASTA index system (starts at 1)
+array_position = fasta_position - 1 # As in a Python array (starts at 0)
+amino_acid_probabilities = sdca.position_probabilities(array_position) # P(a) = e^{-dE(wt→a)} / ∑_b e^{-dE(wt→b)}
+```
+
+### Tutorials and Advanced Usage
+In the `./tutorials/` directory, we provide a series of Jupyter notebooks that illustrate different ways to using **StructureDCA**:
+
+1. **Basics and arguments** (`1_sdca-basics.ipynb`): basics, evaluating effects of mutations with StructureDCA, using optional arguments (like `distance_cutoff` or `lambda_h` / `lambda_J`), evaluate mutations with an alternative background sequence.
+
+2. **Access properties** (`2_sdca-properties.ipynb`): access StructureDCA coefficients and properties (like fields `h`, couplings `J`, Frobenius norms, residue-residue distance matrix, contact map, ...).
+
+3. **Standard DCA** (`3_sdca-standard-dca.ipynb`): solve standard (fully connected) DCA models and run without protein 3D structure. 
+
+4. **Protein–Protein Interactions** (`4_sdca-ppis.ipynb`): working with protein–protein interactions (PPIs).  
+Compute RSA from the biologically relevant conformation, include inter-chain contacts arising from homomers, and build a StructureDCA model from a concatenated MSA of a heteromer PPI of highly coevoling proteins.
+
+5. **Custom contacts** (`5_sdca-custom-contacts.ipynb`): build a StructureDCA model with custom contact map (instead of the default distance criteria) and custom weights for StructureDCA[RSA] (instead of default RSA-based weights) to derive any possible sparse DCA model.
+
+## Build and Installation Notes
+
+### Requirements
+- Python 3.9 or later
+- Python packages `numpy` and `biopython` (version 1.75 or later)
+- A C++ compiler that supports C++17 and OpenMP (such as GCC, LLVM or MSVC).
+
+### Troubleshooting macOS build errors
+StructureDCA uses OpenMP for parallel computation in C++.
+Since macOS `Clang` compiler does not include OpenMP support by default, macOS users may need to install and configure the `LLVM` compiler to build the package.
+
+If you are using macOS and encounter compilation errors related to `-fopenmp`, please follow these steps:
+
+- Install `Homebrew`
+- Install `LLVM` and `OpenMP` runtime and configure Python to use this compiler. Then try to re-install StructureDCA. Run something like (paths may slightly differ):
+```bash
+brew install llvm libomp
+export CC=/usr/local/opt/llvm/bin/clang
+export CXX=/usr/local/opt/llvm/bin/clang++
+export CPPFLAGS="-I/usr/local/opt/libomp/include"
+export LDFLAGS="-L/usr/local/opt/libomp/lib -lomp"
+pip install structuredca
+```
+
+Well, I am not exactly sure about this fix, but I know it is possible.
+
+## Credits
+- For inferring the DCA coefficients, StructureDCA uses a gradient descent solver: [L-BFGS](https://github.com/chokkan/liblbfgs "libLBFGS") by Naoaki Okazaki (which is included in this repo).
+- The part of the code that makes the bridge between Python and C++ is inspired from the [plmDCA implementation 'pycofitness'](https://github.com/KIT-MBS/pycofitness/) by Mehari B. Zerihun, Fabrizio Pucci.

structuredca-1.0.0/README.md

@@ -0,0 +1,131 @@
+
+# StructureDCA
+
+[![PyPi Version](https://img.shields.io/pypi/v/structuredca.svg)](https://pypi.org/project/structuredca/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](
+https://colab.research.google.com/github/3BioCompBio/StructureDCA/blob/main/colab_notebook_StructureDCA.ipynb)
+<div style="text-align: center;">
+<img src="Logo.png" alt="[StructureDCA Logo]" height="400"/>
+</div>
+
+The `structuredca` Python package implements **Structure-Informed Direct Coupling Analysis** (StructureDCA) to predict the **effects of missense mutations on proteins**.
+
+Standard DCA methods use **Multiple Sequence Alignments (MSAs)** to build a **statistical evolutionary model** of homologous protein families. They rely on single-site fields `h` and pairwise couplings `J` that capture co-evolution between residue positions.
+StructureDCA extends this framework by incorporating the **residue–residue contact map** derived from the protein **3D structure** to infer a **sparse DCA model**, in which couplings between spatially distant residue pairs are removed.
+This approach leverages the observation that functionally relevant, co-evolving residues are most often structurally in contact.
+
+The package includes a **pseudolikelihood-maximization DCA solver** capable of inferring sparse DCA models, where selected coupling coefficients `Jij` are constrained to zero.
+StructureDCA combines a flexible, user-friendly Python interface with the high computational efficiency of its C++ backend.
+This model was initially developed to improve classical DCA methods for predicting the effects of missense mutations in proteins. However, StructureDCA can be applied to any DCA-based analysis (except for contact predictions...) and provides the full functionality of both standard and sparse DCA models.
+
+**Please cite**:
+- [Matsvei Tsishyn, Hugo Talibart, Marianne Rooman, Fabrizio Pucci. Inferring Protein Mutational Landscape with Structure-Informed Direct Coupling Analysis. BioRxiv](https://www.biorxiv.org/).
+
+
+## Installation and Usage
+
+### Colab Notebook
+
+You can instantly try StructureDCA in this [Colab Notebook](https://colab.research.google.com/github/3BioCompBio/StructureDCA/blob/main/colab_notebook_StructureDCA.ipynb). This notebook acts as a **user-friendly web server** / **graphical interface**, offering helpers to **automatically fetch or generate the MSA and 3D structure** for your target protein.
+You can then **visualize** your mutational landscape predictions as a DMS heatmap or mapped to the 3D structure.
+
+### Installation
+Installation with `pip`:
+```bash
+pip install structuredca
+```
+
+### CLI usage
+Use StructureDCA with a Command Line Interface (CLI).
+For example, from the directory `./test_data/`, run:
+```bash
+structuredca ./6acv_A_29-94.fasta ./6acv_A_29-94.pdb A -o ./6acv_A_29-94_structuredca.csv
+```
+
+To show CLI usage and optional arguments, run:
+```bash
+structuredca --help
+```
+
+### Python usage
+Make sure the first sequence in your MSA file is the target sequence to mutate (otherwise have a look at tutorial 1).  
+From directory `./test_data/` execute the following Python code:
+```python
+# Import
+from structuredca import StructureDCA
+
+# Log basic usage and arguments
+StructureDCA.help()
+
+# Initialize StructureDCA model
+sdca = StructureDCA(
+    msa_path='./6acv_A_29-94.fasta',
+    pdb_path='./6acv_A_29-94.pdb', chains='A',
+    use_contacts_plddt_filter=False, # use only if 3D structure is an AlphaFold model (or similar) to remove low pLDDT regions from contacts
+)
+
+# Evaluate the evolutionary energy difference (ΔE) of mutations
+# scores can be reweighted by Relative Solvent Accessibility-complement (RSAc) -> advised to predict stability changes (ΔΔG)
+# * dE = 0 means neutral mutation
+# * dE >> 0 means destabilizing / deleterious mutation
+dE_mut1 = sdca.eval_mutation('K13H', reweight_by_rsa=True)
+dE_mut2 = sdca.eval_mutation('K13H:K12G', reweight_by_rsa=True)
+
+# Evaluate ΔE of all single mutations and save results to a file
+dE_all = sdca.eval_mutations_table(
+    save_path='./6acv_A_29-94_structuredca.csv',
+    log_output_sample=True,
+)
+
+# Evaluate absolute evolutionary energy (E) of a sequence
+seq_to_evaluate = 'A' * sdca.msa_length # arbitrary example: AAAAA...
+E_only_alanine = sdca.eval_sequence(seq_to_evaluate, reweight_by_rsa=True)
+
+# Evaluate relative probabilities for the 20 Amino Acids at this position given a background sequence 
+fasta_position = 10 # as in FASTA index system (starts at 1)
+array_position = fasta_position - 1 # As in a Python array (starts at 0)
+amino_acid_probabilities = sdca.position_probabilities(array_position) # P(a) = e^{-dE(wt→a)} / ∑_b e^{-dE(wt→b)}
+```
+
+### Tutorials and Advanced Usage
+In the `./tutorials/` directory, we provide a series of Jupyter notebooks that illustrate different ways to using **StructureDCA**:
+
+1. **Basics and arguments** (`1_sdca-basics.ipynb`): basics, evaluating effects of mutations with StructureDCA, using optional arguments (like `distance_cutoff` or `lambda_h` / `lambda_J`), evaluate mutations with an alternative background sequence.
+
+2. **Access properties** (`2_sdca-properties.ipynb`): access StructureDCA coefficients and properties (like fields `h`, couplings `J`, Frobenius norms, residue-residue distance matrix, contact map, ...).
+
+3. **Standard DCA** (`3_sdca-standard-dca.ipynb`): solve standard (fully connected) DCA models and run without protein 3D structure. 
+
+4. **Protein–Protein Interactions** (`4_sdca-ppis.ipynb`): working with protein–protein interactions (PPIs).  
+Compute RSA from the biologically relevant conformation, include inter-chain contacts arising from homomers, and build a StructureDCA model from a concatenated MSA of a heteromer PPI of highly coevoling proteins.
+
+5. **Custom contacts** (`5_sdca-custom-contacts.ipynb`): build a StructureDCA model with custom contact map (instead of the default distance criteria) and custom weights for StructureDCA[RSA] (instead of default RSA-based weights) to derive any possible sparse DCA model.
+
+## Build and Installation Notes
+
+### Requirements
+- Python 3.9 or later
+- Python packages `numpy` and `biopython` (version 1.75 or later)
+- A C++ compiler that supports C++17 and OpenMP (such as GCC, LLVM or MSVC).
+
+### Troubleshooting macOS build errors
+StructureDCA uses OpenMP for parallel computation in C++.
+Since macOS `Clang` compiler does not include OpenMP support by default, macOS users may need to install and configure the `LLVM` compiler to build the package.
+
+If you are using macOS and encounter compilation errors related to `-fopenmp`, please follow these steps:
+
+- Install `Homebrew`
+- Install `LLVM` and `OpenMP` runtime and configure Python to use this compiler. Then try to re-install StructureDCA. Run something like (paths may slightly differ):
+```bash
+brew install llvm libomp
+export CC=/usr/local/opt/llvm/bin/clang
+export CXX=/usr/local/opt/llvm/bin/clang++
+export CPPFLAGS="-I/usr/local/opt/libomp/include"
+export LDFLAGS="-L/usr/local/opt/libomp/lib -lomp"
+pip install structuredca
+```
+
+Well, I am not exactly sure about this fix, but I know it is possible.
+
+## Credits
+- For inferring the DCA coefficients, StructureDCA uses a gradient descent solver: [L-BFGS](https://github.com/chokkan/liblbfgs "libLBFGS") by Naoaki Okazaki (which is included in this repo).
+- The part of the code that makes the bridge between Python and C++ is inspired from the [plmDCA implementation 'pycofitness'](https://github.com/KIT-MBS/pycofitness/) by Mehari B. Zerihun, Fabrizio Pucci.

structuredca-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+
+# Pip Build Setup --------------------------------------------------------------
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+# Pip Package Metadata ---------------------------------------------------------
+[project]
+name = "structuredca"
+version = "1.0.0"
+description = "Structure-Informed Direct Couplings Analysis."
+readme = "README.md"
+authors = [
+  { name = "Matsvei Tsishyn", email = "matsvei.tsishyn@protonmail.com" },
+  { name = "Hugo Talibart",   email = "hugo.talibart@protonmail.com"   }
+]
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = [
+  "numpy",
+  "biopython>=1.75",
+  "littlecsv",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: C++",
+  "Programming Language :: C",
+  "Operating System :: OS Independent",
+  "Topic :: Scientific/Engineering :: Bio-Informatics"
+]
+urls = { Homepage = "https://github.com/3BioCompBio/StructureDCA" }
+
+# Entry Points for CLI ---------------------------------------------------------
+[project.scripts]
+structuredca = "structuredca.cli:main"
+
+# Setup pip Package ------------------------------------------------------------
+# this finds all the python packages recursively
+[tool.setuptools]
+packages = { find = {} }

structuredca-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

structuredca-1.0.0/setup.py

@@ -0,0 +1,45 @@
+
+"""
+NOTE about the 'setup.py' deprecation.
+Despite the fact that 'setup.py' is now deprecated and replaced by 'pyproject.toml', it is still required to include C++ modules in pip packages.
+Here is a minimal 'setup.py' that includes the C++ code in the package to complement the 'pyproject.toml' (this is fucked up)
+"""
+
+# Imports ----------------------------------------------------------------------
+import os
+from setuptools import setup, Extension
+
+# Extensions -------------------------------------------------------------------
+
+# Detect compiler platform to manage OpenMP compilation
+compile_args = ['-std=c++17', '-O3']
+link_args = ['-O3']
+if os.name == 'nt':
+    # Windows (MSVC)
+    compile_args.append('/openmp')
+else:
+    # Linux/macOS (GCC/Clang)
+    compile_args.append('-fopenmp')
+    link_args.append('-fopenmp')
+
+# Define extension (C++ code that need to be compiled)
+plmdca_ext = Extension(
+    name='structuredca.dca_model.dca_solvers.plmdca.lib_plmdcaBackend',
+    sources=[ # .cpp files
+        'structuredca/dca_model/dca_solvers/plmdca/plmdcaBackend.cpp',
+        'structuredca/dca_model/dca_solvers/plmdca/plmdca.cpp',
+        'structuredca/dca_model/dca_solvers/plmdca/lbfgs/lib/lbfgs.cpp',
+    ],
+    include_dirs=[ # .h directories
+        'structuredca/dca_model/dca_solvers/plmdca/include/',
+        'structuredca/dca_model/dca_solvers/plmdca/lbfgs/include/',
+    ],
+    language='c++',
+    extra_compile_args=compile_args,  # optimization and other flags
+    extra_link_args=link_args,
+)
+
+# Setup ------------------------------------------------------------------------
+setup(
+    ext_modules = [plmdca_ext],
+)

structuredca-1.0.0/structuredca/__init__.py

@@ -0,0 +1,20 @@
+"""
+StructureDCA
+============
+
+**Structure-Informed Direct Coupling Analysis** to predict
+the **effects of missense mutations on proteins**.
+It incorporates the residues contact map derived from protein
+3D structures to infer an **evolutionary sparse DCA model**.
+This approach leverages the observation that functionally relevant,
+co-evolving residues are most often in structural contact.
+
+Example of usage in Python:
+
+>>> from structuredca import StructureDCA
+>>> sdca = StructureDCA('./msa1.fasta', './pdb1.pdb', 'A')
+>>> mutation_score = sdca.eval_mutation('K24M:H39G', reweight_by_rsa=False)
+>>> all_muts_scores_table = sdca.eval_mutations_table()
+"""
+
+from structuredca.structuredca import StructureDCA

structuredca-1.0.0/structuredca/aligner/__init__.py

@@ -0,0 +1,2 @@
+from structuredca.aligner.linear_extrapolation import LinearExtrapolation
+from structuredca.aligner.structure_sequence_alignment import StructureSequenceAlignment

structuredca-1.0.0/structuredca/aligner/linear_extrapolation.py

@@ -0,0 +1,87 @@
+
+# Imports ----------------------------------------------------------------------
+from typing import List
+import numpy as np
+from numpy.typing import NDArray
+
+# Main -------------------------------------------------------------------------
+class LinearExtrapolation:
+    """
+    Class to extrapolate distance matrices distance_increment between two consecutive nodes.
+
+    args:
+        distance_increment:     float    increment distance between two nodes: d[i, i+2] - d[i, i+1]
+        distance_adj: float    distance_increment for two neighbour nodes: d[i, i+1]
+
+    usage:
+        lin_ext = LinearExtrapolation(distance_increment=3.2, distance_adj=0.135)
+
+        squared_dist_matrix = lin_ext.extrapolate_diagonal_matrix(10) # shape = (10, 10)
+
+        prolongation_dist_matrix = lin_ext.extrapolate_marginal_matrix([5.1, 5.3, 5.0], 10) # shape = (10, 3)
+    """
+
+    # Constructor --------------------------------------------------------------
+    def __init__(
+            self,
+            distance_increment: float,
+            distance_adj: float,
+            name: str="linear_extrapolator"
+        ):
+
+        # Guardians
+        assert distance_increment > 0.0, f"ERROR in LinearExtrapolation(): distance_increment={distance_increment} should be stricktly positive."
+        assert distance_adj > 0.0, f"ERROR in LinearExtrapolation(): distance_adj={distance_adj} should be stricktly positive."
+
+        # Init properties
+        self.name = name
+        self.distance_increment = np.float32(distance_increment)
+        self.distance_adj = np.float32(distance_adj)
+
+    # Base methods -------------------------------------------------------------
+    def __str__(self) -> str:
+        return f"LinearExtrapolation('{self.name}', d_inc={self.distance_increment:.2f}, d_nxt={self.distance_adj:.2f})"
+    
+    # Extrapoation -------------------------------------------------------------    
+    def extrapolate_diagonal_matrix(self, n: int) -> NDArray[np.float32]:
+        """
+        Return extrapolated diagonal distance matrix (shape=(n, n)).
+        """
+        assert n > 0, f"ERROR in {self}.extrapolate_diagonal_matrix(): n='{n}' should be stricktly positive."
+        extrapolation_array = [self.distance_adj + i*self.distance_increment for i in range(n)]
+        matrix = np.zeros((n, n), dtype=np.float32)
+        for i1 in range(n):
+            for i2 in range(i1):
+                delta_i = i1 - i2
+                d = extrapolation_array[delta_i - 1]
+                matrix[i1, i2] = d
+                matrix[i2, i1] = d
+        return matrix
+    
+    def extrapolate_marginal_matrix(self, distance_array: List[float], n: int, reverse_lines: bool=False) -> NDArray[np.float32]:
+        """
+        Return extrapolated marginal distance matrix by extrapolating n steps from a distance_array (shape=(n, len(distance_array))).
+        """
+
+        # Guardians
+        assert n > 0, f"ERROR in {self}.extrapolate_marginal_matrix(): n='{n}' should be stricktly positive."
+        
+        # Init
+        ZERO = np.float32(0.0)
+        distance_array = np.array(distance_array, dtype=np.float32)
+        
+        # First increment (might use distance_adj or distance_increment)
+        first_increment_arr = np.array([self.distance_adj if d == ZERO else self.distance_increment for d in distance_array], dtype=np.float32)
+        matrix = [distance_array + first_increment_arr]
+        
+        # Following increments (use distance_increment)
+        for i in range(n-1):
+            increment = np.float32((i+2)*self.distance_increment)
+            matrix.append(distance_array + increment)
+
+        # Reverse if required
+        if reverse_lines:
+            matrix = matrix[::-1]
+
+        # Format and return
+        return np.array(matrix, dtype=np.float32)