In order to run MixMir, PLINK (v1.07) must be installed (http://pngu.mgh.harvard.edu/~purcell/plink/) and a copy of the PLINK executable placed in the MixMir directory. MixMir can run either GEMMA (v0.94) or FaST-LMM (v2.07) to solve mixed linear models (MLM). While we include GEMMA v0.94 in the MixMir folder, FaST-LMM should be downloaded from http://research.microsoft.com/en-us/um/redmond/projects/mscompbio/fastlmm/. The executable script should then be placed in the MixMir folder.
The user should make sure that PLINK, GEMMA and FaST-LMM are executable before running MixMir. This can be done by, for example, executing the command
chmod +x gemma-0.94
You can run an example of MixMir by using the data in the testdata folder. This can be done by executing:
python MixMir.py --seqf testdat/test-utrs.fa --exprf testdat/test-exprs.txt --mirf testdat/testmirs.fa --k_kin 6 --k_motif 6 --N 20 --fast 0 --out testdat/test
This script will produce a list of the top 20 motifs with corresponding matches to microRNAs (miRNAs) in testdat/testmirs.fa and write to the file testdat/test-MixMir-results.txt.gemma. If we chose the option --fast 1 instead, which uses FaST-LMM to solve the MLM instead of GEMMA, the results file will be testdat/test-MixMir-results.txt.fastlmmc. Mature miRNA sequences can be downloaded from miRBase (http://www.mirbase.org/).
For assistance on the parameters, type
python MixMir.py -h
Note that depending on which program is used to solve the MLM, a different set of temporary files may be generated - GEMMA will generate a folder in the MixMir folder called output, where all GEMMA output will be directed. Full GEMMA results will then be found in output/file.assoc.txt. FaST-LMM, however, will print full results in the same directory as the fastlmmc executable, and will be named file.out.txt. MixMir then moves this file to file.fastlmmc-out.txt.
Both GEMMA and FaST-LMM use as input .bed, .bim, and .fam files generated by PLINK. MixMir parses the sequence and phenotype files into .ped and .map files, runs PLINK, and then runs either GEMMA or FaST-LMM, depending on user specification. From our experience, for smaller datasets both GEMMA and FaST-LMM perform comparably. FaST-LMM appears to perform better for larger datasets as it can use multiple cores, particularly because in some cases where GEMMA fails to compute. FaST-LMM can set negative eigenvalues to zero.
INSTRUCTIONS
Type python MixMir.py -h for MixMir options. Options listed below:
usage: MixMir.py [-h] --seqf SEQF --exprf EXPRF [--kinf KINF] [--k_kin K_KIN]
[--k_motif K_MOTIF] [--N N] --mirf MIRF [--fast FAST]
[--out OUT]
Tell me which files and format to use
optional arguments:
-h, --help show this help message and exit
--seqf SEQF UTR sequence file in fasta format
--exprf EXPRF Phenotype file: column 1 is ID; column 2 is expression
--kinf KINF If a kinship file has already been computed, can
designate here
--k_kin K_KIN Motif length for kinship matrix (default is 6)
--k_motif K_MOTIF Length of motifs analyzed (default is 6)
--N N How many top results to analyze (default is 20)
--mirf MIRF miRNA sequence fasta file
--fast FAST Use option if using FastLMM to solve the mixed linear
models (default is False)
--out OUT Results output file basename (default is MixMir-out)
OUTPUT
In addition to the output files from either GEMMA or FaST-LMM (depending on the option selected), MixMir will also create a summary output file which contains the following information, for the top N motifs, where N is some user-designated integer. The summary output file contains 6 columns:
-Rank: The rank of the motif returned, based on lowest P-value
-Motif: Sequence of the actual motif
-P-value: P-value of the motif, pulled from either GEMMA or FaST-LMM output, rounded to 8 decimal places
-Coef: Fixed-effect coefficient of the motif, pulled from either GEMMA or FaST-LMM, rounded to 8 decimal places
-NUTRs: Number of UTRs from the UTR fasta file in which the motif was present
-miRNAs matched: List of miRNAs matched to the motif, along with their match position, where
[2] indicates a perfect seed match, [1] and [3] indicate offset seed matches,
and [A1] indicates an A1 type match
If you run into problems don't hesitate to comment, but I will likely not be able to reach out in a timely manner.