# Installation (Requires Python 3.9 and above)

Use the following command:

```
pip install nrgrank
```

To install nrgrank with rdkit for generating conformers:

```
pip install "nrgrank[rdkit]"
```


Using NRGRank in a python script:

```
from nrgrank import process_target, process_ligands, nrgrank_main
```

# Preparatory steps

## 1. Preprocessing the target

### Required Arguments
| Argument                 | Description                                     | Possible value(s) |
|--------------------------|-------------------------------------------------|-------------------|
| `target_mol2_path`       | Path to target mol2 file                        | Absolute path     |
| `binding_site_file_path` | Path to binding site file generated by GetCleft | Absolute path     |

### Optional Arguments
| Flag             | Description                                           | Possible value(s) |
|------------------|-------------------------------------------------------|-------------------|
| `create_new_dir` | A new folder will be created to store generated files | True,False        |
| `overwrite`      | Allows overwriting existing files                     | True,False        |

### Example command

```
target_save_dir = process_target(target_mol2_path='foo/bar/target.mol2', binding_site_file_path='foo/bar/bd_site_sph_1.pdb')
```

## 2. Preparing the ligands
   
All ligands for one screen must be in the same mol2 file
      
   ### Required Arguments
   
   For running on a single mol2 file:

   | Flag                      | Description                       | Possible value(s) |
   |---------------------------|-----------------------------------|-------------------|
   | `ligand_path`             | Path to ligand mol2 file          | Absolute path     |
   | `conformers_per_molecule` | Number of conformers per molecule | Int               |

   
   ### Optional Arguments

   | Flag           | Description                                                                          | Possible value(s) |
   |----------------|--------------------------------------------------------------------------------------|-------------------|
   | `overwrite`    | Allows overwriting existing files                                                    | True,False        |
   | `ligand_type`  | Assign a specific ligand type recognised by NRGRank. Can be useful for benchmarking. | (str)             |    
   | `output_dir`   | Folder where generated files will be stored                                          | Absolute path     |
   
   ### Example commands:

   ```
   ligand_save_dir = process_ligands(ligand_path='foo/bar/ligands.mol2', conformers_per_molecule=1)
   ```

---
# NRGRank

### Required Flags
    
| Flag                       | Description                                                                                           | Possible value(s) |
|----------------------------|-------------------------------------------------------------------------------------------------------|-------------------|
| `target_name`              | The name of the target. Used for naming the output CSV file when `csv_and_pose_name` is not specified | (str)             |
| `preprocessed_target_path` | Path to the preprocessed target folder (e.g., output from `process_target()`)                         | Absolute path     |
| `preprocessed_ligand_path` | Path to the preprocessed ligand folder (e.g., output from `process_ligand()`)                         | Absolute path     |
| `result_folder_path`       | Directory path where the docking results will be stored                                               | Absolute path     |

---

### Optional Flags
    
| Flag                       | Description                                                                   | Possible value(s)             |
|----------------------------|-------------------------------------------------------------------------------|-------------------------------|
| `result_csv_and_pose_name` | Custom name for CSV and pose files. If not given, defaults to `target_name`   | (str)                         |
| `ligand_type`              | Type of ligand being processed. Useful when benchmarking with DUD-E           | "ligand", "active", "decoy"   |
| `ligand_slice`             | Slice range of ligands to process                                             | list[int] or None             |
| `write_info`               | Write informational remarks to output (e.g., .txt log)                        | True, False                   |
| `write_file`               | Output result file(s)                                                         | True, False                   |
| `output_dictionary`        | Output results as a Python dictionary                                         | True, False                   |
| `file_separator`           | Separator character for the result file (CSV/TSV)                             | ",", "\t"                     |
| `output_header`            | Write a header row in the CSV file                                            | True, False                   |
| `save_time`                | Save time taken per molecule for docking                                      | True, False                   |
| `normalise_score`          | Normalise docking score by number of atoms in molecule                        | True, False                   |
| `unique_run_id`            | Unique identifier to avoid file name conflicts and used to name ligand poses  | (str)                         |
| `user_config`              | Arbitrary keyword arguments for overriding default docking parameters         | key=value pairs               |

### Example commands:

   ```
   result_file_path, result_csv_lines = nrgrank_main(target_name='target', 
                      preprocessed_target_path='foo/bar/preprocessed_target', 
                      preprocessed_ligand_path='foo/bar/preprocessed_ligands_1_conf',
                      result_folder_path='foo/bar/results')
   ```

Returns the path to the result file and the lines contained in the result csv