Python API

Python API#

This page provides detailed documentation for the methods and classes available in pyslim. Here is a quick reference to some of the methods:

`add_mutation_metadata`(ts[, mutation_type, ...])	Returns a new tree sequence with default information added to the top-level metadata for each mutation in the tree sequence that does not already have this information.
`add_mutation_metadata_tables`(tables[, ...])	Does the work of `add_mutation_metadata()`, modifying `tables` in place.
`annotate`(ts, model_type, tick[, cycle, ...])	Takes a tree sequence (as produced by msprime, for instance), and adds in the information necessary for SLiM to use it as an initial state, filling in mostly default values.
`convert_alleles`(ts)	Returns a modified tree sequence in which alleles have been replaced by their corresponding nucleotides.
`default_slim_metadata`(name[, ...])	Returns default metadata of type `name`, where `name` is one of "tree_sequence", "edge", "site", "mutation", "mutation_list_entry", "node", "individual", or "population".
`generate_nucleotides`(ts[, ...])	Returns a modified tree sequence in which mutations have been randomly assigned nucleotides and (optionally) a reference sequence has been randomly generated.
`has_vacant_samples`(ts[, ts_metadata])	Returns whether the tree sequence has vacant sample nodes.
`individual_ages`(ts[, ts_metadata])	Returns the ages of all individuals in the tree sequence, as extracted from metadata.
`individual_ages_at`(ts, time[, stage, ...])	Returns the ages of each individual at the corresponding time ago, which will be `nan` if the individual is either not born yet or dead.
`individuals_alive_at`(ts, time[, stage, ...])	Returns an array giving the IDs of all individuals that are known to be alive at the given time ago.
`mutation_metadata`(ts[, check, ts_metadata])	Returns a dictionary whose keys are the numeric SLiM IDs of mutations, and whose values are metadata entries for those mutations.
`next_slim_mutation_id`(ts)	Returns the next unused SLiM mutation ID for this tree sequence.
`nodes_vacant`(ts)	Evaluates which nodes in the tree sequence are vacant: returns a boolean vector whose k-th element is True if the k-th node is labelled as vacant in the node's metadata recorded by SLiM.
`population_size`(ts, x_bins, y_bins, time_bins)	Calculates the population size in each of the spatial bins defined by grid lines at `x_bins` and `y_bins`, averaged over each of the ticks in the time intervals separated by `time_bins`.
`recapitate`(ts[, ancestral_Ne, keep_vacant])	Returns a "recapitated" tree sequence, by using msprime to run a coalescent simulation from the "top" of this tree sequence, i.e., allowing any uncoalesced lineages to coalesce.
`remove_vacant`(ts[, ts_metadata])	Remove sample flags from all vacant nodes.
`restore_vacant`(ts[, ts_metadata])	The inverse of `remove_vacant()`.
`set_slim_state`(ts[, time, individuals])	Returns a new tree sequence for which the information stored in metadata has been changed so that when loaded into SLiM, the current time will be `time` units ago (i.e., at tskit time `time`) and the alive individuals will be `individuals`.
`slim_time`(ts, time[, stage, ts_metadata])	Converts the given "tskit times" (i.e., in units of time before the end of the simulation) to SLiM times (those recorded by SLiM, usually in units of ticks since the start of the simulation).
`update`(ts)	Update a tree sequence produced by a previous version of SLiM to the current file version.

Editing or adding to tree sequences#

pyslim provides tools for transforming tree sequences:

pyslim.recapitate(ts, ancestral_Ne=None, *, keep_vacant=False, **kwargs)[source]#

Returns a “recapitated” tree sequence, by using msprime to run a coalescent simulation from the “top” of this tree sequence, i.e., allowing any uncoalesced lineages to coalesce.

To allow recapitation to be done correctly, the nodes of the first generation of the SLiM simulation from whom all samples inherit are still present in the tree sequence, but are not marked as samples. If you simplify the tree sequence before recapitating you must ensure these are not removed, which you do by passing the argument keep_input_roots=True to simplify.

If you specify an ancestral_Ne, then the recapitated portion of the tree sequence will be simulated in a single population with this (diploid) size. In other words, all lineages are moved to a single population of this size (named “ancestral” if this name is not already taken), and coalescence is allowed to happen.

You may control the ancestral demography by passing in a demography argument: see msprime.sim_ancestry().

In general, all defaults are whatever the defaults of msprime.sim_ancestry() are; this includes recombination rate, so that if neither recombination_rate or a recombination_map are provided, there will be no recombination.

Sample flags from vacant nodes will be removed before recapitating: see remove_vacant(). To restore these, use keep_vacant=True. You only need to do this if some individuals are not diploid and you will be loading the tree sequence back into SLiM.

Precisely, this function will: (1) remove_vacant() nodes, if any; (2) create a demography in which all populations split from a new population called “ancestral” of the desired size; (3) simulate with msprime.sim_ancestry(); and (4) restore_vacant() nodes, if any.

Parameters:

ts (tskit.TreeSequence) – The tree sequence to transform.
ancestral_Ne (float) – If specified, then will simulate from a single ancestral population of this size. It is an error to specify this as well as demography.
keep_vacant (bool) – Whether to restore the sample flags on any vacant sample nodes. Default: False.
kwargs (dict) – Any other arguments to msprime.sim_ancestry().

Return tskit.TreeSequence:

A copy of the tree sequence with additional ancestral history added.

pyslim.convert_alleles(ts)[source]#

Returns a modified tree sequence in which alleles have been replaced by their corresponding nucleotides. For sites, SLiM-produced tree sequences have “” (the empty string) for the ancestral state at each site; this method will replace this with the corresponding nucleotide from the reference sequence. For mutations, SLiM records the ‘derived state’ as a SLiM mutation ID; this method will replace this with the nucleotide from the mutation’s metadata.

This operation is not reversible: since SLiM mutation IDs are lost, the tree sequence will not be able to be read back into SLiM.

The main purpose of this method is for output: for instance, this code will produce a VCF file with nucleotide alleles:

nts = pyslim.convert_alleles(ts)
with open('nucs.vcf', 'w') as f:
    nts.write_vcf(f)

This method will produce an error if the tree sequence does not have a valid reference sequence or if any mutations do not have nucleotides: to first generate these, see generate_nucleotides().

Parameters:: ts (tskit.TreeSequence) – The tree sequence to transform.
Return tskit.TreeSequence:: A copy of the tree sequence with modified ancestral and derived states.

pyslim.generate_nucleotides(ts, reference_sequence=None, keep=True, seed=None)[source]#

Returns a modified tree sequence in which mutations have been randomly assigned nucleotides and (optionally) a reference sequence has been randomly generated.

If reference_sequence is a string of nucleotides (A, C, G, and T) of length equal to the sequence length, this is used for the reference sequence. If no reference sequence is given, the reference_sequence property of ts is used if present; if not then a sequence of independent and uniformly random nucleotides is generated.

SLiM stores the nucleotide as an integer in the mutation metadata, with -1 meaning “not a nucleotide mutation”. This method assigns nucleotides by stepping through each mutation and picking a random nucleotide uniformly out of the three possible nucleotides that differ from the parental state (i.e., the derived state of the parental mutation, or the ancestral state if the mutation has no parent). If keep=True (the default), the mutations that already have a nucleotide (i.e., an integer 0-3 in metadata) will not be modified.

Technical note: in the case of stacked mutations, the SLiM mutation that determines the nucleotide state of the (tskit) mutation is the one with the largest slim_time attribute. This method tries to assign nucleotides so that each mutation differs from the previous state, but this is not always possible in certain unlikely cases.

Parameters:

ts (tskit.TreeSequence) – The tree sequence to transform.
reference_sequence (bool) – A reference sequence, or None to use an existing reference, or to randomly generate one.
keep (bool) – Whether to leave existing nucleotides in mutations that already have one.
seed (int) – The random seed for generating new alleles.

Return tskit.TreeSequence:

A copy of the tree sequence with nucleotides.

pyslim.update(ts)[source]#

Update a tree sequence produced by a previous version of SLiM to the current file version.

Return TreeSequence:: The updated tree sequence.

pyslim.remove_vacant(ts, ts_metadata=None)[source]#

Remove sample flags from all vacant nodes.

In SLiM’s internal state, there are two nodes per individual, even on chromosomes for which the individual is not diploid. Thus, some sample nodes may be placeholders, not actually representing physical haplosomes, and are called “vacant” nodes. In the tree sequence these nodes have no ancestry, and thus have ‘missing’ data; however, their presence can cause problems with methods not designed for missing data.

This method returns a copy of the tree sequence for which all vacant nodes have the sample flag removed; these nodes will thus not affect recapitate(), tree sequence statistics, etc. This also sets the NODE_IS_VACANT_SAMPLE flag on these nodes, so they can be restored with restore_vacant(). You probably don’t want to run this method again on the output, since these flags will be overwritten and restore_vacant() will no longer work as expected.

Parameters:

ts (tskit.TreeSequence) – The tree sequence.
ts_metadata (dict) – Optionally, the top-level metadata for ts. If this does not match the actual top-level metadata, incorrect values may result.

Return tskit.TreeSequence:

A copy of the tree sequence with vacant nodes not marked as samples.

pyslim.restore_vacant(ts, ts_metadata=None)[source]#

The inverse of remove_vacant().

This method returns a copy of the tree sequence for which all nodes with the NODE_IS_VACANT_SAMPLE flag set have their sample flags set also and the NODE_IS_VACANT_SAMPLE removed. If these nodes are not vacant, an error will be raised.

Parameters:

ts (tskit.TreeSequence) – The tree sequence.
ts_metadata (dict) – Optionally, the top-level metadata for ts. If this does not match the actual top-level metadata, incorrect values may result.

Return tskit.TreeSequence:

A copy of the tree sequence with vacant nodes marked as samples.

pyslim.set_slim_state(ts, time=0, individuals=None)[source]#

Returns a new tree sequence for which the information stored in metadata has been changed so that when loaded into SLiM, the current time will be time units ago (i.e., at tskit time time) and the alive individuals will be individuals. The time in SLiM (i.e., the value of the tick counter) will also be time units earlier.

This is useful, for instance, if you Remember a set of individuals at some point partway through a SLiM simulation, and would like to load those individuals into SLiM, rather than the final generation. (These could be used to start a new simulation, for instance.)

Appropriate individuals might be found, for instance, with pyslim.individuals_alive_at(ts, time).

To do this, the “tick” in top-level metadata is changed; individual flags are reset so that only individuals have the INDIVIDUAL_ALIVE flag set; and tskit times have time subtracted from them (so they measure time ago relative to the new tick).

As a result, some individuals in the tree sequence may have negative times, i.e., have lived “in the future”. Since these individuals will not be “alive”, they will be ignored by SLiM, even when their birth times arrive, so that any future history will also be present, unchanged, in the tree sequence that results from additional simulation. If additional simulation is performed then contradictions may arise: for instance, if one of the individuals had offspring for an additional ten ticks past time in the original simulation, but in the new simulation they die immediately, then the resulting tree sequence will still be valid but the history as recorded by SLiM in metadata will not make sense. To avoid such issues, one can in the original SLiM script Remember and then immediately kill the individuals to be later used in this way.

This also subtracts time from the value of “cycle” in top-level metadata; if this is not desired (or the value in “tick” needs to be adjusted), change the metadata directly.

Parameters:

ts (tskit.TreeSequence) – A SLiM-compatible TreeSequence.
time (int) – The number of time units (ticks) into the past to shift times. (Default: zero; can be positive or negative.)
individuals (numpy.ndarray) – An array of the tskit IDs of the individuals that should be marked as alive (all others will be not alive). (Default: leave unchanged.)

Return tskit.TreeSequence:

A copy of the tree sequence, modified.

pyslim.add_mutation_metadata(ts, mutation_type=0, remove_unused=False)[source]#

Returns a new tree sequence with default information added to the top-level metadata for each mutation in the tree sequence that does not already have this information. To do this, mutations must be in SLiM format, as for instance produced by msprime.SLiMv6MutationModel. Any information about SLiM mutations already in top-level metadata will remain unchanged.

To do this, this method looks for all SLiM IDs that are found in the derived state of some mutation but are not represented in the top-level metadata (see mutation_metadata()). This function then adds entries to that top-level metadata with default values (see default_slim_metadata()), except that (a) the mutation_type can be specified; and (b) the slim_time is set using the tick value in top-level metadata and the time of the oldest tskit mutation in which the SLiM mutation occurs.

Parameters:

ts (tskit.TreeSequence) – The tree sequence to transform.
mutation_type (int) – The numeric ID of the mutation type in SLiM.
remove_unused (bool) – Whether to also remove from metadata information about any mutations not seen in the derived states of the tree sequence.

Return tskit.TreeSequence:

A copy of the tree sequence with mutation information in metadata.

pyslim.add_mutation_metadata_tables(tables, mutation_type=0, remove_unused=False)[source]#

Does the work of add_mutation_metadata(), modifying tables in place.

Parameters:

tables (tskit.TableCollection) – The table collection to be modified.
mutation_type (int) – The numeric ID of the mutation type in SLiM.
remove_unused (bool) – Whether to also remove from metadata information about any mutations not seen in the derived states of the tree sequence.

Summarizing tree sequences#

Additionally, pyslim contains the following methods:

pyslim.individuals_alive_at(ts, time, stage='late', remembered_stage=None, population=None, samples_only=False, ts_metadata=None)[source]#

Returns an array giving the IDs of all individuals that are known to be alive at the given time ago. This is determined using their birth time ago (given by their time attribute) and, for nonWF models, their age attribute (which is equal to their age at the last time they were Remembered). See also individual_ages_at().

In WF models, birth occurs after “early()”, so that individuals are only alive during “late()” for the time step when they have age zero, while in nonWF models, birth occurs before “early()”, so they are alive for both stages.

In both the WF and nonWF life cycles, mortality occurs between “early()” and “late()”, so that individuals are last alive during the “early()” stage of the time step of their final age, and if individuals are alive during “late()” they will also be alive during “first()” and “early()” of the next time step (unless the user calls killIndividuals()). This means it is important to know during which stage individuals were Remembered - for instance, if the call to sim.treeSeqRememberIndividuals() was made during “early()” of a given time step, then those individuals might not have survived until “late()” of that time step. Since SLiM does not record the stage at which individuals were Remembered, you can specify this by setting remembered_stages: it should be the stage during which all calls to sim.treeSeqRememberIndividuals(), as well as to sim.treeSeqOutput(), were made.

Note also that in nonWF models, birth occurs between “first()” and “early()”, so the possible parents in a given time step are those that are alive in “early()” and have age greater than zero, or, equivalently, are alive in “late()” during the previous time step. In WF models, birth occurs after “early()”, so possible parents in a given time step are those that are alive during “early()” of that time step or are alive during “late()” of the previous time step.

Since individuals may be created not during the usual ‘birth’ stage by addSubPop( ), and the stage at which they are created is not stored, results may be unreliable for the first-generation individuals.

Parameters:

ts (tskit.TreeSequence) – A tree sequence.
time (float) – The number of ticks (i.e., time steps) ago.
stage (str) – The stage in the SLiM life cycle that we are inquiring about (either “first”, “early” or “late”; defaults to “late”).
remembered_stage (str) – The stage in the SLiM life cycle during which individuals were Remembered (defaults to the stage the tree sequence was recorded at, stored in metadata).
population (int) – If given, return only individuals in the population(s) with these population ID(s).
samples_only (bool) – Whether to return only individuals who have at least one node marked as samples.
ts_metadata (dict) – Optionally, the top-level metadata for ts. If this does not match the actual top-level metadata, incorrect values may result.

pyslim.individual_ages(ts, ts_metadata=None)[source]#

Returns the ages of all individuals in the tree sequence, as extracted from metadata. The result is an array of length equal to the number of individuals, with k-th entry equal to ts.individual(k).metadata["age"].

These are the ages of the indivdiuals when they were recorded in the tree sequence: either when the tree sequence was saved (if they are alive) or when they were last Remembered. See also individual_ages_at().

Parameters:

ts (tskit.TreeSequence) – The tree sequence.
ts_metadata (dict) – Optionally, the top-level metadata for ts. If this does not match the actual top-level metadata, incorrect values may result.

Returns:

An array of ages of individuals.

pyslim.individual_ages_at(ts, time, stage='late', remembered_stage='late', ts_metadata=None)[source]#

Returns the ages of each individual at the corresponding time ago, which will be nan if the individual is either not born yet or dead. This is computed as the time ago the individual was born (found by the time associated with the the individual’s nodes) minus the time argument; while “death” is inferred from the individual’s age, recorded in metadata (see individual_ages()). These values should be the same as what would be shown in SLiM during the corresponding time step and stage.

Since age increments at the end of each time step, the age is the number of time steps ends the individual has lived through, so if they were born in time step time, then their age will be zero.

In a WF model, this method does not provide any more information than does individuals_alive_at(), but for consistency, non-nan ages will be 0 in “late” and 1 in “first” and “early”. See individuals_alive_at() for further discussion.

Parameters:

ts (tskit.TreeSequence) – A tree sequence.
time (float) – The reference time ago.
stage (str) – The stage in the SLiM life cycle used to determine who is alive (either “early” or “late”; defaults to “late”).
remembered_stage (str) – The stage in the SLiM life cycle during which individuals were Remembered.
ts_metadata (dict) – Optionally, the top-level metadata for ts. If this does not match the actual top-level metadata, incorrect values may result.

pyslim.individual_parents(ts)[source]#

DEPRECATED: now SLiM records parents directly in the individual table (see for instance ind.parents).

Finds all parent-child relationships in the tree sequence (as far as we can tell). The output will be a two-column array with row [i,j] indicating that individual i is a parent of individual j. See has_individual_parents() for exactly which parents are returned.

See individuals_alive_at() for further discussion about how this is determined based on when the individuals were Remembered.

Parameters:: ts (tskit.TreeSequence) – A tskit.TreeSequence.
Returns:: An array of individual IDs, with row [i, j] if individual i is a parent of individual j.

pyslim.has_individual_parents(ts)[source]#

DEPRECATED: now SLiM records parents directly in the individual table (see for instance ind.parents).

Finds which individuals have both their parent individuals also present in the tree sequence, as far as we can tell. To do this, we return a boolean array with True for those individuals for which:

all edges terminating in that individual’s nodes are in individuals,
each of the individual’s nodes inherit from a single individual only,
those parental individuals were alive when the individual was born,
the parental individuals account for two whole genomes.

This returns a boolean array indicating for each individual whether all these are true. Note in particular that individuals with only one recorded parent are not counted as “having parents”.

See individuals_alive_at() for further discussion about how this is determined based on when the individuals were Remembered.

Parameters:: ts (tskit.TreeSequence) – A tskit.TreeSequence.
Returns:: A boolean array of length equal to targets.

pyslim.population_size(ts, x_bins, y_bins, time_bins, stage='late', remembered_stage=None)[source]#

Calculates the population size in each of the spatial bins defined by grid lines at x_bins and y_bins, averaged over each of the ticks in the time intervals separated by time_bins. To obtain actual (census) sizes, the tree sequence must contain all individuals alive, e.g., from a SLiM simulation with all individuals permanently remembered.

With nx, ny and nt the number of bins in the x, y and time directions (so, nx is one less than the length of x_bins), returns a 3-d array with dimensions (nx, ny, nt). The (i,j,k)``th element of the array is the average number of individuals with ``x coordinate in the half-open interval [x_bins[i], x_bins[i + 1]) and y coordinate in the half-open interval [y_bins[i], y_bins[i + 1]), averaged across all times in the half-open interval [time_bins[k], time_bins[k + 1]).

For integer endpoints of the time bins, this average is equivalent to recording the number of indivduals that are alive at each time in the time interval and have location in the relevant location bin, then taking the mean of these recorded population sizes.

Parameters:

ts (tskit.TreeSequence) – The tree sequence to calculate population size from.
x_bins (numpy.ndarray) – The x-coordinates of the boundaries of the location bins.
y_bins (numpy.ndarray) – The y-coordinates of the boundaries of the location bins.
time_bins (numpy.ndarray) – The endpoints of the time bins.
stage (str) – The stage in the SLiM life cycle that the endpoints of the time bins refer to (either “early” or “late”; defaults to “late”).
remembered_stage (str) – The stage in the SLiM life cycle during which individuals were Remembered (defaults to the stage the tree sequence was recorded at, stored in metadata).

Utilities#

pyslim.mutation_metadata(ts, check=True, ts_metadata=None)[source]#

Returns a dictionary whose keys are the numeric SLiM IDs of mutations, and whose values are metadata entries for those mutations. These SLiM IDs are found in the metadata of tskit mutations: for each mutation mut, as mut.metadata["derived_states"].

This is a simple extraction function that places the list of metadata entries stored in ts.metadata["SLiM_mutation_list"] in a dictionary indexed by SLiM ID. It is recommended to extract this information once and use the result in script, because calling this function many times (or, even just referring to ts.metadata many times) can slow down scripts considerably.

SLiM mutation IDs may also be present in mut.derived_state as a comma-separated string, but accessing these from metadata is preferred because the derived state may be changed (by {func}`.convert_alleles`).

Parameters:

ts (tskit.TreeSequence) – The tree sequence.
check (bool) – Whether to verify that all mutations are described in top-level metadata.
ts_metadata (dict) – Optionally, the top-level metadata for ts. If this does not match the actual top-level metadata, incorrect values may result.

Returns dict:

A dictionary of metadata entries, indexed by SLiM ID and in sorted order by SLiM ID.

pyslim.slim_time(ts, time, stage='late', ts_metadata=None)[source]#

Converts the given “tskit times” (i.e., in units of time before the end of the simulation) to SLiM times (those recorded by SLiM, usually in units of ticks since the start of the simulation). Although times in SLiM are always integers, the returned values will not be integers if the values in time are not.

When the tree sequence is written out, SLiM records the current current tick in the metadata: ts.metadata['SLiM']['tick']. In most cases, the “SLiM time” referred to by a time ago in the tree sequence (i.e., the value that would be reported by community.tick within SLiM at the point in time thus referenced) can be obtained by subtracting that time ago from ts.metadata['SLiM']['tick']. However, in WF models, birth happens between the “early()” and “late()” stages, so if the tree sequence was written out using sim.treeSeqOutput() during “early()” in a WF model, the tree sequence’s times measure time before the last set of individuals are born, i.e., before SLiM time step ts.metadata['SLiM']['tick'] - 1. The same thing applies to the “first” stage for both WF and nonWF models.

In some situations (e.g., mutations added during early() in WF models) this may not return what you expect. See Converting from SLiM time to tskit time and back for more discussion.

This method accesses top-level metadata, which may be a costly operation, so if this method will be called many times, it is recommended to extract this to a variable (e.g., ts_metadata = ts.metadata) and pass it to this method (as ts_metadata). However, beware: if ts_metadata is not in sync with the actual top-level metadata, incorrect values may result.

Parameters:

ts (tskit.TreeSequence) – A SLiM-compatible TreeSequence.
time (numpy.ndarray) – An array of times to be converted.
stage (str) – The stage of the SLiM life cycle that the SLiM time should be computed for.
ts_metadata (dict) – Optionally, the top-level metadata for ts.

pyslim.next_slim_mutation_id(ts)[source]#: Returns the next unused SLiM mutation ID for this tree sequence. This is useful because if you want to add more mutations to your SLiM tree sequence using msprime.sim_mutations(), you may need to specify the parameter next_id in your msprime.SLiMv6MutationModel to be larger than any existing mutation IDs. Setting next_id equal to the output of this function will allow the mutated tree sequence to be read in by SLiM. To do this, recall that the “derived state” of SLiM’s mutations are comma-separated strings of mutation IDs; this function just parses all derived states and returns one larger than the largest integer found. It will return an error if it encounters derived states that are not comma-separated strings of integers.

pyslim.has_vacant_samples(ts, ts_metadata=None)[source]#

Returns whether the tree sequence has vacant sample nodes. See remove_vacant().

Parameters:

ts (tskit.TreeSequence) – The tree sequence.
ts_metadata (dict) – Optionally, the top-level metadata for ts. If this does not match the actual top-level metadata, incorrect values may result.

pyslim.nodes_vacant(ts)[source]#

Evaluates which nodes in the tree sequence are vacant: returns a boolean vector whose k-th element is True if the k-th node is labelled as vacant in the node’s metadata recorded by SLiM. A vacant node represents a blank placeholder in SLiM: either a “null haplosome” (used as placeholders for sex chromosomes and other chromosome types not of consistent ploidy in all individuals) or simply an unused node for haploid chromosome types. See remove_vacant().

Parameters:: ts (tskit.TreeSequence) – The tree sequence.
Return boolean ndarray:

pyslim.node_is_vacant(ts, node)[source]#

DEPRECATED: use nodes_vacant() instead. This function requires top-level metadata access, which can be costly, so it is much better to do, for instance:

vacant = nodes_vacant(ts)
for node in ts.nodes():
    # instead of node_is_vacant(ts, node), use:
    vacant[node.id]

Returns True if the node is labelled as vacant in the node’s metadata recorded by SLiM. A vacant node represents a blank placeholder in SLiM: either a “null haplosome” (used as placeholders for sex chromosomes and other chromosome types not of consistent ploidy in all individuals) or simply an unused node for haploid chromosome types. See remove_vacant().

Parameters:

ts (tskit.TreeSequence) – The tree sequence.
node (tskit.Node) – The node object.

pyslim.is_current_version(ts, _warn=False)[source]#

Tests whether the metadata provided is the current SLiM file format or not. If not, use pyslim.update( ) to bring it up to date.

This method may be provided either a TreeSequence or TableCollection directly, or the metadata from one of these. The latter is useful because accessing top-level metadata can be a costly operation.

Parameters:: ts – Either the top-level metadata of a tree sequence, or a TreeSequence or TableCollection that carries this metadata.
Return bool:: Whether the tree sequence is the current version.

Metadata#

SLiM-specific metadata is made visible to the user by .metadata properties, described in Metadata.

Annotation#

These two functions will add default SLiM metadata to a tree sequence (or the underlying tables), which can then be modified and loaded into SLiM.

pyslim.annotate(ts, model_type, tick, cycle=None, stage='early', reference_sequence=None, annotate_mutations=True)[source]#

Takes a tree sequence (as produced by msprime, for instance), and adds in the information necessary for SLiM to use it as an initial state, filling in mostly default values. Returns a tskit.TreeSequence.

Parameters:

ts (tskit.TreeSequence) – A tskit.TreeSequence.
model_type (str) – SLiM model type: either “WF” or “nonWF”.
tick (int) – What tick number in SLiM correponds to time=0 in the tree sequence.
cycle (int) – What cycle number in SLiM correponds to time=0 in the tree sequence (default: equal to tick).
stage (int) – What stage in SLiM’s cycle has the tree sequence been written out in (defaults to “early”; must be “early” or “late”).
reference_sequence (str) – A reference sequence of length equal to ts.sequence_length.
annotate_mutations (bool) – Whether to replace mutation metadata with defaults. (If False, information about mutations is unchanged.)

pyslim.annotate_tables(tables, model_type, tick, cycle=None, stage='early', reference_sequence=None, annotate_mutations=True)[source]#: Does the work of annotate(), but modifies the tables in place: so, takes tables as produced by msprime, and makes them look like the tables as output by SLiM. See annotate() for details.

Constants and flags#

pyslim.NUCLEOTIDES = ['A', 'C', 'G', 'T']#: Mutation metadata records the nucleotide as an integer, translated to ACGT by indexing this array, so a nucleotide value of k actually means NUCLEOTIDES[k].

This is a flag used in node.flags (see remove_vacant()):

pyslim.NODE_IS_VACANT_SAMPLE = np.uint32(65536)#: This flag exists because SLiM expects certain vacant nodes to be marked as samples (those vacant nodes corresponding to alive individuals), but including these as samples causes problems for certain operations in tskit. So, if remove_vacant() is used to remove the ‘sample’ flags from those vacant nodes, this flag is applied so that the sample flag can be easily put back (by restore_vacant()). So, this flag means that this is is a vacant node that SLiM will expect to be a sample but is not currently marked as a sample (in particular, if this flag is set then the tskit.NODE_IS_SAMPLE flag is not expected to be set).

These are the possible values for individual.metadata["sex"]:

pyslim.INDIVIDUAL_TYPE_HERMAPHRODITE = -1#: A value used in individual metadata (“sex”) to indicate the individual is a hermaphrodite.

pyslim.INDIVIDUAL_TYPE_FEMALE = 0#: A value used in individual metadata (“sex”) to indicate the individual is a female.

pyslim.INDIVIDUAL_TYPE_MALE = 1#: A value used in individual metadata (“sex”) to indicate the individual is a male.

Finally, these are used in individual.flags:

pyslim.INDIVIDUAL_ALIVE = np.uint32(65536)#: Used in individual.flags to denote the individual is alive when the tree sequence was written out.

pyslim.INDIVIDUAL_REMEMBERED = np.uint32(131072)#: Used in individual.flags to denote the individual was marked as “remembered”.

pyslim.INDIVIDUAL_RETAINED = np.uint32(262144)#: Used in individual.flags to denote the individual was marked as “retained”.

pyslim.INDIVIDUAL_MIGRATED = np.uint32(524288)#: Used in individual.flags to denote the individual was a migrant.

Python API

Contents

Python API#

Editing or adding to tree sequences#

Summarizing tree sequences#

Utilities#

Metadata#

Annotation#

Constants and flags#