use standard terminology

Author: janzill

activitysim/abm/models/util/bias_logsums.py

@@ -41,11 +41,11 @@ def maybe_bias_logsums(state: workflow.State, choices_df: pd.DataFrame, model_se
         else:
             logger.warning(
                 "Using Poisson sampling method for location choice logsum calculations. Currently the logsums results will"
-                + " differ from those obtained with monte_carlo or eet sampling by a constant shift of"
+                + " differ from those obtained with inverse_cdf or eet sampling by a constant shift of"
                 + f" log({model_settings.SAMPLE_SIZE}) if using the common correction factor"
                 + " `log(pick_count / prob)` in location choice specs. The results of the Poisson method are unbiased,"
                 + " i.e., they agree with the results obtained with a full destination sample, unlike those for"
-                + " monte_carlo or eet sampling."
+                + " inverse_cdf or eet sampling."
             )
 
     return choices_df

activitysim/core/configuration/base.py

@@ -135,12 +135,12 @@ class ComputeSettings(PydanticBase):
     Sharrow settings for a component.
     """
 
-    sample_method: None | Literal["monte_carlo", "eet", "poisson"] = None
+    sample_method: None | Literal["inverse_cdf", "eet", "poisson"] = None
     """
     Override the alternative sampling method used by `interaction_sample`.
 
     When unset, `interaction_sample` preserves legacy behavior: it uses
-    `monte_carlo` when explicit error terms are off and `poisson` when they
+    `inverse_cdf` when explicit error terms are off and `poisson` when they
     are on.
     """
 

activitysim/core/configuration/top.py

@@ -786,17 +786,18 @@ def _check_store_skims_in_shm(self):
     Make choice from random utility model by drawing from distribution of unobserved
     part of utility and taking the maximum of total utility.
 
-    Defaults to standard Monte Carlo method, i.e., calculating probabilities and then
-    drawing a single uniform random number to draw from cumulative probabily.
+    Defaults to the standard inverse-CDF (probability-based) method, i.e., calculating
+    probabilities and then drawing a single uniform random number against the
+    cumulative probability.
 
     .. versionadded:: 1.6
     """
 
-    sample_method: None | Literal["monte_carlo", "eet", "poisson"] = None
+    sample_method: None | Literal["inverse_cdf", "eet", "poisson"] = None
     """
     Sampling method to use in `activitysim.core.interaction_sample`.
 
-    When unset, `monte_carlo` is used when `use_explicit_error_terms` is false and
+    When unset, `inverse_cdf` is used when `use_explicit_error_terms` is false and
     `poisson` is used when it is true.
 
     .. versionadded:: 1.6
@@ -806,7 +807,7 @@ def _check_store_skims_in_shm(self):
     """
     Whether to apply a bias of `log(sample_size)` to the Poisson sampling results.
     This is a temporary workaround to align Poisson sampling results with the biased
-    results of the monte_carlo and eet sampling methods, such that models that were
+    results of the inverse_cdf and eet sampling methods, such that models that were
     estimated with historical biased sampling results can be run with Poisson sampling
     without needing to re-estimate the model.
 

activitysim/core/interaction_sample.py

@@ -31,7 +31,7 @@
 
 DUMP = False
 
-InteractionSampleMethod = typing.Literal["monte_carlo", "eet", "poisson"]
+InteractionSampleMethod = typing.Literal["inverse_cdf", "eet", "poisson"]
 
 # Threshold on P0, the probability that a chooser's Poisson draw comes up empty, below
 # which the fallback term is dropped from the reported inclusion probabilities. Choosers
@@ -82,7 +82,7 @@ def resolve_sample_method(
         sampling_method = state.settings.sample_method
     if sampling_method is None:
         sampling_method = (
-            "poisson" if state.settings.use_explicit_error_terms else "monte_carlo"
+            "poisson" if state.settings.use_explicit_error_terms else "inverse_cdf"
         )
     if sampling_method not in typing.get_args(InteractionSampleMethod):
         raise ValueError(
@@ -170,7 +170,7 @@ def make_sample_choices_eet(
 
     Each chooser receives `sample_size` EV1 draw sets and the argmax-over-utility
     winner is recorded per draw, so duplicates are possible (same with-replacement
-    semantics as the Monte Carlo sampling path).
+    semantics as the inverse-CDF sampling path).
 
     `utilities` drives the Gumbel argmax. `probs` (the MNL choice probabilities
     computed from the same utilities by the caller) supplies the `prob` column
@@ -229,7 +229,7 @@ def make_sample_choices_poisson(
 
     where `p_i` is the chooser's MNL choice probability for alternative `i`. That is the
     probability the alternative would have been drawn at least once across `sample_size`
-    Monte Carlo draws, which is what makes Poisson sampling interchangeable with the other
+    inverse-CDF draws, which is what makes Poisson sampling interchangeable with the other
     sampling methods. `pick_count` is 1 by definition (the draw is a yes/no per
     alternative), so the standard sampling correction factor is recoverable in the usual
     way as `np.log(df.pick_count / df.prob)`.
@@ -781,10 +781,10 @@ def _interaction_sample(
 
     sampling_method = resolve_sample_method(state, compute_settings)
 
-    # Estimation requires MC sampling and MC choice for now
-    if estimation.manager.enabled and sampling_method != "monte_carlo":
+    # Estimation requires inverse-CDF sampling and choice for now
+    if estimation.manager.enabled and sampling_method != "inverse_cdf":
         raise ValueError(
-            f"{trace_label}: estimation requires monte_carlo sampling and choice. Set sample_method='monte_carlo'"
+            f"{trace_label}: estimation requires inverse_cdf sampling and choice. Set sample_method='inverse_cdf'"
             + " (or leave it unset) and use_explicit_error_terms=False for estimation runs."
         )
 
@@ -835,7 +835,7 @@ def _interaction_sample(
             column_labels=["alternative", "probability"],
         )
 
-    if sampling_method == "monte_carlo":
+    if sampling_method == "inverse_cdf":
         del utilities
         chunk_sizer.log_df(trace_label, "utilities", None)
 
@@ -890,8 +890,8 @@ def _interaction_sample(
         del probs
         chunk_sizer.log_df(trace_label, "probs", None)
     else:
-        # eet and poisson: optionally trim choosers with all-zero probs. The MC
-        # path handles this inside make_sample_choices
+        # eet and poisson: optionally trim choosers with all-zero probs. The
+        # inverse-CDF path handles this inside make_sample_choices
         if allow_zero_probs:
             non_zero = probs.sum(axis=1) != 0
             if not non_zero.any():
@@ -1093,10 +1093,11 @@ def interaction_sample(
     sampling_method = resolve_sample_method(state, compute_settings)
     logger.debug(f" interaction_sample sample method = {sampling_method}")
 
-    if sampling_method == "monte_carlo":
-        # The MC sampling path (make_sample_choices) does not consume stable_alt_positions
-        # or n_total_alts. Null them out so callers that conservatively pass values along
-        # don't accidentally rely on them under MC sampling.
+    if sampling_method == "inverse_cdf":
+        # The inverse-CDF sampling path (make_sample_choices) does not consume
+        # stable_alt_positions or n_total_alts. Null them out so callers that
+        # conservatively pass values along don't accidentally rely on them under
+        # inverse-CDF sampling.
         stable_alt_positions = None
         n_total_alts = None
 

activitysim/core/interaction_sample_simulate.py

@@ -91,8 +91,7 @@ def _interaction_sample_simulate(
 
         choices : pandas.Series
             A series where index should match the index of the choosers DataFrame
-            and values will match the index of the alternatives DataFrame -
-            choices are simulated in the standard Monte Carlo fashion
+            and values will match the index of the alternatives DataFrame
 
     if want_logsums is True:
 
@@ -546,8 +545,7 @@ def interaction_sample_simulate(
 
         choices : pandas.Series
             A series where index should match the index of the choosers DataFrame
-            and values will match the index of the alternatives DataFrame -
-            choices are simulated in the standard Monte Carlo fashion
+            and values will match the index of the alternatives DataFrame
 
     if want_logsums is True:
 

activitysim/core/interaction_simulate.py

@@ -704,8 +704,7 @@ def _interaction_simulate(
     -------
     ret : pandas.Series
         A series where index should match the index of the choosers DataFrame
-        and values will match the index of the alternatives DataFrame -
-        choices are simulated in the standard Monte Carlo fashion
+        and values will match the index of the alternatives DataFrame
     """
 
     trace_label = tracing.extend_trace_label(trace_label, "interaction_simulate")
@@ -1031,8 +1030,7 @@ def interaction_simulate(
     -------
     choices : pandas.Series
         A series where index should match the index of the choosers DataFrame
-        and values will match the index of the alternatives DataFrame -
-        choices are simulated in the standard Monte Carlo fashion
+        and values will match the index of the alternatives DataFrame
     """
 
     trace_label = tracing.extend_trace_label(trace_label, "interaction_simulate")

activitysim/core/logit.py

@@ -690,15 +690,6 @@ def make_choices_utility_based(
     rands : pandas.Series
         A series of 0s for compatibility with make_choices. For EET, we do not have per-row random numbers.
 
-    Notes
-    -----
-    An argmax always returns a position, so a chooser with no available alternative gets a
-    choice here rather than an error: with every utility at `UTIL_UNAVAILABLE` the alternatives
-    are tied and the error terms decide, and with every utility at `-inf` the first column wins.
-    The Monte Carlo path does not go quiet in that situation -- `make_choices` reports it unless
-    `allow_bad_probs` is set -- so this function reports it too. Most callers reach here having
-    already run `validate_utils`, which makes the same check; the duplication is deliberate and
-    mirrors `make_choices` re-checking what `utils_to_probs` has already looked at.
     """
     trace_label = tracing.extend_trace_label(trace_label, "make_choices_utility_based")
 

activitysim/core/test/test_interaction_sample.py

@@ -23,7 +23,7 @@ def state() -> workflow.State:
 def test_interaction_sample_ignores_stable_positions_without_global_eet(
     state, monkeypatch
 ):
-    # Do not support stable alt positions or tracking total alts when running with MC sampling
+    # Do not support stable alt positions or tracking total alts when running with inverse-CDF sampling
     # to not introduce any additional changes while adding eet simulation support to ensure no
     # regressions. We can add these features later if desired.
     captured = {}
@@ -139,7 +139,7 @@ def test_interaction_sample_parity(state):
         index=pd.Index(["chooser_attr * alt_attr"], name="Expression"),
     )
 
-    # Run Monte Carlo with replacement.
+    # Run inverse-CDF sampling with replacement.
     state.settings.use_explicit_error_terms = False
     state.rng().set_base_seed(42)
     state.rng().add_channel("person_id", choosers)
@@ -198,14 +198,14 @@ def test_interaction_sample_parity(state):
     assert choices_eet["alt_id"].isin(alternatives.index).all()
 
     shares = {
-        "monte_carlo": _weighted_shares(choices_mnl),
+        "inverse_cdf": _weighted_shares(choices_mnl),
         "poisson": _weighted_shares(choices_poisson),
         "eet": _weighted_shares(choices_eet),
     }
 
     for left, right in [
-        ("monte_carlo", "poisson"),
-        ("monte_carlo", "eet"),
+        ("inverse_cdf", "poisson"),
+        ("inverse_cdf", "eet"),
         ("poisson", "eet"),
     ]:
         all_alts = set(shares[left].index) | set(shares[right].index)
@@ -428,7 +428,7 @@ def _shares_for_sample(
     return choices, _weighted_shares(choices)
 
 
-def test_interaction_sample_eet_sampling_under_mc_simulation(state):
+def test_interaction_sample_eet_sampling_under_inverse_cdf_simulation(state):
     # use_eet=False + sample_method="eet" was silently ignored before the
     # sampling/simulation decoupling. The dispatch now keys on sampling_method
     # only, so this combo must produce shares that match use_eet=True + eet.
@@ -483,9 +483,9 @@ def test_interaction_sample_eet_sampling_under_mc_simulation(state):
         )
 
 
-def test_interaction_sample_poisson_sampling_under_mc_simulation(state):
-    # use_eet=False + sample_method="poisson" used to silently fall through to MC
-    # sampling and then have pick_count forced to 1, corrupting results. After
+def test_interaction_sample_poisson_sampling_under_inverse_cdf_simulation(state):
+    # use_eet=False + sample_method="poisson" used to silently fall through to
+    # inverse-CDF sampling and then have pick_count forced to 1, corrupting results. After
     # decoupling, the combo must run the Poisson path and match use_eet=True + poisson.
     num_choosers = 100_000
     num_alts = 100
@@ -530,7 +530,7 @@ def test_interaction_sample_poisson_sampling_under_mc_simulation(state):
 
     # Poisson contract: pick_count must be uniformly 1
     assert (choices_mc_sim["pick_count"] == 1).all(), (
-        "Poisson sampling under MC simulation must produce pick_count=1; got "
+        "Poisson sampling under inverse-CDF simulation must produce pick_count=1; got "
         f"{choices_mc_sim['pick_count'].value_counts().to_dict()}"
     )
 
@@ -544,7 +544,7 @@ def test_interaction_sample_poisson_sampling_under_mc_simulation(state):
         )
 
 
-def test_interaction_sample_mc_sampling_under_eet_simulation(state):
+def test_interaction_sample_inverse_cdf_sampling_under_eet_simulation(state):
     num_choosers = 100_000
     num_alts = 100
     sample_size = 10
@@ -570,7 +570,7 @@ def test_interaction_sample_mc_sampling_under_eet_simulation(state):
         spec,
         sample_size,
         use_eet=False,
-        sample_method="monte_carlo",
+        sample_method="inverse_cdf",
         seed=42,
         step_name="test_mc_under_mc_sim",
     )
@@ -581,7 +581,7 @@ def test_interaction_sample_mc_sampling_under_eet_simulation(state):
         spec,
         sample_size,
         use_eet=True,
-        sample_method="monte_carlo",
+        sample_method="inverse_cdf",
         seed=42,
         step_name="test_mc_under_eet_sim",
     )
@@ -590,7 +590,7 @@ def test_interaction_sample_mc_sampling_under_eet_simulation(state):
     for alt in all_alts:
         diff = abs(shares_mc_sim.get(alt, 0.0) - shares_eet_sim.get(alt, 0.0))
         assert diff < 0.01, (
-            f"MC sampling shares should not depend on simulation mode at alt {alt}: "
+            f"Inverse-CDF sampling shares should not depend on simulation mode at alt {alt}: "
             f"mc_sim={shares_mc_sim.get(alt, 0.0):.4f}, "
             f"eet_sim={shares_eet_sim.get(alt, 0.0):.4f}, diff={diff:.4f}"
         )

activitysim/core/test/test_logit.py

@@ -683,7 +683,7 @@ def test_make_choices_vs_eet_same_distribution():
 
     utils = pd.DataFrame([utils_values] * n_draws, columns=columns)
 
-    # Probability-based (Monte Carlo) path — independent RNG
+    # Probability-based (inverse-CDF) path — independent RNG
     mc_rng = np.random.default_rng(42)
 
     class MCDummyRNG: