Struct ForwardGraph 

pub struct ForwardGraph { /* private fields */ }

Forward-time representation of a demes::Graph.

Implementations

impl ForwardGraph

pub fn new_discrete_time<F: Into<ForwardTime> + Debug + Copy>( graph: Graph, burnin_time: F, ) -> Result<Self, DemesForwardError>

Constructor

Parameters

• graph: a demes::Graph.
• burnin_time: Burn-in time for the model.

Examples found in repository

examples/iterate_gutenkunst.rs (line 45)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn update_state<F: Into<ForwardTime> + Debug + Copy>( &mut self, parental_generation_time: F, ) -> Result<(), DemesForwardError>

Update the internal state of the graph to the parental generation time parental_generation_time.

Examples found in repository

examples/iterate_gutenkunst.rs (line 51)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn num_demes_in_model(&self) -> usize

The total number of demes in the graph.

Examples found in repository

examples/iterate_gutenkunst.rs (line 71)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn ancestry_proportions(&self, offspring_deme: usize) -> Option<&[f64]>

The ancestry proporitions for a given offspring deme at the current time.

Parameters

• offspring_deme: the index of an offspring deme.

Returns

• Some(&[f64]) if offspring_deme is a valid index and extant offspring demes exist.
• None otherwise.

Examples found in repository

examples/iterate_gutenkunst.rs (line 97)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn cloning_rates(&self) -> Option<&[CloningRate]>

Get cloning rates of all offspring demes.

Returns None if there are no extant offspring demes.

Examples found in repository

examples/iterate_gutenkunst.rs (line 86)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn selfing_rates(&self) -> Option<&[SelfingRate]>

Get selfing rates of all offspring demes.

Returns None if there are no extant offspring demes.

Examples found in repository

examples/iterate_gutenkunst.rs (line 83)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn last_time_updated(&self) -> Option<ForwardTime>

Obtain the time corresponding to the last call of ForwardGraph::update_state.

Examples found in repository

examples/iterate_gutenkunst.rs (line 132)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn end_time(&self) -> ForwardTime

Obtain the end time of the model.

pub fn time_iterator(&self) -> impl Iterator<Item = ForwardTime>

Return an iterator over time values.

The iterator starts at the last updated time and continues until the end time.

Examples found in repository

examples/iterate_gutenkunst.rs (line 53)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn parental_deme_sizes(&self) -> Option<&[CurrentSize]>

Obtain the sizes of each parental deme.

The length of the slice is equal to the number of demes in the graph (see ForwardGraph::num_demes_in_model).

Returns None if there are no parental demes at the current time.

Examples found in repository

examples/iterate_gutenkunst.rs (line 64)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn offspring_deme_sizes(&self) -> Option<&[CurrentSize]>

Obtain the sizes of each offspring deme.

The length of the slice is equal to the number of demes in the graph (see ForwardGraph::num_demes_in_model).

Returns None if there are no offspring demes at the current time.

Examples found in repository

examples/iterate_gutenkunst.rs (line 59)

fn iterate_model(
    graph: demes::Graph,
    burnin: i32,
) -> Result<demes_forward::ForwardTime, Box<dyn std::error::Error>> {
    // Convert the backwards time model
    // to a forward-time representation with
    // some generations of burn-in.
    //
    // The forward graph is mutable because
    // we will update its internal state
    // during iteration.
    //
    // The final argument, None, means to apply
    // no rounding when converting times into generations.
    // None is safe for this model, but may not be so generally.
    // See the demes-rs docs at https://docs.rs/demes for details on rounding methods.
    //
    // NOTE: the implementation of rounding in demes is currently an enum.
    // In the future, it may become a trait, which would break API here
    // but allow for more flexibility in client code.
    let mut forward_graph = demes_forward::ForwardGraph::new_discrete_time(graph, burnin)?;

    // Update the internal model state
    // to parental generation 0, meaning
    // that the first offspring will have
    // birth times of generation 1.
    forward_graph.update_state(0)?;

    for time in forward_graph.time_iterator() {
        // time refers to a parental generation.
        // Therefore, when we have iterated to the time point
        // where the final generation are now parents, there
        // are no offspring and forward_graph.offspring_deme_sizes()
        // returns None.
        if let Some(offspring_deme_sizes) = forward_graph.offspring_deme_sizes() {
            // Get the parent deme sizes.
            // Given our previous "if let ...", this statement cannot/should not
            // return None, and we will panic! if it does.
            let parental_deme_sizes = forward_graph
                .parental_deme_sizes()
                .unwrap_or_else(|| panic!("expected parental deme sizes at time {time}"));

            // The deme size slices have lengths equal to the total
            // number of demes in the graph.
            assert_eq!(
                offspring_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );
            assert_eq!(
                parental_deme_sizes.len(),
                forward_graph.num_demes_in_model()
            );

            // Get the selfing and cloning rates for each deme.
            // The order is the same as the order of demes in the graph.
            // This model has no selfing/cloning, but we include the accesses
            // for completeness.
            let selfing_rates = forward_graph
                .selfing_rates()
                .unwrap_or_else(|| panic!("expected selfing rates"));
            let cloning_rates = forward_graph
                .cloning_rates()
                .unwrap_or_else(|| panic!("expected cloning rates"));

            assert_eq!(selfing_rates.len(), forward_graph.num_demes_in_model());
            assert_eq!(cloning_rates.len(), forward_graph.num_demes_in_model());

            // Iterate over offspring deme indexes
            for (offspring_deme_index, offspring_deme_size) in
                offspring_deme_sizes.iter().enumerate()
            {
                let ancestry_proportions = forward_graph
                    .ancestry_proportions(offspring_deme_index)
                    .unwrap_or_else(|| {
                        panic!(
                            "expected ancestry proportions for offspring deme {offspring_deme_index} at time {time}",
                        )
                    });
                if offspring_deme_size > &0.0 {
                    // If an the offspring deme is extant (size > 0),
                    // then any ancestral deme with a proportion > 0 must
                    // have size > 0.
                    // Further, the sum of all ancestry proportions into
                    // the offspring deme must sum to ~1.0.
                    assert!((ancestry_proportions.iter().sum::<f64>() - 1.0).abs() <= f64::EPSILON);
                    for (ancestor, proportion) in ancestry_proportions.iter().enumerate() {
                        if proportion > &0.0 {
                            assert!(parental_deme_sizes[ancestor] > 0.0);
                        }
                        // NOTE: is incorrect to assert that the ancestor
                        // size is 0 if the ancestry proportion of that ancestor
                        // into offspring_deme is 0!
                        // The ancestor deme could exist but only as an ancestor
                        // of another offspring deme in the graph.
                    }
                } else {
                    // An offspring deme with size 0 has no ancestry.
                    assert_eq!(ancestry_proportions.iter().sum::<f64>(), 0.0);
                }
            }
        }

        // Update the internal state to the next time point.
        forward_graph.update_state(time + 1.into())?;
    }

    Ok(forward_graph
        .last_time_updated()
        .expect("expected Some(ForwardTime)"))
}

pub fn any_extant_parental_demes(&self) -> bool

Return true if there are any extant parental demes at the current time.

pub fn any_extant_offspring_demes(&self) -> bool

Return true if there are any extant offspring demes at the current time.

pub fn num_extant_parental_demes(&self) -> usize

Return the number of extant parental demes at the current time.

pub fn num_extant_offspring_demes(&self) -> usize

Return the number of extant offspring demes at the current time.

pub fn size_at<'a, I: Into<DemeId<'a>>, T: Into<BackwardTimeWrapper>>( &self, deme: I, time: T, ) -> Result<Option<CurrentSize>, DemesForwardError>

Obtain the size (number of parental individuals) of a given deme at a given time.

Parameters

• deme: a deme identifier
• time: a time

Returns

• Some(DemeSize) if there are parents at the given time.
• None if deme does not exist or the deme exists but is not in existence at time.

Errors

DemesForwardError if the calculation of deme size returns an invalid demes::DemeSize or if time is not a valid value.

Notes

• Time is measured backwards in time from 0.0 (inclusive of zero). The reason is that it is usually easier to reason about time in this way.
• Unlike a demes::Graph, time does not go back in the past to “infinity”. The first parental generation is considered to exist at a time one generation prior to the start of events in the graph plus the burn-in time.

pub fn deme_size_history<'a, I>( &self, deme: I, ) -> Result<impl Iterator<Item = DemeSizeAt>, DemesForwardError>

where I: Debug + Into<DemeId<'a>>,

Generate an iterator over the size history of a deme.

Parameters

• deme: the index or name of the deme

Returns

An iterator over instances of DemeSizeAt.

Errors

This function will return an error if:

• deme does not exist in the graph

Note

The iterated values are lazily evaluated. First self is cloned. Then, the entire model history is iterated over, and the output data is returned during iteration.

Panics

• Cloning the graph requires allocations which will panic if the system runs out of memory

pub fn backwards_start_time(&self) -> Time

Return the time in the past when the first generation of the model exists. This time point represents the individuals alive at time zero (forwards in time) who are the ancestors of those individuals born at time 1 of the model.

pub fn backwards_burn_in_time(&self) -> Time

Return the time in the model at the end of any “burn-in”.

Note

This value is distinct from the burn-in duration. Instead, this value represents the time when all alive individuals are the ancestors of the first finite time in the demes::Graph.

pub fn time_to_backward<T: Into<ForwardTimeWrapper>>( &self, time: T, ) -> Result<Option<Time>, DemesForwardError>

Convert a forward time value (ForwardTime) into a backwards time value (demes::Time)

Returns

• None if time is ancestral to the start of the model or more recent than the model’s end.

pub fn time_to_forward<T: Into<BackwardTimeWrapper>>( &self, time: T, ) -> Result<Option<ForwardTime>, DemesForwardError>

Convert a backwards time value (demes::Time) into a forward time value (ForwardTime)

Returns

• None if time is ancestral to the start of the model or more recent than the model’s end.

pub fn deme_names(&self) -> Box<[&str]>

Get the names of each deme in the model.

Note

Implemented by calling demes::Graph::deme_names.

pub fn demes_graph(&self) -> &Graph

Access to the underlying demes::Graph

Trait Implementations

impl Clone for ForwardGraph

fn clone(&self) -> ForwardGraph

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ForwardGraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.