aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFrederick Muriuki Muriithi2022-05-09 05:20:53 +0300
committerFrederick Muriuki Muriithi2022-05-09 05:37:06 +0300
commit7c3335f7c81a5f30dc1b6f55c5cc858c35f17981 (patch)
tree16f2135c4f4980a778b3b030ec64b80430f21c3b
parent90ae44b4b336aa3fbca965da8c1948317714a11a (diff)
downloadgn-uploader-7c3335f7c81a5f30dc1b6f55c5cc858c35f17981.tar.gz
Update documentation and license
Add documentation on how to run the development version of the GeneNetwork Quality Control application. Update the license to the agpl3+ license used by genenetwork3
-rw-r--r--README.org79
-rw-r--r--guix.scm2
2 files changed, 62 insertions, 19 deletions
diff --git a/README.org b/README.org
index ecf7815..8162617 100644
--- a/README.org
+++ b/README.org
@@ -1,5 +1,5 @@
#+STARTUP: inlineimages
-#+TITLE: Quality Control Application
+#+TITLE: GeneNetwork Quality Control Application
** Project Goals
@@ -29,13 +29,59 @@ following criteria:
For reproducibility, this project is developed using guix.
-To launch a guix shell for development, do:
+To launch a guix shell for development, do
+#+BEGIN_SRC shell
+ guix shell --container --network --pure --manifest=manifest.scm --share=/some/host/directory=/the/upload/directory
+#+END_SRC
+which environment that is isolated from the rest of your system.
+
+We share a host directory with the container (that is writeable by the user that
+started the web application) to serve as the upload directory for the
+application.
+*** Run the CLI version
+
+To run the CLI version of the application, we need to set up the correct ~PYTHONPATH~
+#+BEGIN_SRC shell
+export PYTHONPATH="${PYTHONPATH:+$PYTHONPATH:}$(pwd)"
+#+END_SRC
+which enables us to run the script with
#+BEGIN_SRC shell
- guix shell --container --network --manifest=manifest.scm
+python3 scripts/qc.py --help
#+END_SRC
-to get an environment that is isolated from the rest of your system.
+Without setting up the ~PYTHONPATH~ environment variable, you might get an error
+like the following
+#+BEGIN_EXAMPLE shell
+$ python3 scripts/qc.py --help
+Traceback (most recent call last):
+ File "/home/frederick/genenetwork/gnqc_py/scripts/qc.py", line 8, in <module>
+ from quality_control.errors import ParseError
+ModuleNotFoundError: No module named 'quality_control'
+#+END_EXAMPLE
+
+*NOTE*: Setting up the ~PYTHONPATH~ environment variable is only necessary for
+the development environment. It *MUST NOT* require that the end-user set this up
+at all!
+
+*** Run the web version
+
+To run the web-version of the qc app in development mode, you need to set up a
+few environment variables
+#+BEGIN_SRC shell
+export FLASK_APP=wsgi.py
+export FLASK_ENV=development
+export QCAPP_INSTANCE_PATH=/path/to/directory/with/config.py
+#+END_SRC
+then you can run the application with
+#+BEGIN_SRC shell
+flask run
+#+END_SRC
+
+You then need to manually start the *rq* worker(s)
+#+BEGIN_SRC shell
+rq worker qcapp_queue
+#+END_SRC
*** Checks
@@ -56,23 +102,23 @@ To check for correct type usage in the application, run:
** Running QC
-*** Command-Line Version
+*** Installing QC
-Clone this repository
+The application can be installed using guix by pointing to the [[./guix.scm][guix.scm]] file as
+follows:
#+BEGIN_SRC shell
- git clone http://git.genenetwork.org/fredmanglis/gnqc_py.git
-#+END_SRC
-then install the application
-#+BEGIN_SRC shell
- $ python3 -m venv .venv
- $ source .venv/bin/activate
- (.venv) $ pip install .
+guix package [-p /path/to/qc/profile] -f guix.scm
#+END_SRC
+Once installed, the sections that follow show how to use the *qc* application
+
+*** Command-Line Version
+
+Install the application as shown in the [[Installing QC]] section above.
To run qc against a file, the syntax is:
#+BEGIN_SRC shell
- python3 -m qc [--strainsfile <strainsfile-path>] [--verbose] <filetype> <filepath>
+ qc [--strainsfile <strainsfile-path>] [--verbose] <filetype> <filepath>
#+END_SRC
where
- ~<filetype>~ is one of "*average*" or "*standard-error*"
@@ -85,12 +131,9 @@ where
To view the usage information for the application, run
#+BEGIN_SRC shell
- python3 -m qc --help
+qc --help
#+END_SRC
-**** TODO Figure out how to put qc.py in a /bin or /scripts directory and still be able to import the modules in the repo
-**** TODO Reduce the command to simply ~qc [--strainsfile <strainsfile-path>] [--verbose] <filetype> <filepath>~
-
*** Web Version
Coming soon...
diff --git a/guix.scm b/guix.scm
index acfa307..339590c 100644
--- a/guix.scm
+++ b/guix.scm
@@ -42,4 +42,4 @@
"GeneNetwork qc is a quality control application for the data files that
eventually are used to add to the data in the GeneNetwork project.")
(home-page "https://git.genenetwork.org/fredmanglis/gnqc_py")
- (license license:gpl3))
+ (license license:agpl3+))