Occupation Generator: draws a person's employment status, education and job. More...

#include <occupationgen.hpp>

Public Types
enum class	table : std::uint8_t { status , inactivity , education , isco , shares , factors , occupations }
	The data tables. More...

Public Member Functions
	ocg ()
	Default constructor — creates an empty generator with no data.

	ocg (const ocg &)=delete
	Not copyable.

ocg &	operator= (const ocg &)=delete
	Not copyable.

	ocg (ocg &&) noexcept=default
	Movable.

ocg &	operator= (ocg &&) noexcept=default
	Movable.

	~ocg ()=default
	Destructor.

occupation	get_occupation (const occupation_request &request)
	Generate a random occupation for a request.

occupation	get_occupation (const occupation_request &request, std::uint64_t call_seed) const
	Generate a deterministic occupation for a request.

std::vector< occupation >	get_occupation_batch (const occupation_request &request, const core::batch_options &options)
	Generate a batch of occupation results from a seed drawn like get_occupation() draws its own.

std::vector< occupation >	get_occupation_batch (const occupation_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of occupation results, deterministically.

template<typename Sink >
void	for_each_occupation (const occupation_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of occupation results to a sink without holding the whole batch.

template<typename Sink >
void	for_each_occupation (const occupation_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of occupation results with a batch seed drawn like get_occupation() draws its own.

bool	has_data () const
	Check whether status data has been loaded.

std::size_t	country_count () const
	Return the number of countries that can be drawn from.

std::size_t	job_count () const
	Return the number of jobs in the catalogue.

const std::vector< std::string > &	unresolved () const
	Rows that name something that is not loaded: a share for an unknown ISCO group, a job for an unknown ISCO group. They are ignored, so removing a group needs no other change; this lists them to catch misspelt codes.

void	load (const std::filesystem::path &dir)
	Load 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 (for example from a WebAssembly host).

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 tables), recorded in each result's signature().

Static Public Member Functions
static ocg &	instance ()
	Access the global singleton instance.

Detailed Description

Occupation Generator: draws a person's employment status, education and job.

The country (when not given) comes from the "country" stream of the call seed, the sex from "sex", the status from "status", the education from "education", the ISCO-08 group from "isco" and the job within it from "job", so fields added later leave these unchanged. Output is identical on every compiler and platform (dasmig-core).

The status comes from the country's employment and unemployment rates for the person's sex and age band; the inactive are split into students, retired and others by age. From 6 to 14 a person is a student, and under 6 inactive with no job. The job is an ISCO-08 level-2 group drawn by the country's employment share for the person's sex, multiplied by factors for the person's age class and education (how much more or less common the group is at that age or education than in employment as a whole), then a job of the catalogue within the group. Groups with no job open to the person's age are skipped.

The education comes from the country's shares for the sex and age band. A level the person is too young to have completed (basic under 14, intermediate under 17, advanced under 21) counts as the level below.

A country chosen at random is uniform over the countries loaded; the data has no population column. Pass a country chosen by country-generator for a population-weighted world.

Every call takes an occupation_request; generation choices are never stored as instance defaults. Data loading and layers belong to the instance. Can be used as a singleton via instance() or constructed independently.

Thread safety: Each instance is independent. Concurrent calls to get_occupation(request) on the same instance require external synchronisation.

Definition at line 260 of file occupationgen.hpp.

Member Enumeration Documentation

◆ table

enum class dasmig::ocg::table : std::uint8_t

strong

The data tables.

Enumerator
status	`status.tsv`: key `country_code`, `sex`, `band`; employed, unemployed, inactive (percent), basis, year.
inactivity	`inactivity.tsv`: key `band`; student, retired, other (shares of the inactive).
education	`education.tsv`: key `country_code`, `sex`, `band`; less_than_basic, basic, intermediate, advanced, basis, year.
isco	`isco.tsv`: key `code` (ISCO-08 level 2); label, major, skill.
shares	`shares.tsv`: key `country_code`, `sex`, `code`; share (percent of employment), basis, year.
factors	`factors.tsv`: key `country_code`, `major`, `dimension`, `value`; factor, basis, year.
occupations	`occupations.tsv`: key `key`; label, isco, weight, unit, min_age, max_age, tags, skills, gear.

Definition at line 264 of file occupationgen.hpp.

Constructor & Destructor Documentation

◆ ocg()

dasmig::ocg::ocg ( )

inline

Default constructor — creates an empty generator with no data.

Definition at line 277 of file occupationgen.hpp.

Member Function Documentation

◆ country_count()

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

inline

Return the number of countries that can be drawn from.

Returns: The count: countries with status rows for both sexes.

Definition at line 408 of file occupationgen.hpp.

◆ data_hash()

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

inline

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

Returns: The hash; 0 when nothing is loaded.

Definition at line 549 of file occupationgen.hpp.

◆ extend() [1/2]

void dasmig::ocg::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 the table files (status.tsv, inactivity.tsv, education.tsv, isco.tsv, shares.tsv, factors.tsv, occupations.tsv); all are applied together or, if any fails, none. A file must have one of those names.

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 484 of file occupationgen.hpp.

◆ extend() [2/2]

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

inline

Add a data layer to one table.

Rows are keyed by the table's key columns (see table). In the default override mode a row replaces the loaded row with the same key and new keys are added; a row with disabled set to 1 removes its key.

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 (rows added, replaced, removed, warnings).

Exceptions

core::tsv_error If a row is invalid; the data is unchanged.

Definition at line 515 of file occupationgen.hpp.

◆ extend_from_string()

const core::layer_info & dasmig::ocg::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 (for example from a WebAssembly host).

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 532 of file occupationgen.hpp.

◆ for_each_occupation() [1/2]

template<typename Sink >

void dasmig::ocg::for_each_occupation	(	const occupation_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of occupation results with a batch seed drawn like get_occupation() draws its own.

Template Parameters

Sink	Callable taking `(std::uint64_t, occupation&)`.

Parameters

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

Definition at line 393 of file occupationgen.hpp.

◆ for_each_occupation() [2/2]

template<typename Sink >

void dasmig::ocg::for_each_occupation	(	const occupation_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

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

Generates the same items as get_occupation_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, occupation&)`; 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 378 of file occupationgen.hpp.

◆ get_occupation() [1/2]

occupation dasmig::ocg::get_occupation ( const occupation_request & request )

inline

Generate a random occupation for a request.

Parameters

request Country, age, sex, education and status; any may be omitted. Pass {} to use the request defaults.

Draws a call seed from the instance's entropy-seeded engine.

Returns: The occupation.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If the country has no data for the person (or, with no country, no country has any), or no occupation is open to the person.

Definition at line 307 of file occupationgen.hpp.

◆ get_occupation() [2/2]

occupation dasmig::ocg::get_occupation	(	const occupation_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate a deterministic occupation for a request.

Parameters

request	Country, age, sex, education and status; any may be omitted.
call_seed	Seed; the same seed, request and data give the same occupation.

Returns: The occupation.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	As for the unseeded overload.

Definition at line 319 of file occupationgen.hpp.

◆ get_occupation_batch() [1/2]

std::vector< occupation > dasmig::ocg::get_occupation_batch	(	const occupation_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch of occupation results from a seed drawn like get_occupation() draws its own.

Item i is get_occupation(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 335 of file occupationgen.hpp.

◆ get_occupation_batch() [2/2]

std::vector< occupation > dasmig::ocg::get_occupation_batch	(	const occupation_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch of occupation results, deterministically.

Item i is exactly get_occupation(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 `occupation`).
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 356 of file occupationgen.hpp.

◆ has_data()

bool dasmig::ocg::has_data ( ) const

inline

Check whether status data has been loaded.

Returns: True when at least one status row is loaded.

Definition at line 404 of file occupationgen.hpp.

◆ instance()

static ocg & dasmig::ocg::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 290 of file occupationgen.hpp.

◆ job_count()

std::size_t dasmig::ocg::job_count ( ) const

inline

Return the number of jobs in the catalogue.

Returns: The count.

Definition at line 412 of file occupationgen.hpp.

◆ layers()

const std::vector< core::layer_info > & dasmig::ocg::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 541 of file occupationgen.hpp.

◆ load() [1/2]

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

inline

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

The directory must contain status.tsv; the other tables are read when present (a missing one leaves its table empty). A path without status.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 434 of file occupationgen.hpp.

◆ load() [2/2]

bool dasmig::ocg::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_OCCUPATION_EMBED, otherwise searches resources/, ../resources, occupation-generator/resources and ../occupation-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 456 of file occupationgen.hpp.

◆ unresolved()

const std::vector< std::string > & dasmig::ocg::unresolved ( ) const

inline

Rows that name something that is not loaded: a share for an unknown ISCO group, a job for an unknown ISCO group. They are ignored, so removing a group needs no other change; this lists them to catch misspelt codes.

Returns: One description per ignored row, such as ‘occupations.tsv:12: unknown ISCO group '7x’`.

Definition at line 420 of file occupationgen.hpp.

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

dasmig/occupationgen.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ table

Constructor & Destructor Documentation

◆ ocg()

Member Function Documentation

◆ country_count()

◆ data_hash()

◆ extend() [1/2]

◆ extend() [2/2]

◆ extend_from_string()

◆ for_each_occupation() [1/2]

◆ for_each_occupation() [2/2]

◆ get_occupation() [1/2]

◆ get_occupation() [2/2]

◆ get_occupation_batch() [1/2]

◆ get_occupation_batch() [2/2]

◆ has_data()

◆ instance()

◆ job_count()

◆ layers()

◆ load() [1/2]

◆ load() [2/2]

◆ unresolved()