Usage

Program options

AlphaPeel accepts several command-line options to control the program’s behaviour. To view a list of all supported options, run AlphaPeel like this: AlphaPeel or AlphaPeel -h.

Input options

Individuals:
  -ped_file [PED_FILE ...]
                      Pedigree file(s)
                      (see format details).
  -geno_file [GENO_FILE ...]
                      Genotype file(s)
                      (see format details).
  -seq_file [SEQ_FILE ...]
                      Sequence allele read count file(s)
                      (see format details).
  -x_chr              Indicate that input data is for the X chromosome.
  -pheno_file [PHENO_FILE ...]
                      Phenotype file(s)
                      (see format details).
  -plink_file [PLINK_FILE ...]
                      Plink (binary) file(s)
                      (see format details).

Markers:
  -map_file MAP_FILE  Map file for loci in genomic data files
                      (see format details).
  -start_snp START_SNP
                      The first locus to consider.
                      Counting starts at 1.
                      Default: 1.
  -stop_snp STOP_SNP  The last locus to consider.
                      Default: all loci in input files.

Model parameters and other:
  -alt_allele_prob_file [ALT_ALLELE_PROB_FILE ...]
                      Alternative allele probability file
                      (see format details).
                      Default: 0.5 for each locus.
  -main_metafounder MAIN_METAFOUNDER
                      ID used to represent the base population of the pedigree
                      (metafounder / unknown parent group)
                      (see format details).
                      Default: MF_1.
  -rec_length REC_LENGTH
                      Recombination length of the chromosome in Morgans
                      (see map file).
                      Default: 1.00.
  -mutation_rate MUTATION_RATE
                      Mutation probability.
                      Default: 1e-8.
  -geno_error_prob GENO_ERROR_PROB
                      Genotype error probability.
                      Default: 0.0001.
  -seq_error_prob SEQ_ERROR_PROB
                      Sequence error probability.
                      Must not be 0.
                      Default: 0.001.
  -pheno_penetrance_prob_file
                      [PHENO_PENETRANCE_PROB_FILE ...]
                      Phenotype penetrance probability file
                      (see format details).

AlphaPeel requires a pedigree file (-ped_file) and one or more genomic data files to run the analysis.

AlphaPeel supports the following genomic data files: genotype file in the AlphaGenes format (-geno_file), sequence allele read count file in the AlphaGenes format (-seq_file), and binary Plink file (-plink_file).

When -x_chr is used the pedigree file and genotype file have specific requirements. Follow the links to respective file formats for more details.

AlphaPeel also supports phenotype files (-pheno_file) and corresponding phenotype penetrance files (-pheno_penetrance_prob_file). Both must be provided for work with phenotypes.

The input options in the form of -opt [XYZ ...] can accept more than one argument separated by spaces.

Use -start_snp and -stop_snp to run the analysis only on a subset of markers.

Note

We use interchangeably the terms “marker(s)”, “locus/loci”, “SNP(s)”, or “site(s)”, to refer to a specific position in the genome, where we typically observe polymorphism in the population.

AlphaPeel supports specifying a number of model parameters, which are probabilities of different events or outcomes: alternative allele probabilities in the base population(s) (-alt_allele_prob_file), recombination length of the chromosome (-rec_length),

mutation rate (-mutation_rate), genotype error probability (-geno_error_prob), sequence error probability (-seq_error_prob), and phenotype penetrance probabilities (-pheno_penetrance_prob_file).

Note

The accuracy of AlphaPeel results has been shown to be quite robust to deviations in most of the model parameters, so it might not be needed to change or estimate them from the input data; at least unless large deviations from the defaults are known or expected. Having said this, do explore what works best for your data and your aims!

Note

We use the term “probability” to also represent the commonly used terms “frequency” and “rate”, to refer to the same concept of a value between 0 and 1 that quantifies the likelihood or proportion of a certain event or outcome.

Output options

Individuals:
  -no_dosage            Suppress default output of allele dosages.
  -geno                 Call and output genotypes.
  -geno_threshold [GENO_THRESHOLD ...]
                        Genotype calling threshold(s) from the genotype probabilities.
                        Multiple space separated values allowed.
                        Value(s) less than 1/3 are replaced by 1/3.
                        Default: 1/3.
  -geno_prob            Output genotype probabilities.
  -phased_geno_prob     Output phased genotype probabilities.
  -hap                  Call and output haplotypes.
                        Default: 1/2.
  -hap_threshold [HAP_THRESHOLD ...]
                        Haplotype calling threshold(s) from the phased genotype probabilities
                        Multiple space separated values allowed.
                        Value(s) less than 1/2 are replaced by 1/2.
  -seg_prob             Output segregation probabilities.
  -pheno_prob           Output phenotype probabilities.

Prefix, order, and IO:
  -out_file PREFIX      The output file prefix. All file outputs will be named
                        as "PREFIX.OUTPUT.txt", where "OUTPUT" is the type of output
                        (for example, "dosage" and "geno_prob").
  -out_id_order OUT_ID_ORDER
                        Determines the order of individuals in the output
                        file based on their order in the
                        corresponding input file. Individuals not in the input
                        file are placed at the end of the file and sorted in
                        alphanumeric order. These individuals can be suppressed
                        with the -out_id_only option. Accepted arguments for
                        this option are: id, pedigree, genotypes, sequence, and
                        segregation.
                        Default: id.
  -out_id_only          Suppress output for individuals not present in
                        the file specified with -out_id_order. It also suppresses
                        "dummy" individuals.
  -n_io_thread N_IO_THREAD
                        Number of threads to use for input/output (IO).
                        Default: 1.

AlphaPeel by default produces a dosage file. Additional individual-level outputs can be requested with the options described above. The -geno_threshold and -hap_threshold respectively control which genotypes and haplotypes are called. A threshold of 0.9 gives calls only if the probability for one genotype (or haplotype allele) is higher than 0.9. When the probability is lower than the threshold, the output is set to value 9 (missing). Using a higher value will increase the accuracy of called genotypes (or haplotypes), but will result in fewer calls. Since there are three genotype states and two haplotype states, “best-guess” genotypes and haplotypes are respectively called with a threshold less than 1/3 and 1/2.

The output order of individuals can be changed using the -out_id_order option, with additional control provided with the -out_id_only option. The latter option is not recommended for hybrid peeling or any combination of different input files.

The option -n_io_thread controls the number of threads/processes used by AlphaPeel. AlphaPeel uses additional threads to parse and format input and output files. Setting this option to a value greater than 1 is only recommended for very large files (i.e. >10,000 individuals).

Peeling methods

Strategy:
  -method METHOD        Peeling method: single or multi.
                        Default: multi.

Single-locus options for the second stage of hybrid peeling:
  -seg_file SEG_FILE    Segregation probabilities file.
  -seg_map_file SEG_MAP_FILE
                        Map file for loci in the segregation probabilities file.

AlphaPeel supports three peeling strategies: single-locus, multi-locus, and hybrid.

Single-locus peeling method does not use linkage information between loci in iterative peeling. It is fast, but not very accurate.

Multi-locus peeling method runs multi-locus iterative peeling, which uses linkage information to increase accuracy and calculate segregation probabilities, but it is much slower than single-locus method.

Hybrid peeling is useful in settings with a SNP genotypes with a limited number of markers and a sequence allele read counts from a large number of loci. In this setting, you can first run the multi-locus peeling method on SNP genotypes to estimate segregation probabilities, and then run the single-locus peeling method on sequence allele read counts and the segregation probabilities. In this second stage of hybrid peeling, provide: a -map_file with positions for loci in the sequence allele read count data, a -seg_file with segregation probabilities generated via multi-locus method, and a -seg_map_file with genetic positions for loci in the segregation probabilities file. This combination of options is not required in the standard multi-locus mode.

Peeling parameters

Computational parameters:
  -n_cycle N_CYCLE      Number of peeling cycles.
                        Default: 5.
  -n_thread N_THREAD
                        Number of threads to use.
                        Default: 1.

Estimation of model parameters:
  -est_start_alt_allele_prob
                        Estimate starting alternative allele probabilities
                        from all inputted genomic data prior to peeling.
  -est_alt_allele_prob  Estimate alternative allele probabilities
                        after each peeling cycle.
  -est_geno_error_prob  Estimate genotype error probability
                        after each peeling cycle.
  -est_seq_error_prob   Estimate sequence error probability
                        after each peeling cycle.
  -est_pheno_penetrance_prob
                        Estimate phenotype penetrance probabilities
                        after each peeling cycle.
  -no_phase_founder     Phase a heterozygous allele in one of the
                        founders (if such an allele can be found).

Computational effort and speed of AlphaPeel can be controlled with the number of peeling cycles (-n_cycle, increasing the number will marginally increase accuracy, but also runtime) and the number of threads (-n_thread, to reduce runtime on large datasets).

AlphaPeel can estimate the model parameters from the input data. The default or user provided input values are used as a starting point for estimation. See a note on robustness of results to these parameters.

When estimation options are used, the respective parameters are estimated after each peeling cycle and output to a file at the end. This process usually increases running times and might require additional peeling cycles to converge. The estimates are based on inferred states of the modelled events and their match/mismatch between observed and inferred states.

Alternative allele probabilities are estimated (using -est_alt_allele_prob) as half of the mean of estimated allele dosage in the base population(s) (metafounders).

This estimation can be warm-started with a sample estimate from inputted genomic data (using -est_start_alt_allele_prob). Note that this sample estimate is not taking the pedigree structure into account, so it is a naive estimate and does not pertain to the pedigree base population(s) and hence ignores metafounders. Option -est_start_alt_allele_prob uses Newton optimisation, which also requires starting values. These starting values are by default 0.5, but can also be provided using -alt_allele_prob_file.

For a pedigree with multiple metafounders, there are three options to obtain metafounder-specific alternative allele probabilities: (1) use the default starting values of 0.5 for all loci and then -est_alt_allele_prob, (2) use -est_start_alt_allele_prob to use sample-based starting values and then -est_alt_allele_prob, or (3) provide starting values using -alt_allele_prob_file and then -est_alt_allele_prob. In all three cases, -est_alt_allele_prob is optional.

Error probabilities (using -est_geno_error_prob and -est_seq_error_prob) are estimated as the proportion of mismatches between observed and inferred states.

Phenotype penetrance probabilities (using -est_pheno_penetrance_prob) are estimated from the average conditional probabilities of phenotype states for each phased genotype across phenotyped individuals. This follows Kinghorn (2003) A simple method to detect a single gene that determines a categorical trait with incomplete penetrance. Assoc. Advmt. Anim. Breed. Genet. 15:103-106.

File formats

Input file formats

Pedigree file

This file has one line with recorded parents for each individual. The file(s) should include all individuals present in other files and their known relatives present only in pedigree. Each line of a pedigree file has three values, the individual’s ID, their father’s ID, and their mother’s ID. Unknown parent ID is encoded with 0. Individuals with one unknown parent are internally assigned a “dummy” parent. Therefore, all individuals have either both parents known or neither parent known. Individuals with two unknown parents are considered as founders and as such represent the base population of the pedigree. Internally, they are assigned to a metafounder (unknown parent group) MF_1 (or whatever is specified through -main_metafounder). Users can define multiple base populations (metafounders) as shown below. The IDs of these metafounders must start with MF_.

When working with the X chromosome, a fourth value is needed for individual’s sex: 0 for males and 1 for females.

Example with four individuals across two generations:

id1 0 0
id2 0 0
id3 id1 id2
id4 id1 id2

Example with two metafounders:

id1 MF_1 MF_1
id2 MF_2 MF_2
id3 id1 id2
id4 id1 id2

Example with sex information; id1 and id3 are males, while id2 and id4 are females:

id1 0 0 0
id2 0 0 1
id3 id1 id2 0
id4 id1 id2 1

Genotype file

This file has one line with observed genotypes for each genotyped individual. The file does not need to include all individuals present in other files. The first value in each line is the individual’s ID. The remaining values are observed genotypes at each locus. Only loci on one chromosome should be provided!

Note

AlphaPeel works with bi-allelic loci with two alleles; reference (major) allele a and alternative (minor) allele A. The terms major and minor indicates their frequency in a population, but this is not a requirement for AlphaPeel. These alleles are numerically encoded as 0 and 1, respectively. Combining two alleles in a diploid individual gives three possible genotypes: reference homozygote a/a, heterozygote a/A or A/a, and alternative homozygote A/A. When the origin of alleles that an individual inherited is known, we have four phased genotypes: aa, aA, Aa, and AA, where the paternal allele is listed first and the maternal allele is listed second. These genotypes are numerically encoded as 0, 1, and 2, respectively. Missing alleles and genotypes are numerically encoded as 9. The numerical codes are called allele dosages, because they represent the number (dose) of alternative alleles.

When working with the X chromosome: (1) heterogametic genotypes (for males in mammals (XY) and for females in birds (ZW)) should be coded as: 0 (reference allele a on the X chromosome of the XY genotype), 1 (alternative allele A on the X chromosome of the XY genotype), or 9 (missing) and (2) Homogametic genotypes (females in mammals (XX) and males in birds (ZZ)) should be coded as described above for autosomes (since they have the XX genotype).

Example with four individuals and their genotypes at four loci:

id1 0 2 9 0
id2 1 1 1 1
id3 2 0 2 0
id4 0 2 1 0

Example with four individuals and their X chromosome genotypes at four loci; id1 and id3 are males, while id2 and id4 are females:

id1 0 1 9 0
id2 1 1 1 1
id3 1 0 1 0
id4 0 2 1 0

Sequence allele read counts file

This file has two lines with observed allele read counts for each sequenced individual. The file does not need to include all individuals present in other files. The first line gives the individual’s ID and read counts for the reference allele at each locus. The second line gives the individual’s ID and allele read counts for the alternative allele at each locus.

The same format works for the autosomes and the X chromosome. Only loci on one chromosome should be provided!

Example with four individuals and their allele read counts at four loci:

id1 4 0 0 7 # Reference allele read counts for id1
id1 0 3 0 0 # Alternative allele read counts for id1
id2 1 3 4 3
id2 1 1 6 2
id3 0 3 0 1
id3 5 0 2 0
id4 2 0 6 7
id4 0 7 7 0

Phenotype file

This file has one or multiple lines with observed phenotypes for each phenotyped individual. Multiple lines per individual support repeated phenotyping. The file does not need to include all individuals present in other files. The first value in each line is the individual’s ID. The remaining values are the phenotypes of the individual for a specific trait, coded from 0 onwards. For example, a binary trait should be coded as 0 and 1, while a trait with three states should be coded as 0, 1, and 2 (current phenotype functionality works only with one locus and one trait).

Example with four individuals and their phenotypes for a binary trait:

id1 0
id2 1
id3 1
id4 0

Binary Plink file

This file is supported through the package AlphaPlinkPython, which can be installed via pip, but is only stable for Linux. There are known issues with this package, so we do not advocate its use at the moment. The pedigree supplied by the .fam file will be used if a pedigree file is not supplied. Otherwise, the pedigree file will be used and the .fam file will be ignored.

Map file

This file has one line with genome information for each locus. The file should include all loci present in other files. Each line of a map file has three values, the chromosome number, the locus name, and the physical position (in base-pairs). Only loci on one chromosome should be provided!

Example with four SNP loci on chromosome 1:

snp_a 12483939
snp_b 192152913
snp_c 65429279
snp_d 107421759

Output file formats

Dosage file

The .dosage.txt file contains expected dosages for the alternative allele for each individual. These expected dosages are obtained by (1) taking the allele dosages (0, 1, and 2) of each individual at each locus, (2) weighting them with corresponding genotype probabilities, and (3) summing the weighted dosages. There is one line per individual. The first value in each line is the individual ID. The remaining values are allele dosages at each locus. These values will be between 0 and 2, inclusive (see the note on encoding alleles and genotypes).

Example with four individuals and four loci:

id1 0.2089 1.7820 1.4725 0.0000
id2 1.0000 1.0000 1.0000 0.9999
id3 0.8293 1.1329 1.9999 0.0000
id4 0.0001 1.9999 1.0000 0.0000

Genotype file

The .geno_THRESHOLD.txt file contains called genotypes for each individual for each specified threshold (-geno_threshold THRESHOLD). There is one line per individual. The first value in each line is the individual ID. The remaining values are called genotypes at each locus, encoded as 0, 1, and 2, or 9 when the probability is to low to make the call (see the note on encoding alleles and genotypes).

Example with four individuals and four loci:

id1 0 2 1 0
id2 1 1 1 1
id3 1 1 2 0
id4 0 2 1 0

Genotype probability file

The .geno_prob.txt file contains genotype probabilities for each individual.

There are four lines per individual (an empty line and three lines with probabilities for aa, aA or Aa, and AA genotypes). The first value in each line is the individual ID. The remaining values are genotype probabilities at each locus.

Example with four individuals and four loci:

id1 0.7912 0.0000 0.0000 1.0000
id1 0.2088 0.2179 0.5274 0.0000
id1 0.0000 0.7820 0.4725 0.0000

id2 0.0000 0.0000 0.0000 0.0001
id2 1.0000 1.0000 1.0000 0.9999
id2 0.0000 0.0000 0.0000 0.0000

id3 0.3784 0.2171 0.0000 1.0000
id3 0.4140 0.4329 0.0001 0.0000
id3 0.2076 0.3500 0.9999 0.0000

id4 0.9999 0.0000 0.0000 1.0000
id4 0.0001 0.0001 0.9999 0.0000
id4 0.0000 0.9999 0.0000 0.0000

Phased genotype probability file

The .phased_geno_prob.txt file contains phased genotype probabilities for each individual.

There are five lines per individual (an empty line and four lines with probabilities for aa, aA, Aa, and AA phased genotypes). The first value in each line is the individual ID. The remaining values are phased genotype probabilities at each locus.

Example with four individuals and four loci:

id1 0.7912 0.0000 0.0000 1.0000
id1 0.1044 0.1090 0.2637 0.0000
id1 0.1044 0.1090 0.2637 0.0000
id1 0.0000 0.7820 0.4725 0.0000

id2 0.0000 0.0000 0.0000 0.0001
id2 0.3764 0.6611 0.0000 0.9628
id2 0.6236 0.3388 1.0000 0.0371
id2 0.0000 0.0000 0.0000 0.0000

id3 0.3784 0.2171 0.0000 1.0000
id3 0.4140 0.0000 0.0001 0.0000
id3 0.0000 0.4328 0.0000 0.0000
id3 0.2076 0.3500 0.9999 0.0000

id4 0.9999 0.0000 0.0000 1.0000
id4 0.0000 0.0000 0.2912 0.0000
id4 0.0000 0.0000 0.7088 0.0000
id4 0.0000 0.9999 0.0000 0.0000

Phase / haplotype file

The .hap_THRESHOLD.txt file contains called haplotypes for each individual. There are two lines per individual, one for each of the paternal and maternal haplotypes of the individual. The first value in each line is the individual ID. The remaining values are called alleles at each locus, encoded as 0 and 1, or 9 when the probability is to low to make the call (see the note on encoding alleles and genotypes). For individuals for whom the allele/haplotype of origin can be determined, the first line provides information on the paternal haplotype, and the second line provides information on the maternal haplotype.

Example with four individuals and four loci:

id1 0 1 1 0 # Paternal haplotype
id1 0 1 1 0 # Maternal haplotype
id2 1 0 1 0
id2 0 1 0 1
id3 0 1 1 0
id3 1 0 1 0
id4 0 1 1 0
id4 0 1 0 0

Segregation file

The .seg_prob.txt file contains segregation probabilities for each individual. There are four lines per individual, corresponding to the four possible patterns of segregation (inheritance):

The grand paternal allele from the father and the grand paternal allele from the mother: \(Pr(F_{p,-} \& M_{p,-})\),

The grand paternal allele from the father and the grand maternal allele from the mother: \(Pr(F_{p,-} \& M_{-,m})\),

The grand maternal allele from the father and the grand paternal allele from the mother: \(Pr(F_{-,m} \& M_{p,-})\), and

The grand maternal allele from the father and the grand maternal allele from the mother: \(Pr(F_{-,m} \& M_{-,m})\).

The symbols above mean the following: Pr() probability, F father, M mother, p paternal allele, m maternal allele, and - the allele that was not inherited.

The first value in each line is the individual ID. The remaining values are segregation probabilities at each locus.

Example with four individuals and four loci:

id1 0.2500 0.2500 0.2500 0.2500
id1 0.2500 0.2500 0.2500 0.2500
id1 0.2500 0.2500 0.2500 0.2500
id1 0.2500 0.2500 0.2500 0.2500
id2 0.2500 0.2500 0.2500 0.2500
id2 0.2500 0.2500 0.2500 0.2500
id2 0.2500 0.2500 0.2500 0.2500
id2 0.2500 0.2500 0.2500 0.2500
id3 0.3356 0.3894 0.5000 0.4390
id3 0.1644 0.1106 0.0000 0.0610
id3 0.3356 0.3894 0.5000 0.4390
id3 0.1644 0.1106 0.0000 0.0610
id4 0.2046 0.1953 0.2760 0.3914
id4 0.2954 0.3047 0.2240 0.1086
id4 0.2046 0.1953 0.2760 0.3914
id4 0.2954 0.3047 0.2240 0.1086

Phenotype probability file

The .pheno_prob.txt file contains phenotype probabilities for each individual.

There are 1+k lines per individual (an empty line and k lines with probabilities for 0:k phenotypes). The first value in each line is the individual ID. The remaining values are phenotype probabilities (current phenotype functionality works only with one locus and one trait).

Example with four individuals and two phenotype states for a binary trait:

id1 0.9000
id1 0.1000

id2 0.9000
id2 0.1000

id3 0.2453
id3 0.7547

id4 0.9000
id4 0.1000

Parameter file formats

Alternative allele probability file

The .alt_allele_prob.txt file contains alternative allele probabilities for each base population (metafounder) and each locus. There is one line per locus, with one optional top/header line. The header contains the metafounder ID(s), which can be skipped when there is just one metafounder / no metafounders. The remaining lines contain the metafounder-specific alternative allele probabilities for each locus. The file should include all metafounders present in pedigrees. Any missing values, or whole metafounder columns, default to 0.5 for all loci. If you do not have information for some loci, provide 0.5 for those loci. The file format is identical whether inputted via -alt_allele_prob_file or outputted from estimation using -est_start_alt_allele_prob or -est_alt_allele_prob.

Example with no metafounder and four loci:

Example with two metafounders and four loci:

MF_1      MF_2
468005  0.390000
195520  0.219890
733061  0.509849
145847  0.090000

Genotype error probability file

The .geno_error_prob.txt file contains genotype error probabilities for each locus. There is one line per locus with one value.

Example with four loci:

Sequence error probability file

The .seq_error_prob.txt file contains sequence error probabilities for each locus. There is one line per locus with one value.

Example with four loci:

Phenotype penetrance probability file

This .pheno_penetrance_prob.txt file contains phenotype penetrance probabilities for each distinct genotype impacting a phenotype. These probabilities encode the relationship between genotypes and phenotypes. The file should include all phenotypes present in phenotype files (current functionality works only with one locus and one trait). There are four lines per locus, containing conditional probabilities of all phenotypes for a given phased genotype, including phenotyping errors or other deviations. Each column represents a different phenotype state (ordered from 0 to the total number of states), and each row represents the phased genotypes (aa, aA, Aa, and AA). That is, the values within a row form a conditional probability distribution of phenotypes for the corresponding phased genotype.

Example for a monogenic recessive binary trait with 10% phenotyping error: