male-pedigree-toolbox 0.1.2

Meiotic distances in pedigrees (distance)

Calculate distances between all individuals in the provided pedigrees. The pedigrees need to be in Trivial Graph Format (tgf). The command can calculate the distances between all individuals in a pedigree.

Example command:

$ mpt distances -i tgf_folder -o pairwise_distances.csv

This will create a comma separated values (csv) file containing the generational distance between all individuals of each pedigree.

Counting mutations between alleles of markers (mut_diff)

Get the number of mutations between all alleles for all markers in pedigrees. The input for this command is an alleles file. This is a .csv file that contains the alleles for each marker of one or more pedigrees. An Example of an alleles filecan be found at examples/example_alleles.csv. The number of alleles does not have to be 6. Optionally the distances between all individuals of the different pedigrees can be provided (this can be generated with the distance command).

Example command:

$ mpt mut_diff -af allele_file.csv -df optional_distance_file.csv -fo full_output_file.csv -so summarized_output_file.csv -do meiotic_mutation_rates.csv

This always results in at least 2 files. Firstly, a full output file containing the number of mutations that occured between all individuals of a pedigree for all markers for each allele. Secondly, a summary output file that takes the mutations for all markers together and shows the number of mutations between all individuals of a pedigree. If a distance file was specified then percentage of mutation is calculated for each number of meiosis present in the provided pedigrees.

Infering pedigree mutation events (ped_mut_graph)

Infer alleles and mutation events for pedigrees containing individuals with unknown alleles. The input for this command is an alleles file (for an example see the mut_diff description) and a folder containing pedigrees in .tgf format.

Example command:

$ mpt ped_mut_graph -af allele_file.csv -t tgf_folder -o output_folder

This will generate a pedigree for each marker containing the number of mutations that occured between descendants in the pedigree. It will also contain an overview graph for each pedigreewhere all unique sets of alleles get their own color. Each pedigree also gets a file with mutation rates for each marker based on that pedigree. Finally, a file that summarizes all these mutation rates for all pedigrees is also generated.

Example of a pedigree for a certain marker with inferred mutation locations. The number at the edge indicates the number of mutations the color indicates where this mutation could have occured, since these mutations are annotated at the first place that they could have occured.

Example of the same pedigree for all markers. Here Each unique allele gets a unique color. A .csv file acompanies this file giving information on what marker mutated on what edge. All edges where mutations occured have an id together with the number of mutations that occured. Keep in mind that these mutations are placed at the first edge they could have occured.

Clustering alleles based on mutation distance (draw_pedigrees)

Identify likely related individuals based on the mutation distance of the alleles of measured markers. The input for this functionality is full list of mutation distances between all markers for all alleles (this can be generated with the mut_diff command). . For an example of a mutation rates file see examples/example_marker_rates.csv. Additionally, for more accurate results you can also provide the mutation rates for all markers in a separate file. You can either define the number of clusters yourself or let the program calculate the optimal number using silhouette score to measure how good the clustering is.

Example command:

$ mpt draw_pedigrees -fm full_mutation_distances.csv -mr marker_mutation_rates_file.csv -o output_folder -t both

This will produce a dendrogram or multi-dimensional scaling (MDS) plot or both for each pedigree present in the full mutation distances file. Besides that text files are provided that contain the clusters, in order to easily work with get all the individuals of a certain cluster.

Run all the above commands in tandem (all)

There is a command to run all the above functionalities in order where files created from one command are used as inputs for others. This requires at the minimum a folder with .tgf files and an alleles file to run.

Example command:

$ mpt all -af allele_file.csv -t tgf_folder -o output_folder

Simulate alleles data (simulate) (command line only)

Simulate data for creating classification models based on mutation rates of markers. These mutation rates can be obtained from ped_mut_graph or calculated yourself. For an example of a mutation rates file see examples/example_marker_rates.csv. This command generates data for the make_models command in order to have a sufficiently large dataset to create the models from. You can specify the number of generations and the number of inidividuals per generation that you want to simulate. Each generation is simulated independant from previous generations.

Example command:

$ mpt simulate -i marker_rate_file.csv -o simulated_mutations.csv -n 10000 -g 50

This will generate one file containing the simulated mutations for each marker of each individual over all generations. We recommend generating for at least 10.000 individuals per generation. An example of the simulated data can be found at examples/example_simulated.csv.

Create classification models from simulated data (make_models) (command line only)

Create classification models that predict a generational distance between 2 individuals of 1 till the number of simulated generations. There are a number of different models that can be chosen from. From our experience the best performing models are the multi-layer perceptron, support vector machines (SVM, scale very badly with large datasets) and linear discriminant analysis (LDA). Depending on the model this can run for quite a while. It is also advised to a large number of cores if available to speed up the calculations.

Example command:

$ mpt make_models -i simulated_data.csv -o output_folder -mt MDS LDA -c -1

This will create a pickled RandomizedSearchCV object containing the model. These can be used by the final component of these comands to predict the generational distance between individuals.

Predict generational distance (predict)

Allows to predict the generational distance between one or more individuals based on the number of mutations between a sets of markers. There are a number of pre-computed models that can be used for a few standard sets of markers. The following marker sets have pre-computed models:

• RMPLEX

• PPY23

• YFP

• PPY23 + RMPLEX

• YFP + RMPLEX

The input file can be generated from an alleles file with the help of the mut_diff command. The file should look the same as the examples/example_simulated.csv.

Example command:

$ mpt predict -i marker_mutation_observations.csv -o output_folder -m model_file.joblib -tf simulated_data.csv