Python API#

mrpast.result.draw_graphs(model_file: str, ax, grid_cols: int | None = None, epoch_spacing: float = 0.5, epoch_label_spacing: float | None = 0.15, max_node_size: int = 800, migrate_color: str | None = None, popsize_color: str | None = None, x_offset: float = 0.25, coal_values: List[float] | None = None, mig_values: List[float] | None = None, cax=None, cmap=None, min_max_migrate: Tuple[float, float] | None = None)#

Draw the topology of the given input mrpast model file on the given matplotlib axis.

Parameters:

  • model_file – The mrpast model filename.

  • ax – The matplotlib axis object.

  • grid_cols – Default is None. When set to an integer, layout the graphs in a grid with the given number of columns. For example, if you have a 6-deme model then you might want to set grid_cols=2 or grid_cols=3 to lay the graph out as 3x2 or 2x3.

  • epoch_spacing – Spacing between each epoch in the figure.

  • epoch_label_spacing – Spacing between the epoch label and the epoch graph. Set to None to disable epoch labels.

  • max_node_size – The maximum size that a particular node can be.

  • migrate_color – The color to use for migration edges. By default, a spectrum of colors is used which indicates a higher (darker color) or lower (lighter color) rate.

  • popsize_color – The color to use for deme nodes. By default, the matplotlib.pyplot.cm.Dark2 colormap is used.

  • x_offset – The offset from the X-axis to start drawing.

  • coal_values – If non-None, use this list of coalescence rate values instead of the ground-truth values from the model. This only works if the model has densely packed parameters, with no parameter index gaps.

  • mig_values – If non-None, use this list of migration rate values instead of the ground-truth values from the model. This only works if the model has densely packed parameters, with no parameter index gaps.

  • min_max_migrate – Optional tuple of (min, max) float values, which are the minimum and maximum possible migration rate values for the purposes of coloring the edges.

mrpast.result.load_json_pandas(filename: str, interval_field: str | None = None, skip_fixed: bool = True) → DataFrame#

Load a solver output JSON file as a Pandas DataFrame.

Parameters:

  • filename – The JSON filename.

  • interval_field – Optionally, the name of a field in the JSON file (on each parameter) to use for computing the parameter confidence intervals. Typically this is “gim_ci”, which is present on an output file if the “mrpast confidence” command was used to generate the JSON.

  • skip_fixed – Set to False to keep the fixed values that were part of the solution, otherwise only the parameters will be returned.

Returns:

Pandas DataDrame, where coalescent rates have been converted into effective population sizes (Ne).

mrpast.result.summarize_bootstrap_data(bootstrap_df: DataFrame, use_median: bool = True, interval_conf: float = 0.95, use_percentile: bool = False) → DataFrame#

Given a Pandas DataFrame loaded from a bootstrap CSV file, produce a new DataFrame that summarizes the data. Confidence intervals are calculated, and the resulting parameter estimates are the mean (or median) of the value over all bootstrap samples.

Parameters:

  • bootstrap_df – A DataFrame as loaded via pandas.read_csv() with the CSV that is generated by “mrpast confidence –bootstrap”.

  • use_median – Set to False if you want to use the mean instead of the median for summarizing parameter values over all bootstrap samples. The median is more robust to parameter estimates that hit the lower or upper bounds during maximum likelihood estimation.

  • interval_conf – Defaults to 0.95. Set to one of 0.99, 0.95, 0.9, 0.75 or 1.0. 1.0 means use the entire range of the bootstrap values instead of the standard deviation plus a confidence interval. The other values are the confidence for the normal distribution confidence intervals based on sample standard deviation.

  • use_percentile – Instead of computing the sample stddev, just use the percentile from the bootstraps for each parameter.

Returns:

DataFrame with one row per parameter, summarizing the value and confidence interval.

mrpast.result.tab_show(filename: str, sort_by: str = 'Index', show_popsize: bool = False, bound_column: bool = False)#

Print an ASCII table showing the parameter values and their error from ground truth, for the given JSON output from the solver.

mrpast.arginfer.attach_populations_ts(tree_seq: TreeSequence, pop_map: PopMap, ploidy: int = 2) → TreeSequence#

Update the given tree-sequence file with the population information. There are two “types” of tree-sequences:

  • Ones made via Relate or SINGER. These have the individual order such that the sample nodes (0, 1) are for individual 0, (2, 3) are for individual 1, etc. There is no “individual table” in the tree file.

  • Ones made via tsinfer. These have an individual table, and assume the order of individuals matches the original order in the .vcz data.

Parameters:

  • tree_seq – The tree-sequence.

  • pop_map – A PopMap object describing individuals and their populations.

  • ploidy – Default value of 2. The ploidy of the individuals.

class mrpast.model.PopMap(mapping: List[List[int]], names: List[str])#

Maps populations to the individuals contained within, and the names of the populations.