diff --git a/Dockerfile b/Dockerfile index 1fed4e0..05bc017 100644 --- a/Dockerfile +++ b/Dockerfile @@ -25,6 +25,7 @@ RUN wget https://github.com/lh3/seqtk/archive/refs/tags/v1.3.tar.gz && \ WORKDIR /app -COPY . . +COPY lib/censuscope.py ./lib/censuscope.py +COPY test_data ./test_data -CMD ["python", "lib/censuscope.py"] +CMD ["python", "lib/censuscope.py"] \ No newline at end of file diff --git a/README.md b/README.md index f2379a4..85eb71e 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,17 @@ # CensuScope -We have chosen to apply the Creative Commons Attribution 3.0 Unsupported License to this version of the software. - -Mazumder Lab. What is CensuScope? ------------------------ -* CensuScope is designed and optimized for the quick detection of the components in a given NGS metagenomic dataset and provides users - with a standard format report of components into species or higher taxonomic node resolution. - - The core of CensuScope consists of census-based reads file generation and Blast/bowtie based short-reads alignment. - CensuScope is capable of sample contamination evaluation, microbiome components detection and other meta-omic related data analysis. - -Installation instructions: ------------------------------------------------------------------------ -CensuScope link: https://hive.biochemistry.gwu.edu/dna.cgi?cmd=censuscope - -Users must download the CensuScope package before running. - - -* You need concatenated BLAST-NT database (or the MetaPhlAn Markers database) as a reference, we have already prepared - this database. When the download has finished (it is a zip folder with 11.0 GB size containing all required files) - extract the compressed Package (censuscope.zip) into your system.(for ex. directory is c:\) - The compressed folder includes BLAST-NT database (17GB) and Blastn software and a bacterial - read datasets from prokaryotes (bacteria.fastq) for testing. - -CensuScope v1.2 (Windows version) README -==================================== - -How to use CensuScope? ---------------------------- -<> -<> - - 1. go to CensuScope-win directory and Run censuscope.exe - - 2. Set the path of your source file(for example c:\censuscope\source\bacteria.fastq) - - 3. Set the path of CensuScope Package where you extracted it,please do not include CensuScope main folder into path (for example c:\ or d:\desktop\) - - 4.choose your desired database , you can select the Blast-NT or MetaPhlAn database - - 5. Set the number of iterations and set the size of samples - - 6. Press submit and wait (please do not minimize the application) - - 7. The output will be downloadable as a Zip file and you can check the generated output at this direction \CensuScope\sample\ +CensuScope is designed for the quick detection of the components in a given NGS metagenomic dataset. It can provide users with a standard format report of components into species or higher taxonomic node resolution. -THE OUTPUT ------------------------------ - -* Final results are in 4 different files (3 csv and 1 txt) - - 1. log.txt -- this text file provides all parameters which have been used to run and generate the result - - 2. gi_centric_table.csv -- GI_numbers sorted result - - 3. tax_centric_table.csv -- TAX_ID Sorted result - - 4. taxslim_centric_table.csv -- Kingdom-depth taxonomy sorted result - -CensuScope v1.2 (UNIX version) README -===================================== - -How to use CensuScope: ---------------------------- -* Users need a PHP or ZEND server on their system for running this version. -<< It is recommended that you use a computer with RAM capacity more than 1GB>> -<> - - PARAMETERS : - -i : set the number of iterations - - -s : set the size of samples (per READ) +The core of CensuScope consists of census-based reads file generation and Blast/bowtie based short-reads alignment. +CensuScope is capable of sample contamination evaluation, microbiome components detection and other meta-omic related data analysis. - -t : set the depth of tax_slim (it is set to 3=kingdom) - - -d : path to the source - - -p : path of censuscope Package - - - FOR EXAMPLE : - $ php censuscope.php -i 10 -s 1000 -t 3 -d '/user/desktop/fungi.fastq' -p '/user/' - -THE OUTPUT ------------------------------ +Deployment instructions: +- [Local deployment](docs/deployment/localDeployment.md) +- [Docker deployment](docs/deployment/dockerDeployment.md) -* Final result are in 4 different files (3 csv and 1 txt) - - 1. log.txt -- this text file provide all parameters which have been used to run and generate the result - - 2. gi_centric_table.csv -- GI_numbers sorted result - - 3. tax_centric_table.csv -- TAX_ID Sorted result - - 4. taxslim_centric_table.csv -- Kingdom-depth taxonomy (or whatever taxonomic depth is chosen by user) sorted result - +## CensuScope Development and troubleshooting +- [FAQ and trouble shooting](docs/faq.md) +- [`.secretes` configuration](docs/config.md) +- [Testing](docs/testing.md) \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index c57c0be..2c32561 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -10,11 +10,10 @@ services: -i 10 -s 5 -t 5 - -q /app/input_files/GW-04_S4_L001_R1_001.fastq - -d /app/input_files/blast_db/gfkb/HumanGutDB-v2.6.fasta + -q /app/test_data/GW-04_S4_L001_R1_001.fastq + -d /app/test_data/blast_db/gfkb/HumanGutDB-v2.6.fasta volumes: - - /tmp/test:/app/input_files - /tmp/test/outputs:/app/temp_dirs stdin_open: true tty: true diff --git a/docs/deployment/dockerDeployment.md b/docs/deployment/dockerDeployment.md new file mode 100644 index 0000000..7b2cd75 --- /dev/null +++ b/docs/deployment/dockerDeployment.md @@ -0,0 +1,58 @@ +# CensuScope Docker Deployment + + +### Requirements +- Python 3: [3.10.6 reccomended](https://www.python.org/downloads/release/python-3106/) +- Docker: + - [Docker Desktop for Linux](https://docs.docker.com/desktop/install/linux-install/) + - [Docker Desktop for Mac (macOS)](https://docs.docker.com/desktop/install/mac-install/) + - [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/) + +## Clone the repository +``` +git clone https://github.com/GW-HIVE/CensuScope/ +``` + +## Enter the repository +``` +cd CensuScope +``` + +**Make sure you are on the desired branch (Check for latest branch):** + +``` +git switch [DESIRED BRANCH TAG] +``` + +### Building CensuScope via Docker + +A docker file is provided to allow easy building of the BCO API. This can be done from the root directory (the directory with Dockerfile in it) by running: + +`docker build -t censuscope .` + +This will build a container named `censuscope`. + +The build process (via the `entrypoint.sh` script) will check for an existing database in the repository and run migrations. If no database is present one will be created and the test data will be loaded (taken from `config/fixtures/local_data.json`). + +### Running the container via Docker + +The BCO Api container can be run via docker on the command line in Linux/Windows by running: + +`docker run --rm --network host -it bco_api:latest` + +The BCO Api container can be run via docker on the command line in MacOS by running: + +`docker run --rm -p 8000:8000 -it bco_api:latest` + +This will expose the server at `http://127.0.0.1:8000`, whitch is where all of the default settings will expect to find the BCODB. + +#### Overriding the port + +It is possible to override the port 8000 to whatever port is desired. This is done by running the container with 8080 representing the desired port. + +`docker run --rm --network host -it bco_api:latest 0.0.0.0:8080` + + +NOTE: The ip address of 0.0.0.0 is to allow the web serer to properly associate with 127.0.0.1 - if given 127.0.0.1 it will not allow communications outside of the container! + +You can also give it a specific network created with `docker network create` if you wanted to give assigned IP addresses. diff --git a/docs/deployment/localDeployment.md b/docs/deployment/localDeployment.md new file mode 100644 index 0000000..e69de29