dasmig::bthg Class Reference

Birth generator that produces demographically plausible birthdays from country age pyramids. More...

#include <birthgen.hpp>

Public Types
enum class	table : std::uint8_t { countries , age_pyramid , monthly_births }
	The three data tables. More...

Public Member Functions
	bthg ()=default
	Default constructor — creates an empty generator with no data.
	bthg (const bthg &)=delete
	Not copyable.
bthg &	operator= (const bthg &)=delete
	Not copyable.
	bthg (bthg &&) noexcept=default
	Movable.
bthg &	operator= (bthg &&) noexcept=default
	Movable.
	~bthg ()=default
	Destructor.
birth	get_birth (const birth_request &request)
	Generate a random birth using per-call filters and settings.
birth	get_birth (const birth_request &request, std::uint64_t call_seed) const
	Generate a deterministic birth using per-call filters and settings.
std::vector< birth >	get_birth_batch (const birth_request &request, const core::batch_options &options)
	Generate a batch of birth results from a seed drawn like get_birth() draws its own.
std::vector< birth >	get_birth_batch (const birth_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of birth results, deterministically.
template<typename Sink >
void	for_each_birth (const birth_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of birth results to a sink without holding the whole batch.
template<typename Sink >
void	for_each_birth (const birth_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of birth results with a batch seed drawn like get_birth() draws its own.
bool	has_data () const
	Check whether any country can be generated.
std::size_t	country_count () const
	Number of countries that can be generated.
std::vector< std::string >	countries () const
	The countries that can be generated, in the order of countries.tsv.
const std::vector< double > &	age_weights (std::string_view cca2, sex bio_sex) const
	A country's population by single age, as the generator draws ages.
double	life_expectancy (std::string_view cca2, sex bio_sex) const
	A country's life expectancy at birth, the figure le_remaining is computed from.
void	load (const std::filesystem::path &dir)
	Load data from a resource directory, replacing all data and layers loaded before.
bool	load (dataset tier)
	Load a dataset tier, replacing all data and layers loaded before.
void	extend (const std::filesystem::path &path, core::layer_mode mode=core::layer_mode::override)
	Add data layers from a directory or a file.
const core::layer_info &	extend (table which, core::tsv_document doc, core::layer_mode mode=core::layer_mode::override)
	Add a data layer to one table.
const core::layer_info &	extend_from_string (table which, std::string_view text, std::string source, core::layer_mode mode=core::layer_mode::override)
	Add a data layer to one table from TSV text.
const std::vector< core::layer_info > &	layers (table which) const
	The layers in effect for one table, in order.
std::uint64_t	data_hash () const
	Hash of the loaded data (all three tables), recorded in each result's signature().

Static Public Member Functions
static bthg &	instance ()
	Access the global singleton instance.
static std::string_view	cohort_of (int year)
	The generational cohort of a birth year, as birth::cohort labels it (see the table in the usage guide).

Static Public Attributes
static constexpr std::chrono::year_month_day	default_reference_date
	The default reference date: 1 July 2023, the date the UN World Population Prospects estimates in the data refer to.

Detailed Description

Birth generator that produces demographically plausible birthdays from country age pyramids.

The generation pipeline, each step drawing from its own stream split from the call seed (so fixing the sex, year or age range leaves the other steps' draws unchanged):

1. Sex, weighted by the country's male:female population.
2. Age in completed years, from the country's age pyramid for that sex (optionally restricted to an age range), or derived from a fixed year.
3. Month, from the country's seasonal weights.
4. Day, uniform within the month and placed so that the age at the reference date is exact; weekend days are redrawn with a probability that grows with the country's caesarean rate.
5. Weekday, remaining life expectancy and generational cohort.

Ages are relative to a fixed reference date (default 2023-07-01, the date of the population estimates), not the clock, so a seed gives the same birth every time. Output is identical on every compiler and platform (dasmig-core).

Thread safety

Each instance is independent. Concurrent calls to get_birth() on the same instance require external synchronisation.

Definition at line 189 of file birthgen.hpp.

Member Enumeration Documentation

table

enum class dasmig::bthg::table : std::uint8_t

strong

The three data tables.

Enumerator
countries	countries.tsv: names, life expectancy, caesarean rate.
age_pyramid	age_pyramid.tsv: population by single age and sex.
monthly_births	monthly_births.tsv: seasonal birth weights.

Definition at line 193 of file birthgen.hpp.

Member Function Documentation

age_weights()

const std::vector< double > & dasmig::bthg::age_weights ( std::string_view  cca2, sex  bio_sex  ) const

inline

A country's population by single age, as the generator draws ages.

Relative weights, not normalised: they are the rows of age_pyramid.tsv (population by age 0 to 100 and sex), so two countries' weights are comparable only within a country.

Parameters

cca2	ISO 3166-1 alpha-2 code.
bio_sex	The sex.

Returns

101 weights, index = age in completed years.

Exceptions

std::runtime_error	If no data is loaded.
std::invalid_argument	If the country has no data.

Definition at line 375 of file birthgen.hpp.

cohort_of()

static std::string_view dasmig::bthg::cohort_of ( int  year )

inlinestatic

The generational cohort of a birth year, as birth::cohort labels it (see the table in the usage guide).

Parameters

year	The birth year.

Returns

Greatest Generation up to 1927, then Silent Generation, Baby Boomer, Generation X, Millennial, Generation Z, and Generation Alpha from 2013.

Definition at line 400 of file birthgen.hpp.

countries()

std::vector< std::string > dasmig::bthg::countries ( ) const

inline

The countries that can be generated, in the order of countries.tsv.

Returns

ISO 3166-1 alpha-2 codes; empty when no data is loaded.

Definition at line 357 of file birthgen.hpp.

country_count()

std::size_t dasmig::bthg::country_count ( ) const

inline

Number of countries that can be generated.

Returns

The count.

Definition at line 352 of file birthgen.hpp.

data_hash()

std::uint64_t dasmig::bthg::data_hash ( ) const

inline

Hash of the loaded data (all three tables), recorded in each result's signature().

Returns

The hash; 0 when nothing is loaded.

Definition at line 521 of file birthgen.hpp.

extend() [1/2]

void dasmig::bthg::extend ( const std::filesystem::path &  path, core::layer_mode  mode = core::layer_mode::override  )

inline

Add data layers from a directory or a file.

A directory may hold any of countries.tsv, age_pyramid.tsv and monthly_births.tsv; all are applied together or, if any fails, none. A file must have one of those names. Rows are keyed by cca2; see Extending Data in doc/usage.md.

Parameters

path	Directory or file.
mode	How the layers combine with the data loaded before.

Exceptions

core::tsv_error	If a file cannot be read or a row is invalid; the data is then unchanged.
std::invalid_argument	If path is a file with another name.

Definition at line 462 of file birthgen.hpp.

extend() [2/2]

const core::layer_info & dasmig::bthg::extend ( table  which, core::tsv_document  doc, core::layer_mode  mode = core::layer_mode::override  )

inline

Add a data layer to one table.

Parameters

which	The table.
doc	TSV with that table's columns.
mode	How the layer combines with the data loaded before.

Returns

What the layer did.

Exceptions

core::tsv_error

If a row is invalid; the data is unchanged.

Definition at line 488 of file birthgen.hpp.

extend_from_string()

const core::layer_info & dasmig::bthg::extend_from_string ( table  which, std::string_view  text, std::string  source, core::layer_mode  mode = core::layer_mode::override  )

inline

Add a data layer to one table from TSV text.

Parameters

which	The table.
text	TSV with that table's columns.
source	Name used in errors.
mode	How the layer combines with the data loaded before.

Returns

What the layer did.

Exceptions

core::tsv_error

If a row is invalid; the data is unchanged.

Definition at line 504 of file birthgen.hpp.

for_each_birth() [1/2]

template<typename Sink >

void dasmig::bthg::for_each_birth ( const birth_request &  request, const core::batch_options &  options, Sink &&  sink  )

inline

Stream a batch of birth results with a batch seed drawn like get_birth() draws its own.

Template Parameters

Sink	Callable taking (std::uint64_t, birth&).

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
sink	Receives the items.

Definition at line 336 of file birthgen.hpp.

for_each_birth() [2/2]

template<typename Sink >

void dasmig::bthg::for_each_birth ( const birth_request &  request, const core::batch_options &  options, std::uint64_t  batch_seed, Sink &&  sink  ) const

inline

Stream a batch of birth results to a sink without holding the whole batch.

Generates the same items as get_birth_batch() and calls sink(index, item) in index order on the calling thread; index includes options.first.

Template Parameters

Sink	Callable taking (std::uint64_t, birth&); for example core::jsonl_writer or core::csv_writer.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
batch_seed	Seed of the whole batch.
sink	Receives the items.

Definition at line 321 of file birthgen.hpp.

get_birth() [1/2]

birth dasmig::bthg::get_birth ( const birth_request &  request )

inline

Generate a random birth using per-call filters and settings.

Draws a call seed from the instance's entropy-initialized random engine. Use get_birth(request, seed) for deterministic generation.

Parameters

request

All filters and settings for this call.

Returns

The birth, including its seed for replay with the same request.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the country is unknown, the reference date or age range is invalid, or both year and ages are specified.

Definition at line 236 of file birthgen.hpp.

get_birth() [2/2]

birth dasmig::bthg::get_birth ( const birth_request &  request, std::uint64_t  call_seed  ) const

inline

Generate a deterministic birth using per-call filters and settings.

Does not advance the internal random engine. Replay with the same request, seed and data.

Parameters

request	Filters and settings for this call.
call_seed	Seed.

Returns

The birth.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the country is unknown, the reference date or age range is invalid, or both year and ages are specified.

Definition at line 251 of file birthgen.hpp.

get_birth_batch() [1/2]

std::vector< birth > dasmig::bthg::get_birth_batch ( const birth_request &  request, const core::batch_options &  options  )

inline

Generate a batch of birth results from a seed drawn like get_birth() draws its own.

Item i is get_birth(request, core::item_seed(batch_seed, options.first + i)) for the drawn batch seed; see the seeded overload.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.

Returns

The results, in index order.

Definition at line 278 of file birthgen.hpp.

get_birth_batch() [2/2]

std::vector< birth > dasmig::bthg::get_birth_batch ( const birth_request &  request, const core::batch_options &  options, std::uint64_t  batch_seed  ) const

inline

Generate a batch of birth results, deterministically.

Item i is exactly get_birth(request, core::item_seed(batch_seed, options.first + i)), so an item replays on its own, a range can be generated directly, two batches that follow each other equal one, and the output does not depend on options.threads.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness (see core::unique_rule; the rule must be made for birth).
batch_seed	Seed of the whole batch.

Returns

The results, in index order.

Exceptions

std::invalid_argument	If the request or options are invalid.
std::runtime_error	If no data has been loaded, or a unique batch runs out of attempts.

Definition at line 299 of file birthgen.hpp.

has_data()

bool dasmig::bthg::has_data ( ) const

inline

Check whether any country can be generated.

Returns

True when at least one country has an age pyramid and life expectancy.

Definition at line 348 of file birthgen.hpp.

instance()

static bthg & dasmig::bthg::instance ( )

inlinestatic

Access the global singleton instance.

Loads the lite tier (or full if lite is missing) on first access, from compiled-in data or an auto-probed resources/.

Returns

The singleton.

Definition at line 219 of file birthgen.hpp.

layers()

const std::vector< core::layer_info > & dasmig::bthg::layers ( table  which ) const

inline

The layers in effect for one table, in order.

Parameters

which

The table.

Returns

The layer records.

Definition at line 513 of file birthgen.hpp.

life_expectancy()

double dasmig::bthg::life_expectancy ( std::string_view  cca2, sex  bio_sex  ) const

inline

A country's life expectancy at birth, the figure le_remaining is computed from.

Parameters

cca2	ISO 3166-1 alpha-2 code.
bio_sex	The sex.

Returns

Years.

Exceptions

std::runtime_error	If no data is loaded.
std::invalid_argument	If the country has no data.

Definition at line 388 of file birthgen.hpp.

load() [1/2]

void dasmig::bthg::load ( const std::filesystem::path &  dir )

inline

Load data from a resource directory, replacing all data and layers loaded before.

Reads countries.tsv, age_pyramid.tsv and monthly_births.tsv; a missing file leaves its table empty. A path that is not a directory, or has no countries.tsv, is ignored.

Parameters

dir	Directory such as resources/lite.

Exceptions

core::tsv_error

If a file is malformed; the data is then unchanged.

Definition at line 412 of file birthgen.hpp.

load() [2/2]

bool dasmig::bthg::load ( dataset  tier )

inline

Load a dataset tier, replacing all data and layers loaded before.

Uses the compiled-in copy when the library is built with DASMIG_BIRTH_EMBED, otherwise searches resources/, ../resources, birth-generator/resources and ../birth-generator/resources.

Parameters

tier

The tier.

Returns

False when the tier was not found.

Exceptions

core::tsv_error

If a file is malformed.

Definition at line 434 of file birthgen.hpp.

Member Data Documentation

default_reference_date

constexpr std::chrono::year_month_day dasmig::bthg::default_reference_date

staticconstexpr

Initial value:

{
        birth_request::default_reference_date}

The default reference date: 1 July 2023, the date the UN World Population Prospects estimates in the data refer to.

Definition at line 202 of file birthgen.hpp.

---

The documentation for this class was generated from the following file:

• dasmig/birthgen.hpp