diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 156 |
1 files changed, 93 insertions, 63 deletions
@@ -19,7 +19,8 @@ also encourage contributions, for example, by forking the repository, making your changes to the code, and issuing a pull request. Currently, GEMMA is supported for 64-bit Mac OS X and Linux -platforms. *Windows is not currently supported.* If you are interested +platforms. *Windows is not currently supported.* though you can +run GEMMA in a Linux VM or [container](https://docs.docker.com/docker-for-windows/). If you are interested in helping to make GEMMA available on Windows platforms (e.g., by providing installation instructions for Windows, or by contributing Windows binaries) please post a note in the @@ -52,13 +53,46 @@ algorithm can be used to estimate variance components when individual-level data are available. For summary data, GEMMA uses the MQS algorithm to estimate variance components. -## Quick start +## Installation + +To install GEMMA you can + +1. Download the precompiled binaries (64-bit Linux and Mac only) + +2. Use existing package managers, see [INSTALL.md](INSTALL.md). + +3. Compile GEMMA from source, see [INSTALL.md](INSTALL.md). + +Compiling from source takes more work, but can potentially boost +performance of GEMMA when using specialized C++ compilers and +numerical libraries. + +### Precompiled binaries + +1. Fetch the [latest stable release][latest_release] and download the + file appropriate for your platform. + +2. For .tar.bz2 files unpack the tar ball + + tar xvjf gemma-$version-installer.tar.bz2 + + run the installer + + ./install.sh ~/gemma + + and run gemma + + ~/gemma/bin/gemma + +3. For .gz files run `gunzip gemma.linux.gz` or `gunzip +gemma.linux.gz` to unpack the file. + -1. Download and install the software. See [INSTALL.md](INSTALL.md). +## Quick start -2. Work through the demo. *Give more details here.* +1. Work through the demo. *Give more details here.* -3. Read the manual and run `gemma -h`. *Give more details here.* +2. Read the manual and run `gemma -h`. *Give more details here.* ## Citing GEMMA @@ -92,7 +126,7 @@ studies.](https://doi.org/10.1101/042846) *Annals of Applied Statistics*, in pre ## License -Copyright (C) 2012–2017, Xiang Zhou. +Copyright (C) 2012–2017, Xiang Zhou and team. The *GEMMA* source code repository is free software: you can redistribute it under the terms of the @@ -103,10 +137,10 @@ warranty**; without even the implied warranty of **merchantability or fitness for a particular purpose**. See file [LICENSE](LICENSE) for the full text of the license. -The source code for the -[shUnit2](https://github.com/genenetwork/shunit2) unit testing -framework, included in this repository [here](contrib/shunit2-2.0.3), is -distributed under the +Both the source code for the +[gzstream zlib wrapper](http://www.cs.unc.edu/Research/compgeom/gzstream/) +and [shUnit2](https://github.com/genenetwork/shunit2) unit testing +framework included in GEMMA are distributed under the [GNU Lesser General Public License](contrib/shunit2-2.0.3/doc/LGPL-2.1), either version 2.1 of the License, or (at your option) any later revision. @@ -115,64 +149,59 @@ The source code for the included [Catch](http://catch-lib.net) unit testing framework is distributed under the [Boost Software Licence version 1](https://github.com/philsquared/Catch/blob/master/LICENSE.txt). -## What's included - -This is the current structure of the GEMMA source repository: - -``` -├── LICENSE -├── Makefile -├── NEWS.md -├── README.md -├── bin -├── doc -├── example -└── src -``` +### Optimizing performance -*Write a paragraph here briefly explaining what is in each of the -subfolders; see Wilson et al "Good Enough Practices" paper for example -of this.* - -## Setup - -To install GEMMA you can - -1. Download the precompiled binaries (64-bit Linux and Mac only), see - [latest stable release][latest_release]. - -2. Use existing package managers, see [INSTALL.md](INSTALL.md). - -3. Compile GEMMA from source, see [INSTALL.md](INSTALL.md). - -Compiling from source takes more work, but can boost performance of -GEMMA when using specialized C++ compilers and numerical libraries. - -Source code and [latest stable release][latest_release] are available -from the Github repository. - -### Precompiled binaries - -1. Fetch the [latest stable release][latest_release] and download the -file appropriate for your platform: `gemma.linux.gz` for Linux, or -`gemma.macosx.gz` for Mac OS X. - -2. Run `gunzip gemma.linux.gz` or `gunzip gemma.linux.gz` to -unpack the file. - -3. Downloadable binaries are linked to static versions of the GSL, -LAPACK and BLAS libraries. There is no need to install these -libraries. +Precompiled binaries and libraries may not be optimal for your particular +hardware. See [INSTALL.md](INSTALL.md) for speeding up tips. ### Building from source -*Note that GEMMA currently does not work with GSL 2.x. We recommend -linking to the latest version of GSL 1.x, which is GSL 1.16 as of this -writing.* - More information on source code, dependencies and installation can be found in [INSTALL.md](INSTALL.md). +## Reporting a GEMMA bug or issue + +For bugs GEMMA has an +[issue tracker](https://github.com/genetics-statistics/GEMMA/issues) +on github. For general support GEMMA has a mailing list at +[gemma-discussion](https://groups.google.com/forum/#!forum/gemma-discussion) + +Before posting an issue search the issue tracker and mailing list +first. It is likely someone may have encountered something +similiar. Also try running the latest version of GEMMA to make sure it +has not been fixed already. Support/installation questions should be +aimed at the mailing list. The issue tracker is for development issues +around the software itself. When reporting an issue include the output +of the program and the contents of the .log.txt file in the output +directory. + +### Check list: + +1. [X] I have found and issue with GEMMA +2. [ ] I have searched for it on the [issue tracker](https://github.com/genetics-statistics/GEMMA/issues?q=is%3Aissue) (incl. closed issues) +3. [ ] I have searched for it on the [mailing list](https://groups.google.com/forum/#!forum/gemma-discussion) +4. [ ] I have tried the latest [release](https://github.com/genetics-statistics/GEMMA/releases) of GEMMA +5. [ ] I have read and agreed to below code of conduct +6. [ ] If it is a support/install question I have posted it to the [mailing list](https://groups.google.com/forum/#!forum/gemma-discussion) +7. [ ] If it is software development related I have posted a new issue on the [issue tracker](https://github.com/genetics-statistics/GEMMA/issues) or added to an existing one +8. [ ] In the message I have included the output of my GEMMA run +9. [ ] In the message I have included the relevant .log.txt file in the output directory +10. [ ] I have made available the data to reproduce the problem (optional) + +To find bugs the GEMMA software developers may ask to install a +development version of the software. They may also ask you for your +data and will treat it confidentially. Please always remember that +GEMMA is written and maintained by volunteers with good +intentions. Our time is valuable too. By helping us as much as +possible we can provide this tool for everyone to use. + +## Code of conduct + +By using GEMMA and communicating with its communtity you implicitely +agree to abide by the +[code of conduct](https://software-carpentry.org/conduct/) as +published by the Software Carpentry initiative. + ## Credits The *GEMMA* software was developed by: @@ -182,7 +211,8 @@ Dept. of Biostatistics<br> University of Michigan<br> 2012-2017 -Peter Carbonetto, Tim Flutre, Matthew Stephens, Pjotr Prins and others -have also contributed to the development of this software. +Peter Carbonetto, Tim Flutre, Matthew Stephens, +[Pjotr Prins](http://thebird.nl/) and others have also contributed to +the development of this software. [latest_release]: https://github.com/genetics-statistics/GEMMA/releases "Most recent stable releases" |