mergeron.gen.data_generation_functions¶

Non-public functions called in data_generation.py.

Module Contents¶

mergeron.gen.data_generation_functions.market_share_sampler(_sample_size, _share_spec, _fcount_rng_seed_seq, _mktshr_rng_seed_seq, _nthreads, /)[source]¶

Generate share data.

Parameters:¶

_share_spec : mergeron.gen.MarketShareSpec¶: Class specifying parameters for generating market share data
_fcount_rng_seed_seq : numpy.random.SeedSequence | None¶: Seed sequence for assuring independent and, optionally, redundant streams
_mktshr_rng_seed_seq : numpy.random.SeedSequence¶: Seed sequence for assuring independent and, optionally, redundant streams
_nthreads : int¶: Must be specified for generating repeatable random streams

Returns:¶

Arrays representing shares, diversion ratios, etc. structured as a :MarketSharesData:

Return type:¶

mergeron.gen.MarketSharesData

mergeron.gen.data_generation_functions.market_share_sampler_uniform(_s_size, _dist_parms_mktshr, _mktshr_rng_seed_seq, _nthreads, /)[source]¶

Generate merging-firm shares from Uniform distribution on the 3-D simplex.

Parameters:¶

_s_size : int¶: size of sample to be drawn
_mktshr_rng_seed_seq : numpy.random.SeedSequence¶: seed for rng, so results can be made replicable
_nthreads : int¶: number of threads for random number generation

Returns:¶

market shares and other market statistics for each draw (market)

Return type:¶

mergeron.gen.MarketSharesData

mergeron.gen.data_generation_functions.market_share_sampler_dirichlet(_dir_alphas, _s_size, _recapture_form, _mktshr_rng_seed_seq, _nthreads, /)[source]¶

Dirichlet-distributed shares with fixed firm-count.

Parameters:¶

_dir_alphas : mergeron.ArrayDouble¶: Shape parameters for Dirichlet distribution
_s_size : int¶: sample size to be drawn
_recapture_form : mergeron.RECForm¶: r_1 = r_2 if RECForm.FIXED, otherwise MNL-consistent. If RECForm.OUTIN; the number of columns in the output share array is len(_dir_alphas) - 1.
_mktshr_rng_seed_seq : numpy.random.SeedSequence¶: seed market share rng, for replicable results
_nthreads : int¶: number of threads for parallelized random number generation

Returns:¶

array of market shares and other market statistics

Return type:¶

mergeron.gen.MarketSharesData

mergeron.gen.data_generation_functions.diversion_ratios_builder(_recapture_form, _recapture_rate, _frmshr_array, _aggregate_purchase_prob, /)[source]¶

Given merging-firm shares and related parameters, return diversion ratios.

If recapture is specified as mergeron.RECForm.OUTIN, then the choice-probability for the outside good must be supplied.

Parameters:¶

_recapture_form : mergeron.RECForm¶: Enum specifying Fixed (proportional), Inside-out, or Outside-in
_recapture_rate : float | None¶: If recapture is proportional or inside-out, the recapture rate for the firm with the smaller share.
_frmshr_array : mergeron.ArrayDouble¶: Merging-firm shares.
_aggregate_purchase_prob : mergeron.ArrayDouble¶: 1 minus probability that the outside good is chosen; converts market shares to choice probabilities by multiplication.

Raises:¶

ValueError – If the firm with the smaller share does not have the larger diversion ratio between the merging firms.

Returns:¶

Merging-firm diversion ratios for mergers in the sample.

Return type:¶

mergeron.ArrayDouble

mergeron.gen.data_generation_functions.prices_sampler(_frmshr_array, _nth_firm_share, _aggregate_purchase_prob, _pcm_spec, _price_spec, _hsr_filing_test_type, _pcm_rng_seed_seq, _pr_rng_seed_seq, _nthreads, /)[source]¶

Generate margin and price data for mergers in the sample.

Parameters:¶

_frmshr_array : mergeron.ArrayDouble¶: Merging-firm shares; see mergeron.gen.MarketShareSpec.
_nth_firm_share : mergeron.ArrayDouble¶: Share of the nth firm in the sample.
_aggregate_purchase_prob : mergeron.ArrayDouble¶: 1 minus probability that the outside good is chosen; converts market shares to choice probabilities by multiplication.
_pcm_spec : mergeron.gen.PCMSpec¶: Enum specifying whether to use asymmetric or flat margins. see mergeron.gen.PCMSpec.
_price_spec : mergeron.gen.PriceSpec¶: Enum specifying whether to use symmetric, positive, or negative margins; see mergeron.gen.PriceSpec.
_hsr_filing_test_type : mergeron.gen.SSZConstant¶: Enum specifying restriction, if any, to impose on market data sample to model HSR filing requirements; see mergeron.gen.SSZConstant.
_pcm_rng_seed_seq : numpy.random.SeedSequence¶: Seed sequence for generating margin data.
_pr_rng_seed_seq : numpy.random.SeedSequence | None¶: Seed sequence for generating price data.
_nthreads : int¶: Number of threads to use in generating price data.

Returns:¶

Simulated margin- and price-data arrays for mergers in the sample.

Return type:¶

tuple[mergeron.gen.MarginsData, mergeron.gen.PricesData]

mergeron.gen.data_generation_functions.beta_located_bound(_dist_parms, /)[source]¶

Return shape parameters for a non-standard beta, given mean, stddev, and range.

Recover the r.v.s as \(\min + (\max - \min) \cdot \symup{Β}(a, b)\), with a and b calculated from the specified mean (\(\mu\)) and variance (\(\sigma\)). [1]

Parameters:¶

_dist_parms : mergeron.ArrayDouble¶: vector of \(\mu\), \(\sigma\), \(\mathtt{\min}\), and \(\mathtt{\max}\) values

Returns:¶

shape parameters for Beta distribution

Return type:¶

mergeron.ArrayDouble

Notes

For example, beta_located_bound(np.array([0.5, 0.2887, 0.0, 1.0])).

References