From 34dfa073d74648693bc6ab68dc1aa362ed1e6b71 Mon Sep 17 00:00:00 2001
From: Yasemin Bridges <y.bridges@qmul.ac.uk>
Date: Thu, 21 Sep 2023 11:38:38 +0100
Subject: [PATCH] update README.md

---
 README.md | 101 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 84 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index ff2b28d..6cd2cd5 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,105 @@
 # LIRICAL Runner for PhEval
-This is the LIRICAL plugin for PhEval. Highly experimental. Do not use.
 
-## Developers
+This is the LIRICAL plugin for PhEval. With this plugin, you can leverage the prioritisation tool, LIRICAL, to run the PhEval pipeline seamlessly. he setup process for running the full PhEval Makefile pipeline differs from setting up for a single run. The Makefile pipeline creates directory structures for corpora and configurations to handle multiple run configurations. Detailed instructions on setting up the appropriate directory layout, including the input directory and test data directory, can be found here.
 
-An example skeleton `config.yaml` has been provided (`pheval.phen2gene/config.yaml`) which should be be correctly filled and moved to the input-dir location.
+## Installation 
 
-Warning, the pheval library currently needs to be included as a file reference in the toml file.
+Clone the pheval.lirical repo and set up the poetry environment:
 
+```shell
+git clone https://github.com/yaseminbridges/pheval.lirical.git
+cd pheval.lirical
+poetry shell
+poetry install
 ```
-poetry add /Users/yaseminbridges/Documents/GitHub/pheval
 
-poetry lock
+## Configuring a *single* run:
 
-poetry install
+### Setting up the input directory
+
+A `config.yaml` should be located in the input directory and formatted like so:
+
+```yaml
+tool: LIRICAL
+tool_version: 2.0.0-RC2
+variant_analysis: True
+gene_analysis: True
+disease_analysis: True
+tool_specific_configuration_options:
+  mode: phenopacket
+  lirical_jar_executable: lirical-cli-2.0.0-RC2/lirical-cli-2.0.0-RC2.jar
+  exomiser_db_configurations:
+    exomiser_database:
+    exomiser_hg19_database: 2302_hg19_variants.mv.db
+    exomiser_hg38_database:
+  post_process:
+    sort_order: descending
 ```
+The bare minimum fields are filled to give an idea on the requirements. 
 
-This will change when pheval is published on pypi.
+The LIRICAL data files should be located in the input directory under a subdirectory named `data`
+If running LIRICAL with variant and/or gene analysis set to true, you will need to provide the relevant exomiser hg19/hg38 databases.
 
-To install the LIRICAL plugin:
+The lirical jar executable points to the location in the input directory.
 
-``` 
-git clone https://github.com/yaseminbridges/pheval.lirical.git
+The input directory should look something like so (removed some files for clarity):
 
-cd pheval.lirical/
+```tree
+.
+├── 2302_hg19_variants.mv.db
+├── config.yaml
+├── data
+│   ├── hg19_refseq.ser
+│   ├── hg19_ucsc.ser
+│   ├── hg38_refseq.ser
+│   ├── hg38_ucsc.ser
+│   ├── hgnc_complete_set.txt
+│   ├── hp.json
+│   ├── mim2gene_medgen
+│   └── phenotype.hpoa
+└── lirical-cli-2.0.0-RC2
+    └── lirical-cli-2.0.0-RC2.jar
 
-poetry add /path/to/local/pheval
+```
+### Setting up the testdata directory
 
-poetry lock
+The LIRICAL plugin for PhEval accepts phenopackets and vcf files as an input. The plugin can be run in only `disease_analysis` mode, where only phenopackets are required as an input, however, this *must* be specified in the `config.yaml`.
 
-poetry install
+The testdata directory should include subdirectories named `phenopackets` and `vcf` if running with gene/variant prioritisation.
+
+e.g., 
+
+```tree
+├── testdata_dir
+   ├── phenopackets
+   └── vcf
 ```
 
-To install PhEval:
+## Run command
 
+Once the testdata and input directories are correctly configured for the run, the `pheval run` command can be executed.
+
+```bash
+pheval run --input-dir /path/to/input_dir \
+--testdata-dir /path/to/testdata_dir \
+--runner liricalphevalrunner \
+--output-dir /path/to/output_dir \
+--version 13.2.0
 ```
-git clone https://github.com/monarch-initiative/pheval.git 
+
+## Common errors
+
+You may see an error that is related to the current `setuptools` being used:
+
+```shell
+pkg_resources.extern.packaging.requirements.InvalidRequirement: Expected closing RIGHT_PARENTHESIS
+    requests (<3,>=2.12.*) ; extra == 'parse'
+             ~~~~~~~~~~^
 ```
+
+To fix the error, `setuptools` needs to be downgraded to version 66:
+
+```shell
+pip uninstall setuptools
+pip install -U setuptools=="66"
+```
\ No newline at end of file