=== DESCRIPTION ===
This program takes a PLINK genotype file, runs it through PLINK,
illustrates the results via locuszoom, identifies the SNP with the
most significant (i.e. lowest) p-value, adds this SNP to a condition
list, and then repeats the process until there are no SNPs with p-values
below a given threshold of significance.
Required commands: 	--script <script path>
			--outfolder <folder path>
			--test <test name>
			--chromosome <number>
			--from-mb <start in Mb> --to-mb <end in Mb>
 		OR	--from-kb <start in kb> --to-kb <end in kb>
		OR	--from-bp <start in bp> --to-bp <end in bp>
			
Optional commands:	--chrband <chr band>
			--refgene <gene name>
			--flag <word>
			--pbound <number>
			--loop <number>
			--condition-list <file path>
			--pheno <file path>

=== INSTRUCTIONS ===
Argument and default information for this program can be accessed
with a call to the program using --help or -h.

== REQUIRED COMMANDS ===

SCRIPT:
--script <script path>		OR	-s <script path>
Commands to the program MUST include the path location of a
script containing the following constructions directly from PLINK:
	--bfile <full path name of binary data files to be fed
	  	into PLINK (without extension)>
	--covar <full path name of covariate file (include extension)>
	Optionally, one can also include the following flags:
	--noweb
	--sex
	--hide-covar
Scripts CANNOT contain:
	ANY output file information, constructed in PLINK using:
		--out
	ANY type of regional information, constructed in PLINK using:
		--from...
		--to...
		--chromosome
		--window
		--gene
	Association test commands (those will come later):
		For examples, see:
		http://pngu.mgh.harvard.edu/~purcell/plink/anal/ahtml#cc
	Condition List information, constructed in PLINK using:
		--condition-list
	Phenotype commands, constructed in PLINK using
		--pheno
		--all-pheno
		--pheno-name
	
OUTPUT FOLDER:
--outfolder <folder path>	OR	-o <folder path>
Commands to the program MUST include the path location of a Big Mama
results folder. Within this folder, the program will constuct
additional folders to separate results by chromosome.

TEST:
--test <plink test>	OR	-t <plink test>
Commands to the program MUST include an indication of which PLINK test
 should be run. Current program configuration will accept the following:
 	--test logistic
 	--test linear
 	--test assoc
 	--test fisher
 	--test model
 	--test mh
 
 CHROMOSOME:
 --chromosome <number>	OR	-c <number>
 Commands to the program MUST include the number of the chromosome on
 which the analysis should be run.
 
 REGIONAL BOUNDARIES:
 --from-mb <start in Mb> --to-mb <end in Mb>	OR
 --from-kb <start in kb> --to-kb <end in kb>	OR
 --from-bp <start in bp> --to-bp <end in bp>
 Commands to the program MUST include range information of a region
 on the chromosome. This can be given in mega-basepairs, kilo-basepairs,
 or basepairs (or a combination thereof).
 	__________________________________________
 
 === OPTIONAL COMMANDS ===
 Without these commands, the program will use current default values,
 which can be learned by using the --help command. To change the
 defaults, see the advanced user section.
 
 CHRBAND:
 --chrband <chr band>
 This command uses a chromosomal band name instead of range information
 to name output files.
 
 REFGENE:
 --refgene <gene name>
 This command uses a reference gene name instead of range information
 to name output files.
 
 PBOUND:
 --pbound <highest p-value of interest>
 This command sets the highest p-value that is considered significant.
 When there are no more SNPs with p-values below this number,
 the program terminates.
 
 MAXLOOPS:
 --loop <number> 	OR	-l <number>
 This command sets the maximum number of times the program should loop
 through PLINK.
 
 FLAG:
 --flag <word>		OR	-f <word>
 This command adds a word or phrase (NO SPACES) to the titles of all
 output files produced during the run.
 
 CONDITION-LIST:
 --condition-list <file path>
 This command takes the path location of a list of SNPs which should
 be included in the condition list from the very first loop through
 PLINK. All SNPs in the file will be copied to ~leastP_SNPs.txt, and
 any additional SNPs the program identifies will be added there.
 ANY output files produced through this command will contain '~'
 in the name.
 
 PHENO:
 --pheno <file path>
 This command takes the path location of a PLINK phenotype file. The
 program will perform separate loops for each of the phenotypes in
 the pheno-file.
 
 
 === EXAMPLES ===
 Example Script Text:
 --bfile /home/mst3k/data/soandso
 --covar /home/mst3k/data/soandso.cov 
 --hide-covar --sex --noweb
 
 Example Commandline Call:
 python plink_conditional.py --script /home/mst3k/data/soandso.txt
 --outfolder /home/mst3k/results/SoAndSo/ --test logistic --chromosome 11
 --refgene INS --from-mb 2.1 --to-mb 2.3
	_______________________________________________

=== DESCRIPTION ===
This program reads from a file containing regional information and
performs plink_conditional.py on each of the regions.

Required Commands:	--region-list <file path>
			+ ALL REQUIRED COMMANDS FOR PLINK_CONDITIONAL.PY
			
Optional Commands:	--cfolder <folder path>

=== INSTRUCTIONS ===
Argument and default information for this program can be accessed
with a call to the program using --help or -h.

=== REQUIRED COMMANDS ===

REGION-LIST:
--region-list <file path>
Commands to this program MUST include the path to a file containing
regional information for the regions on which plink_conditional
should be run. The column headings of the file must include: "gene_chr",
"region_start", "region_end", and "gene_symbol". The positional 
information MUST be given in megabase-pairs (Mb).

 
 PLINK_CONDITIONAL COMMANDS:
 Commands to this program MUST include any commands that would normally
 be given to plink_conditional.
 
 === OPTIONAL COMMANDS ===
 
 CONDITIONAL LIST FOLDER:
 --cfolder <folder path>
 This command takes the path location of a folder of condition-lists
 of SNPs, for naming purposes these should be produced by either
 meta_yank.py or assoc_yank.py. Each region (e.g. chromosomal band
 6q72.1 or region JKB on chromosome 6) in the region-list must have
 a corresponding condition-list in the folder (i.e. 6q72.1.txt or
 Chr6_JKB.txt). The SNPs in each condition-list will be copied to
 ~leastP_SNPs.txt and included in the condition-list from the very first
 loop through PLINK for the associated region. Any additional SNPs the
 program identifies will be added to the second location
 (~leastP_SNPs.txt), leaving the original lists in the condition-list
 folder unchanged. ANY output files produced through this command will
 contain '~' in the name.
	_____________________________________________________

=== DESCRIPTION ===
This program reads the log files produced during plink_conditional.py
and creates a summary file containing key information from the logs.
It also produces a second text file likely of interest only to the
programmer containing information about the first run through PLINK
from each log.

Required commands: 	--logfolder <folder path>
					--map <path to ORIGINAL map file>
					--freq <file path>

Optional commands:	--summary <filename NO EXTENSION>
					--runinfo <filename NO EXTENSION>

=== INSTRUCTIONS ===
Argument and default information for this program can be accessed
with a call to the program using --help or -h.

=== REQUIRED COMMANDS ===

LOG FOLDER:
--logfolder <folder path>
Commands to this program MUST include the path to the logs folder
which plink_conditional.py created within your Big Mama results folder.
So, the address of this folder will be Big_Mama's_Path/logs.

MAP FILE:
--map <file path>
Commands to this program MUST include the path to the original map file,
unaltered by map_adapt.

FREQUENCY FILE:
--freq <file path>
Commands to this program MUST include the path to the a frequency file for
the control population produced by plink. For your convenience:
	plink --bfile "data" --filter-controls --freq --make-bed --noweb --out "data"_controls


=== OPTIONAL COMMANDS ===

SUMMARY FILE NAME:
--summary <file name NO EXTENSION>
The program will write the summary file to the logs folder under the
name 'log_summary.txt', unless another basename is given.

RUN INFO NAME:
--runinfo <file name NO EXTENSION>
The program will write the run info to the logs folder under the name
'run_info.txt', unless another basename is given.
	_____________________________________________________

Required Commands:	--outfile <filepath>
					--meta <filepath>
					--region-list <filepath>

=== INSTRUCTIONS ===
Argument and default information for this program can be accessed
with a call to the program using --help or -h.

=== REQUIRED COMMANDS ===

OUTPUT FILE:
--out <file path>
Commands to this program MUST include the path to the file where the
results should be written.

META-ANALYSIS FILE:
--meta <file path>
Commands to this program MUST include the path to a meta-analysis file
containing the relevant SNP information. The column headings of the file
must include: "CHR", "MarkerName", "P-value","POS" (bp-position),
"Zscore".

REGION-LIST:
--region-list <file path> or -r <file path>
Commands to this program MUST include the path to a region-list file. The
column headings of the file must include: "gene_chr", "region_start",
"region_end", and "gene_symbol". The positional information MUST be given
in megabase-pairs (Mb).

	_____________________________________________________

Required Commands:	--outfile <filepath>
			--assoc <filepath>
			--region-list <filepath>
			--bp-form <'mb' OR 'kb' OR 'bp'>

=== INSTRUCTIONS ===
Argument and default information for this program can be accessed
with a call to the program using --help or -h.

=== REQUIRED COMMANDS ===

OUTPUT FILE:
--out <file path>
Commands to this program MUST include the path to the file where the
results should be written.

ASSOCIATION FILE:
--assoc <file path>
Commands to this program MUST include the path to a PLINK association file
containing the relevant SNP information. The column headings of the file
must include: "CHR", "SNP", "P", "BP" (bp-position).

REGION-LIST:
Commands to this program MUST include the path to a region-list file. The
column headings of the file must include: "gene_chr", "region_start",
"region_end", and "gene_symbol".

POSITIONAL UNITS:
--bp-form <'mb' OR 'kb' OR 'bp'>
Commands to this program MUST include one of three flags indicating
what unit is used to list positional information in the region list.


	_____________________________________________________

Required commands:	--map <file path>

=== INSTRUCTIONS ===
Argument information for this program can be accessed with a call
to the program using --help or -h.

=== REQUIRED COMMANDS ===

MAP FILE:
--map <path to map file>
Commands to the program MUST include the path to a map file.
	__________________________________________________

=== INSTRUCTIONS ===

DO NOT MAKE CALLS TO PC_WORKHORSE.PY

=== INSTRUCTIONS ===

DO NOT MAKE CALLS TO PC_TOOLBOX.PY

ONLY Users who know what they are doing:
	CHANGING DEFAULTS
	It might be easier for you to change some of the defaults at
	the top	of the program file than type in all of the command
	flags every time. If you would like, you may do this for
	plink_conditional.py or parse_log.py.
	DO NOT CHANGE DEFAULTS IN PC_WORKHORSE.PY.
	Open the program file in a text editor. The default values are
	set beneath the list of globals. The ones in which you may be
	interested are marked between rows of asterisks (*). DO NOT
	alter anything (i.e. the name of the default) on the left side
	of the equals sign, only change the value on the right side.
PLINK Constructions:
	plink_conditional.py only cares about 2 things:
	  1) The column names of the PLINK results file. The program
	     will look for columns titled 'P' and 'SNP' in order to
	     perform its search for the most significant SNP and then
	     use those column titles to instruct locus zoom. If a PLINK
	     construction results in differently titled columns, there
	     will be problems.
	  2) The file extension of the PLINK results file containing the
	     SNP and P-value information. If a PLINK construction alters
	     the file extension, there will be problems.