Struct demes::GraphBuilder

pub struct GraphBuilder { /* private fields */ }

This type allows building a Graph using code rather then using text input.

Notes

• A “builder” in rust will never be as convenient as one in, say, Python or Juilia. The lack of a rust REPL and the strong type checking are the primary reasons.
• All error checks are delayed until resolution.

Implementations

impl GraphBuilder

pub fn new( time_units: TimeUnits, generation_time: Option<GenerationTime>, defaults: Option<GraphDefaults> ) -> Self

Constructor

Returns

This function returns an “builder” containing an unresolved Graph.

pub fn new_generations(defaults: Option<GraphDefaults>) -> Self

Construct a builder with time units in generations.

This function works by calling GraphBuilder::new.

pub fn add_deme( &mut self, name: &str, epochs: Vec<UnresolvedEpoch>, history: UnresolvedDemeHistory, description: Option<&str> )

Add a Deme to the graph.

Examples

let start_size = demes::DemeSize::from(100.);
let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
let history = demes::UnresolvedDemeHistory::default();
let mut b = demes::GraphBuilder::new_generations(None);
b.add_deme("A", vec![epoch], history, Some("this is deme A"));
b.resolve().unwrap();

Notes

pub fn add_asymmetric_migration<S: ToString, D: ToString>( &mut self, source: Option<S>, dest: Option<D>, rate: Option<MigrationRate>, start_time: Option<Time>, end_time: Option<Time> )

Add an asymmetric migration

Examples

let start_size = demes::DemeSize::from(100.);
let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
let history = demes::UnresolvedDemeHistory::default();
let mut b = demes::GraphBuilder::new_generations(None);
b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
b.add_deme("B", vec![epoch], history, Some("this is deme B"));
b.add_asymmetric_migration(Some("A"),
                           Some("B"),
                           Some(demes::MigrationRate::from(1e-4)),
                           None, // Using None for the times
                                 // will mean continuous migration for the
                                 // duration for which the demes coexist.
                           None);
b.resolve().unwrap();

pub fn add_symmetric_migration<D: ToString>( &mut self, demes: Option<&[D]>, rate: Option<MigrationRate>, start_time: Option<Time>, end_time: Option<Time> )

Add a symmetric migration

Examples

let start_size = demes::DemeSize::from(100.);
let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
let history = demes::UnresolvedDemeHistory::default();
let mut b = demes::GraphBuilder::new_generations(None);
b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
b.add_deme("B", vec![epoch], history, Some("this is deme B"));
b.add_symmetric_migration(Some(&["A", "B"]),
                          Some(demes::MigrationRate::from(1e-4)),
                          None, // Using None for the times
                                // will mean continuous migration for the
                                // duration for which the demes coexist.
                          None);
b.resolve().unwrap();

pub fn add_migration<D: ToString, S: ToString, E: ToString>( &mut self, demes: Option<&[D]>, source: Option<S>, dest: Option<E>, rate: Option<MigrationRate>, start_time: Option<Time>, end_time: Option<Time> )

Add a migration to the graph.

Note

This function can be inconvenient due to the generics. Prefer add_symmetric_migration or add_asymmetric_migration.

Examples

Adding an asymmetric migration

let start_size = demes::DemeSize::from(100.);
let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
let history = demes::UnresolvedDemeHistory::default();
let mut b = demes::GraphBuilder::new_generations(None);
b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
b.add_deme("B", vec![epoch], history, Some("this is deme B"));
b.add_migration::<String, _, _>(None,
                  Some("A"),
                  Some("B"),
                  Some(demes::MigrationRate::from(1e-4)),
                  None, // Using None for the times
                        // will mean continuous migration for the
                        // duration for which the demes coexist.
                  None);
b.resolve().unwrap();

Adding a symmetric migration

let start_size = demes::DemeSize::from(100.);
let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
let history = demes::UnresolvedDemeHistory::default();
let mut b = demes::GraphBuilder::new_generations(None);
b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
b.add_deme("B", vec![epoch], history, Some("this is deme B"));
b.add_migration::<_, String, String>(Some(&["A", "B"]),
                  None,
                  None,
                  Some(demes::MigrationRate::from(1e-4)),
                  None, // Using None for the times
                        // will mean continuous migration for the
                        // duration for which the demes coexist.
                  None);
b.resolve().unwrap();

pub fn add_pulse( &mut self, sources: Option<&[&str]>, dest: Option<&str>, time: Option<Time>, proportions: Option<Vec<Proportion>> )

Add an UnresolvedPulse to the graph.

Examples

let start_size = demes::DemeSize::from(100.);
let epoch = demes::UnresolvedEpoch{start_size: Some(start_size), ..Default::default()};
let history = demes::UnresolvedDemeHistory::default();
let mut b = demes::GraphBuilder::new_generations(None);
b.add_deme("A", vec![epoch], history.clone(), Some("this is deme A"));
b.add_deme("B", vec![epoch], history, Some("this is deme B"));
b.add_pulse(Some(&["A"]),
            Some("B"),
            Some(demes::Time::from(50.0)),
            Some(vec![demes::Proportion::from(0.5)]));
b.resolve().unwrap();

pub fn resolve(self) -> Result<Graph, DemesError>

Generate and return a resolved Graph.

Errors

Returns `DemesError’ if any of the data are invalid.

pub fn set_toplevel_metadata<T: Serialize>( &mut self, metadata: &T ) -> Result<(), BuilderError>

Set top-level metadata

Parameters

• metadata: the metadata type

Note

Repeated calls will overwrite existing metadata.

Errors

• [BuilderError] if serialization to YAML fails.

Example

#[derive(serde::Serialize, serde::Deserialize)]
struct MyMetaData {
   foo: i32,
   bar: String
}
builder.set_toplevel_metadata(&MyMetaData{foo: 3, bar: "string".to_owned()}).unwrap();