aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md42
1 files changed, 29 insertions, 13 deletions
diff --git a/README.md b/README.md
index e5805a8..ff1245b 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,39 @@
-# bionix
+<h1 align="center"> BioNix </h1>
-Bionix is a set of [Nix](http://nixos.org/nix) expressions for specifying and
-executing bioinformatics pipelines. It is currently a work in progress, so
-documentation is sparse.
+BioNix is a tool for reproducible bioinformatics that unifies workflow engines, package managers, and containers.
+It is implemented as a lightweight library on top of the [Nix](https://nixos.org/nix/) deployment system.
+
+BioNix is currently a work in progress, so documentation is sparse.
## Getting started
-Install [Nix](http://nixos.org/nix) and then try `nix-build` in the examples
-directory.
+Install [Nix](http://nixos.org/nix):
+
+```{sh}
+curl https://nixos.org/nix/install | sh
+```
+To run a sample pipeline, clone this project and run `nix-build` in the `/examples` directory:
+
+```{sh}
+$ git clone https://github.com/PapenfussLab/bionix
+$ cd examples
+$ nix-build
+```
+
+The sample pipeline performs variant calling using [`platypus`](https://github.com/andyrimmer/Platypus), alignment using [`bwa mem`](https://github.com/lh3/bwa), and preprocessing using [`samtools`](http://www.htslib.org/).
+BioNix will download or build all of the necessary software and create a soft link (`result`) to the workflow output.
+
+Next, check out the code:
+
+- The pipeline itself is specified in `examples/call.nix` and `examples/default.nix`.
+- The BioNix wrapper for `platypus` is in `tools/platypus-callVariants.nix`.
+- The software package for `platypus` can be found in [nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/science/biology/platypus/default.nix).
-## Example pipelines
+BioNix pipelines can be easily wrapped in shell scripts: see `examples/ex-tnpair/tnpair` for an example script that accepts a reference fasta, along with paired normal and tumor fastq files, and performs alignment, preprocessing, and variant calling with [`strelka`](https://github.com/Illumina/strelka).
-The examples directory shows a simple pipeline in the call.nix and default.nix
-files. You can build it with `nix-build` in the examples directory. The result
-will be linked to ./result, which in this example case is an empty VCF file.
+Writing your own pipelines requires some familiarity with the Nix programming language and deployment system. Good introductions can be found [here](https://learnxinyminutes.com/docs/nix/) and [here](https://ebzzry.io/en/nix/).
-There is another tumour-normal pipeline calling example consisting of `tnpair`
-and `tnpair.nix`. In this case, the shell script tnpair accepts a reference and
-two fastq files to run the pipeline defined in `tnpair.nix` on.
+We have successfully run BioNix pipelines in a zero-install manner (using a [statically linked binary](https://matthewbauer.us/blog/static-nix.html) and [user namespaces](https://www.redhat.com/en/blog/whats-next-containers-user-namespaces)), but this feature is currently unstable. Stay tuned!
## Contact