Metadata-Version: 2.4
Name: chainmapper
Version: 1.0.1
Summary: Tool to map chains of two structures
Author-email: Pierre Berriet <pierre.berriet@univ-lille.fr>
Maintainer-email: Pierre Berriet <pierre.berriet@univ-lille.fr>
License-Expression: CECILL-2.1
Keywords: Chain Mapping
Requires-Python: ~=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython~=1.87
Requires-Dist: numpy~=2.5
Requires-Dist: scipy~=1.18
Requires-Dist: pandas~=3.0
Requires-Dist: scikit-learn~=1.9
Dynamic: license-file

# ChainMapper

## Install

```bash
pip install chainmapper
```

### Usage

### Run simple mapping on samples

```bash
chainmapper \
      -r samples/sample1.pdb \
      -q samples/sample2.pdb \
      -o results \
      --n_outputs 1 \
      --unique \
      --verbose      
```

## Modules

### Reduction Modules: Clustering-based or Heuristic:

|          Module Name          | Id |           Method           |                                                                                                                           Description                                                                                                                           |
| :----------------------------: | :-: | :-------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|      Sequence Clustering      | S |         Clustering         |                                                                                               Chain sequences are aligned and cluster according to identity score                                                                                               |
|  Minimal Distance Clustering  | M |         Clustering         |                                                                                                  Minimal distance vector of the chains are compared using RMSE                                                                                                  |
| Barycentre Distance Clustering | B |         Clustering         |                                                                                                Barycentre distance vector of the chains are compared using RMSE                                                                                                |
|    Conformation Clustering    | C |         Clustering         |                                                                                             Chain are clustered according to their conformation (chain-chain RMSD)                                                                                             |
|             Pivot             | P | Clustering with constraints | One chain of each model is used as pivot to guide minimal distance clustering. Multiple pivots are tested. This module should be used after other clustering modules. If it does not fall below the enumeration threshold, it has no impact on the clustering. |
|      Simulated Annealing      | A |          Heuristic          |                                                              Fall back module used to force finding a mapping using simulated annealing search. Need to be used at the end of the module sequence.                                                              |

### Scoring modules:

| Module Name                       | Id |                             Description                             |
| --------------------------------- | :-: | :------------------------------------------------------------------: |
| Root Mean Square Deviation (RMSD) | R |    RMSD computed on$C_\alpha$ of all residues after alignment.    |
| RMSD on chain PCA points          | r | Fast RMSD used in simulated annealing or to fliter out off mappings. |

## Input arguments, options and flags

| Name                            | Required |  Default  |                                          Description                                          |
| ------------------------------- | :------: | :-------: | :--------------------------------------------------------------------------------------------: |
| **Arguments**             |          |          |                                                                                                |
| -r, --ref_file_path             |   ✔️   |          |                           Path to reference PDB file (mmCIF allowed)                           |
| -q, --query_file_path           |   ✔️   |          |                             Path to query PDB file (mmCIF allowed)                             |
| -o, --out_path                  |   ✔️   |          |                                     Path of output folder.                                     |
| **Options**               |          |          |                                                                                                |
| -m, --modules                   |          |  SMBPAR  |                                  Modules to launch in order.                                  |
| --ignore_chains_ref             |          |    ""    |                          Chains to ignore in the reference structure.                          |
| --ignore_chains_query           |          |    ""    |                            Chains to ignore in the query structure.                            |
| -e --max_enum                   |          |   1000   |                            Maximum number of mappings to enumerate.                            |
| --n_siman                       |          |     1     |                              Number of simulated annealing runs.                              |
| --clustering_threshold          |          |     0     |                          Minimum threshold for clustering (escept S).                          |
| --sequence_clustering_threshold |          |    0.3    |                            Threshold used for sequence clustering.                            |
| --ref_name                      |          | file_name |                                Name of the reference structure.                                |
| --query_name                    |          | file_name |                                  Name of the query structure.                                  |
| --n_outputs                     |          |     1     |                           Maximum number of mapped files to return.                           |
| --n_print_score                 |          |     5     |                                Number of final scores to print.                                |
| **Option flags**          |          |          |                                                                                                |
| --fitted_output                 |          |          |                                Output the model aligned on ref.                                |
| --no_change_chain_ids           |          |          | Disable the replacement of chain ids in the output file by the respective ids in the ref file. |
| --no_change_chain_order         |          |          |        Disable the change of chain order in the output file according ot the ref file.        |
| --unique                        |          |          |                      Enable to have unique ids in the output file names.                      |
| --all                           |          |          |                        Enable to save all mappings scored in csv file.                        |
| --stats                         |          |          |              Enable to save stats like time and number of mappings in a csv file.              |
| --verbose                       |          |          |                                 Enable logs during processing.                                 |
