Skip to content

Commit

Permalink
Merge pull request #22 from tinavisnovska/expand_readme
Browse files Browse the repository at this point in the history 
Expansion, re-wording and re-formatting of README.md
  • Loading branch information
@xiaoliz0
xiaoliz0 authored Jan 23, 2024
2 parents b169415 + 4c2a041 commit 11fee79
Showing 1 changed file with 221 additions and 86 deletions.
307 changes: 221 additions & 86 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,89 +1,224 @@
# PRONTO
rePort geneRator fOr iNpred Tumor bOards
This is a tool used to filter and analysis data from TSO500 results and generate the report based on the results data and template file.
This repository contains the configure, scripts, report template, file infrastructure and docker files to run this tool locally or in Docker/Singularity.
# PRONTO
**(rePort geneRator fOr iNpred Tumor bOards)**

<br />

PRONTO is a tool used to filter and analyse data from TSO500 analysis (in the form of [TSOPPI](https://tsoppi.readthedocs.io/en/latest/) results). It generates powerpoint patient reports using predefined powerpoint template file. This repository contains the config file, metadata files, executable script, report template, testing data, and docker files to run this tool locally or in Docker/Singularity. The repository is accompanied with a docker image that is automatically pushed to [dockerhub](https://hub.docker.com/r/inpred/pronto) on each version release.

<br />

## Table of contents

1. [Requirments for running PRONTO locally](#requirments-for-running-pronto-locally)
2. [Repository contents](#repository-contents)
3. [Run PRONTO locally](#run-pronto-locally)
4. [Example commands](#example-commands)
5. [PRONTO Docker](#pronto-docker)
6. [PRONTO Singularity](#pronto-singularity)
7. [ChangeLog](#changelog)


<br />

## Requirments for running PRONTO locally

# Requirments (for running PRONTO locally, see below for Docker/Singularity)
1. This tool needs to be run with python above version 3.
2. Module xlutils and pptx need to be installed for python:
To install module xlutils, run the command: [sudo pip3 install xlutils]
To install module python-pptx, run the command: [sudo pip3 install python-pptx]
2. Module xlutils and pptx need to be installed for python:
- To install module xlutils, run the command:
```
sudo pip3 install xlutils
```
- To install module python-pptx, run the command:

```
sudo pip3 install python-pptx
```
3. Module xlrd and xlwt are needed for MTF importing function:
Download the files from Internet. Please google search it and choose the correct version for your environment.
Under the downloaded folder and install the module with command: [sudo python setup.py install]

# File infrastructure
INPUT:
Script/PRONTO.py --- The python script.
Config/configure_PRONTO.ini --- The configure file. Local changes need to set up.
In/Templates/MTB_template.pptx --- The template file used for generating PP report.
In/InPreD_PRONTO_metadata.txt --- The clinical data file. Reports will be generated for the Sample_id with "Create_report==Y" in this file.
In/MTF/IPD-XXXX_Material Transit Form InPreD NGS.xlsx --- The material file contains all patient personal information. (Used by OUS) This file will generate the inpred-samle-id following the nomenclature file.

OUTPUT:
Out/$runID/IPDXXX --- The folder contains all results for this sample.
Out/$runID/IPDXXX/extra_files --- The folder contains filter tables during the calculation process, and the patient material file from lab.
Out/$runID/IPDXXX/IPDXXX_MTB_report.pptx --- The PP report file.
Out/$runID/IPDXXX/IPDXXX_Remisse_draft.docx --- The remise draft file for email. (Used by OUS)
Out/InPreD_PRONTO_metadata_tsoppi.txt --- The file contains clinical data and the SOPPI results for all sample reports.

TESTING:
Testing_data/191206_NB501498_0174_AHWCNMBGXC_TSO_500_LocalApp_postprocessing_results.zip --- The testing data from AcroMetrix sample TSOPPI results which only contains the files PRONTO needs. Move this folder into your local TSOPPI result path for testing.
Testing_data/InPreD_PRONTO_metadata.txt --- The file contains clinical data of AcroMetrix samples for testing. Move this file into In/ for testing.
Testing_data/191206_NB501498_0174_AHWCNMBGXC.zip --- The testing results from AcroMetrix sample TSOPPI results for your local comparisons.

# Process of local running
1. LOCAL CONFIGURE:
In Config/configure_PRONTO.ini, please specify your InPreD node with "inpred_node = ". This will appear in the header of the reports.
In Config/configure_PRONTO.ini, please specify the local dataset file path of TSOPPI results with "data_path =".
2. Type clinical data into In/InPreD_PRONTO_metadata.txt
Manually write the clinical data into file In/InPreD_PRONTO_metadata.txt. Reports will be generated for the Sample_id with "Create_report==Y" in this file.
3. Run Script/PRONTO.py
Please run the script with "-h" or "--help" to print the usage information.
This script is a tool used to generate the paitent report based on the TSO500 analysis results and the personal intomation from the clinical data in In/InPreD_PRONTO_metadata.txt, and update the SOPPI results into the file Out/InPreD_PRONTO_metadata_tsoppi.txt when the reports are generated.
This script could also fill the patient personal information into the clinical data file with the MTF files under the foder In/MTF/. (This fuction currently is only used by OUS)
To run this script tool in your system with python3, it will read the clinical data from In/InPreD_PRONTO_metadata.txt and generate reports for the Sample_id with "Create_report==Y".

# Example commands
[python3 Script/InPreD_PRONTO.py -h]
Print the usage information of this tool.

[python3 Script/InPreD_PRONTO.py]
Please remember to update the "Create_report" to "N" in file In/InPreD_PRONTO_metadata.txt manually after the report generation is finished!

Special commands used by OUS:
-c, --clinical_file: Fill the patient personal information into file InPreD_PRONTO_metadata.txt with the MTF files under the foder In/MTF/.
[python3 Script/InPreD_PRONTO.py -r <TSO500_runID> -D <DNA_sampleID> -c]
-m, --mail_draft: Generate the Remisse_draft.docx file with report.
[python3 Script/InPreD_PRONTO.py -m]

# PRONTO Docker
PRONTO docker image is automatically pushed to dockerhub: https://hub.docker.com/r/inpred/pronto
Please download the image with the latest tag: [docker pull inpred/pronto:latest]

Run PRONTO with docker image:
[sudo docker run --rm -it -v $tsoppi_data:/pronto/tsoppi_data -v $InPreD_PRONTO_metadata_file:/pronto/In/InPreD_PRONTO_metadata.txt -v $pronto_output_dir:/pronto/Out inpred/pronto:latest python /pronto/Script/PRONTO.py]

"$tsoppi_data" is the path of your local TSOPPI results, which contains all runs of TSOPPI data (not the folder for individual runs).
"$InPreD_PRONTO_metadata_file" is your local InPreD meta data file which contains clinical data for the samples.
"$pronto_output_dir" is the path in your local environment to store the reports generated by PRONTO.

NB:
Running PRONTO with docker, you only need to modify the "inpred_node = " in Config/configure_PRONTO.ini file.
Please keep the "data_path =/pronto/tsoppi_data/" in Config/configure_PRONTO.ini.

# PRONTO Singularity
Download PRONTO docker image in the dockerhub with the latest tag: [docker pull inpred/pronto:latest]
Save the PRONTO docker image to a tar file: [docker save -o PRONTO_docker_image.tar inpred/pronto:latest]
Generate PRONTO Singularity image by conversion from the docker image file. Example command:
[singularity build --disable-cache --tmpdir $SINGULARITY_TMP $dir/PRONTO_singularity_image.sif docker-archive://$dir/PRONTO_docker_image.tar]

Run PRONTO image with Singularity:
[singularity exec --no-home -B $tsoppi_data:/pronto/tsoppi_data -B $InPreD_PRONTO_metadata_file:/pronto/In/InPreD_PRONTO_metadata.txt -B $pronto_output_dir:/pronto/Out -W $SINGULARITY_TMP $dir/PRONTO_singularity_image.sif python /pronto/Script/PRONTO.py]

"$tsoppi_data" is the path of your local TSOPPI results, which contains all runs of TSOPPI data (not the folder for individual runs).
"$InPreD_PRONTO_metadata_file" is your local InPreD meta data file which contains clinical data for the samples.
"$pronto_output_dir" is the path in your local environment to store the reports generated by PRONTO.py.

NB:
Running PRONTO with singularity, you only need to modify the "inpred_node = " in Config/configure_PRONTO.ini file. Please keep the "data_path =/pronto/tsoppi_data/" in Config/configure_PRONTO.ini.
- Download the files from Internet. Please google search it and choose the correct version for your environment.
- Under the downloaded folder and install the module with command:

```
sudo python setup.py install
```

<br />

## Repository contents

| INPUT file name: | Details: |
|:---|:---|
| `Script/PRONTO.py` | The executable python script.|
| `Config/configure_PRONTO.ini` | The configure file. Needs to be modified prior to its first use.|
| `In/Templates/MTB_template.pptx` | The template file used for generating PP report. (TODO: explain PP) |
| `In/InPreD_PRONTO_metadata.txt` | The clinical data file. Reports will be generated for the `Sample_id` for which the `Create_report` value is set to `Y` in this file. |
| `In/MTF/IPD-XXXX_Material Transit Form InPreD NGS.xlsx` | The material file contains all patient personal information. (Used by OUS) This file will generate the inpred-samle-id following the nomenclature file. |

<br />
<br />

| OUTPUT file/folder name: | Details: |
|:---|:---|
| `Out/$runID/IPZXXXX` | The folder contains all results for sample `IPZXXXX` from sequencing run $runID. |
| `Out/$runID/IPZXXXX/extra_files` | The folder contains filter tables during the calculation process, and the patient material file from lab. |
| `Out/$runID/IPZXXXX/IPZXXXX_MTB_report.pptx` | The PP report file. (TODO: explain PP) |
| `Out/$runID/IPZXXXX/IPZXXXX_Remisse_draft.docx` | The remise draft file for email. (Used by OUS) |
| `Out/InPreD_PRONTO_metadata_tsoppi.txt` | The file contains clinical data and the TSOPPI results for all sample reports. |

<br />
<br />

| Files located in the `Testing_data` folder : | Details: |
|:---|:---|
| `testRunID="191206_NB501498_0174_AHWCNMBGXC"` | `testRunID` is used in the following lines of this table as a shortcut for the full ID of the sequencing run, which is `191206_NB501498_0174_AHWCNMBGXC`.|
| `$testRunID_TSO_500_LocalApp_postprocessing_results.zip` | The testing data from AcroMetrix sample TSOPPI results which only contains the files PRONTO needs. Move this folder into your local TSOPPI result path for testing. |
| `InPreD_PRONTO_metadata.txt` | The file contains clinical data of AcroMetrix samples for testing. Move this file into `In` folder of this repository for testing. |
| `$testRunID.zip` | The testing results from AcroMetrix sample TSOPPI results for your local comparisons. |



<br />

## Run PRONTO locally

### Adapt the config file:

- In `Config/configure_PRONTO.ini`, please specify your InPreD node by defining value of the `inpred_node` parameter. The node name will appear in the header of the reports.
- In `Config/configure_PRONTO.ini`, please specify the local dataset file path of TSOPPI results by defining value of the `data_path` parameter.

### Type clinical data into the input metadata file:

Manually write the clinical data into file `In/InPreD_PRONTO_metadata.txt`. Reports will be generated for the `Sample_id` for which the `Create_report` value is set to `Y` in this file.

### Run PRONTO:

PRONTO takes in TSOPPI data, clinical info provided in `In/InPreD_PRONTO_metadata.txt`, and powerpoint template `In/Templates/MTB_template.pptx`. It generates a patient report for every `Sample_id` with the `Create_report` set to `Y` in the `Out` folder and updates the file `Out/InPreD_PRONTO_metadata_tsoppi.txt` with the TSOPPI results of the patients for which the reports were generated.


To print the usage information run the following command:

```
python3 Script/PRONTO.py --help
```

To execute the command and generate the reports as defined in the input metadata file, run the command:

```
python3 Script/PRONTO.py
```


<br />

## Example commands

### Print the usage information:

```
python3 Script/PRONTO.py -h
```

### Execute the report generating process:

```
python3 Script/PRONTO.py
```

After executing the script and generating all the required reports, update the `Create_report` value to `N` for every sample for which the report should not be re-generated in the future.

### Special commands used by OUS:

```
python3 Script/PRONTO.py -r <TSO500_runID> -D <DNA_sampleID> -c
python3 Script/PRONTO.py -m
```
- -c, --clinical_file: Fill the patient personal information into file InPreD_PRONTO_metadata.txt with the MTF files under the foder In/MTF/.
- -m, --mail_draft: Generate the Remisse_draft.docx file with report.


<br />

## PRONTO Docker

### Download the image with the latest tag:

```
docker pull inpred/pronto:latest
```

### Modify content of the config file:

- Specify your InPreD node name as the value of the `inpred_node` parameter in the `Config/configure_PRONTO.ini` file.
- Keep the `data_path` parameter's value set to `/pronto/tsoppi_data/` in the same config file.


### Run PRONTO with docker image:

```
sudo docker run \
--rm -it \
-v $tsoppi_data:/pronto/tsoppi_data \
-v $InPreD_PRONTO_metadata_file:/pronto/In/InPreD_PRONTO_metadata.txt \
-v $pronto_output_dir:/pronto/Out \
inpred/pronto:latest \
python /pronto/Script/PRONTO.py
```

- `$tsoppi_data` is the path of your local TSOPPI results, which contains all runs of TSOPPI data (not the folder for individual runs).
- `$InPreD_PRONTO_metadata_file` is your local InPreD meta data file which contains clinical data for the samples.
- `$pronto_output_dir` is the path in your local environment to store the reports generated by PRONTO.


<br />

## PRONTO Singularity

### Download PRONTO singularity image with the latest tag:

```
singularity pull PRONTO_singularity_image.sif docker://inpred/pronto:latest
```


### Modify content of the config file:

- Specify your InPreD node name as the value of the `inpred_node` parameter in the `Config/configure_PRONTO.ini` file.
- Keep the `data_path` parameter's value set to `/pronto/tsoppi_data/` in the same config file.


### Run PRONTO image with Singularity:

```
singularity exec \
--no-home \
-B $tsoppi_data:/pronto/tsoppi_data \
-B $InPreD_PRONTO_metadata_file:/pronto/In/InPreD_PRONTO_metadata.txt \
-B $pronto_output_dir:/pronto/Out \
-W $SINGULARITY_TMP \
$dir/PRONTO_singularity_image.sif \
python /pronto/Script/PRONTO.py
```

- `$tsoppi_data` is the path of your local TSOPPI results, which contains all runs of TSOPPI data (not the folder for individual runs).
- `$InPreD_PRONTO_metadata_file` is your local InPreD meta data file which contains clinical data for the samples.
- `$pronto_output_dir` is the path in your local environment to store the reports generated by PRONTO.py.


<br />

## ChangeLog

### v1.1

- New Features: (TODO: fill in)
- Resolved Issues:
[ #5](https://github.com/InPreD/PRONTO/issues/5)
[ #7](https://github.com/InPreD/PRONTO/issues/7)
[ #8](https://github.com/InPreD/PRONTO/issues/8)
[#14](https://github.com/InPreD/PRONTO/issues/14)
[#17](https://github.com/InPreD/PRONTO/issues/17)
- Other Changes: (TODO: fill in)

### v1.0
- First tracked version.

0 comments on commit 11fee79

Please sign in to comment.