1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
//! rust support for
//! [demes](https://popsim-consortium.github.io/demes-spec-docs).
//!
//! # Introduction
//!
//! This crate provides:
//!
//! * Support for reading `YAML` descriptions of `demes` models.
//! See [`loads`](crate::loads) and [`load`](crate::load).
//! * Support for building a demes model using `rust` code.
//! See [`GraphBuilder`](crate::GraphBuilder).
//!
//! The output of any of these operations is a fully-resolved
//! [`Graph`](crate::Graph).
//!
//! ## More information
//!
//! * See [here](https://popsim-consortium.github.io/demes-spec-docs/main/introduction.html#) for
//! an overview of `demes`.
//!
//! ## Technical details
//!
//! * `YAML` and [`GraphBuilder`](crate::GraphBuilder) inputs
//! support the Human Data Model (HDM) described in the
//! demes
//! [specification](https://popsim-consortium.github.io/demes-spec-docs/main/specification.html)
//! * A [`Graph`] is fully-resolved according to the Machine
//! Data Model (MDM) described in the
//! [specification](https://popsim-consortium.github.io/demes-spec-docs/main/specification.html).
//!
//! # Features
//!
//! The following [cargo features](https://doc.rust-lang.org/cargo/reference/features.html)
//! are available:
//!
//! * `json`: enables reading/writing a [`Graph`] in JSON format.
#![warn(missing_docs)]
#![warn(rustdoc::broken_intra_doc_links)]
#![cfg_attr(doc_cfg, feature(doc_cfg))]
mod macros;
mod builder;
mod cloning_rate;
mod deme_size;
mod error;
mod migration_rate;
mod proportion;
mod selfing_rate;
mod specification;
mod time;
use std::io::Read;
pub use builder::{BuilderError, GraphBuilder};
pub use cloning_rate::{CloningRate, InputCloningRate};
pub use deme_size::{DemeSize, InputDemeSize};
pub use error::DemesError;
pub use migration_rate::{InputMigrationRate, MigrationRate};
pub use proportion::{InputProportion, Proportion};
pub use selfing_rate::{InputSelfingRate, SelfingRate};
pub use specification::*;
pub use time::*;
const VERSION: &str = env!("CARGO_PKG_VERSION");
/// Build a [`Graph`](crate::Graph) from an in-memory [`str`](std::primitive::str).
///
/// # Errors
///
/// Returns [`DemesError`](crate::DemesError) in the event of invalid input.
///
/// # Examples
///
/// ```
/// let yaml = "
/// time_units: generations
/// demes:
/// - name: ancestor
/// epochs:
/// - start_size: 100
/// - name: derived
/// start_time: 50
/// ancestors: [ancestor]
/// epochs:
/// - start_size: 10
/// ";
///
/// let graph = demes::loads(yaml).unwrap();
/// ```
pub fn loads(yaml: &str) -> Result<specification::Graph, DemesError> {
specification::Graph::new_resolved_from_str(yaml)
}
/// Generate a [`Graph`] from a JSON string.
#[cfg(feature = "json")]
#[cfg_attr(doc_cfg, doc(cfg(feature = "json")))]
pub fn loads_json(json: &str) -> Result<specification::Graph, DemesError> {
specification::Graph::new_resolved_from_json_str(json)
}
/// Build a [`Graph`](crate::Graph) from a type implementing
/// [`Read`](std::io::Read).
///
/// # Errors
///
/// Returns [`DemesError`](crate::DemesError) in the event of invalid input.
///
/// # Examples
///
/// ```
/// // We can load graphs from in-memory data in YAML format:
/// let yaml = "
/// time_units: generations
/// demes:
/// - name: ancestor
/// epochs:
/// - start_size: 100
/// - name: derived
/// start_time: 50
/// ancestors: [ancestor]
/// epochs:
/// - start_size: 10
/// ";
/// // A slice of raw bytes implements std::io::BufReader
/// // which implements Read
/// let raw_bytes: &[u8] = yaml.as_bytes();
/// let graph = demes::load(raw_bytes).unwrap();
/// # assert_eq!(graph, demes::loads(yaml).unwrap());
/// # // The more common use case will be to load from a file
/// # // First, let's create a file
/// # // and write our buffer to it.
/// # {
/// # use std::io::prelude::*;
/// # let mut file = std::fs::File::create("model.yaml").unwrap();
/// # file.write_all(raw_bytes);
/// # }
/// // We can also read from files:
/// let file = std::fs::File::open("model.yaml").unwrap();
/// let graph_from_file = demes::load(file).unwrap();
/// # assert_eq!(graph, graph_from_file);
/// # // clean up
/// # std::fs::remove_file("model.yaml").unwrap();
/// ```
pub fn load<T: Read>(reader: T) -> Result<specification::Graph, DemesError> {
specification::Graph::new_resolved_from_reader(reader)
}
#[cfg(feature = "json")]
#[cfg_attr(doc_cfg, doc(cfg(feature = "json")))]
/// Load a [`Graph`] from a JSON reader.
pub fn load_json<T: Read>(reader: T) -> Result<specification::Graph, DemesError> {
specification::Graph::new_resolved_from_json_reader(reader)
}
/// Return the package version given in the
/// `Cargo.toml` file of this crate.
///
/// # Examples
///
/// ```
/// let _ = demes::version();
/// ```
pub fn version() -> &'static str {
VERSION
}