Module fwdpy11.tskit_tools#

This module contains various things to help interact with tskit.

New in version 0.8.0.

The following are boolean flags that are used to populate the flags colummn of a tskit.IndividualTable. The flags represent individuals alive at the end of the simulation, those preserved as ancient samples, and those from the very first generation of the simulation, respectively. See here for why the last class of preserved samples are special.

fwdpy11.tskit_tools.INDIVIDUAL_IS_ALIVE#
fwdpy11.tskit_tools.INDIVIDUAL_IS_PRESERVED#
fwdpy11.tskit_tools.INDIVIDUAL_IS_FIRST_GENERATION#
fwdpy11.tskit_tools.get_toplevel_metadata(ts, name)#

Extract top-level metadata from a tree sequence.

Parameters:
Returns:

The metadata field, if name is a valid field, or None otherwise.

fwdpy11.tskit_tools.iterate_timepoints_with_individuals(ts, *, decode_metadata=False)#

Return an iterator over all unique time points with individuals.

Parameters:

  • ts (tskit.TreeSequence) – A tree sequence

  • decode_metadata (bool) – Flag to decode individual metadata or not

For each time point a tuple of (time, nodes, metadata) is yielded.

Parameters:

decode_individual_metadata (bool) – Whether to return decoded metadata.

If decode_individual_metadata is True, metadata will be stored in a list of fwdpy11.tskit_tools.DiploidMetadata. If False, None will be yielded.

fwdpy11.tskit_tools.decode_individual_metadata(ts, rows=None)#

Decodes a tskit.IndividualTable.

Parameters:

  • ts (tskit.TreeSequence) – A tree sequence

  • rows – The rows to decode. If None, the entire table is decoded and returned.

Returns:

individual metadata

Return type:

List of fwdpy11.tskit_tools.DiploidMetadata

Warning

Decoding the entire table may consume a lot of system memory.

New in version 0.12.0.

Changed in version 0.15.0: Add index/slice access to the table.

Changed in version 0.17.0: Change input from TableCollection to TreeSequence

class fwdpy11.tskit_tools.DiploidMetadata(*, g, e, w, sex, deme, label, alive, preserved, first_generation, parents, geography, nodes)#

Instances of this type are returned by fwdpy11.tskit_tools.decode_individual_metadata().

The following kwargs are used to construct instances of this type. Member attributes have the same names as these kwargs`:

Parameters:

  • g (float) – Genetic value

  • e (float) – “Random/environmental” value

  • w (float) – Fitness

  • sex (int) – Sex

  • deme (int) – Deme

  • label (int) – Index in the population at time of living/sampling

  • alive (bool) – Individual is alive

  • preserved (bool) – Individual is preserved

  • first_generation (bool) – Individual is first generation

  • parents (list) – label of parents

  • geography (list) – Location in 3d space

  • nodes (list) – Nodes on tree sequence

New in version 0.12.0.

fwdpy11.tskit_tools.decode_mutation_metadata(ts, rows=None)#

Decodes metadata from a tskit.MutationTable.

Parameters:

  • ts (tskit.TreeSequence) – A tree sequence

  • rows – The rows to decode. If None, the entire table is decoded and returned.

Returns:

Mutations

Return type:

list

Warning

Decoding the entire table may consume a lot of system memory.

New in version 0.12.0.

Changed in version 0.15.0: Return type is now a list, allowing some elements to be None.

Add index/slice access to the table.

Changed in version 0.17.0: Change input from TableCollection to TreeSequence