SearchLibrium 0.0.273__tar.gz → 0.0.274__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {searchlibrium-0.0.273/src/SearchLibrium.egg-info → searchlibrium-0.0.274}/PKG-INFO +216 -3
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/README.md +215 -2
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/pyproject.toml +1 -1
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/MixedLogit.py +7 -2
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/__init__.py +12 -0
- searchlibrium-0.0.274/src/SearchLibrium/delphos.py +773 -0
- searchlibrium-0.0.274/src/SearchLibrium/delphos_q.py +605 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/latent_class.py +57 -15
- searchlibrium-0.0.274/src/SearchLibrium/lc_ml.py +777 -0
- searchlibrium-0.0.274/src/SearchLibrium/llm.py +1794 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/multinomial_logit.py +43 -1
- searchlibrium-0.0.274/src/SearchLibrium/route_choice.py +164 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/search.py +133 -34
- searchlibrium-0.0.274/src/SearchLibrium/spec_grammar.py +449 -0
- searchlibrium-0.0.274/src/SearchLibrium/version.txt +1 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274/src/SearchLibrium.egg-info}/PKG-INFO +216 -3
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/SOURCES.txt +13 -0
- searchlibrium-0.0.274/tests/test_delphos.py +392 -0
- searchlibrium-0.0.274/tests/test_delphos_q.py +169 -0
- searchlibrium-0.0.274/tests/test_lc_membership_intercept.py +78 -0
- searchlibrium-0.0.274/tests/test_lc_ml.py +132 -0
- searchlibrium-0.0.274/tests/test_llm_assistant.py +204 -0
- searchlibrium-0.0.274/tests/test_route_choice.py +76 -0
- searchlibrium-0.0.274/tests/test_spec_grammar.py +102 -0
- searchlibrium-0.0.273/src/SearchLibrium/version.txt +0 -1
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/LICENSE +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/MANIFEST.in +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/setup.cfg +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/BEHier.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/Halton.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/MixedLogitGSE.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/Mode_Activity_Nested.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/RandomP.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/SEARCH_SM_MARIO.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/Two_Level_Nest.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/__main__.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/_choice_model.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/_device.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/abm.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/accessibility.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/banditsa.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/boxcox_functions.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/call_meta.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/constraints_builder.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/coupled_solver.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/data/Swissmetro_final.csv +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/data/TravelMode.csv +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/data/electricity.csv +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/destination_distances.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/harmony.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/hspbil.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/jax_utils.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/larch_compat.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/larch_models.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/latent_spec.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/lc_rail_guard.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/logistic_regression.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/main.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/main_debug.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/mdcev.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/mh_choice_estimator.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/misc.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/mixed_logit.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/mixed_nested.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/mixedrrm.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/multinomial_nested.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/multinomial_probit.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/numba_engine.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/numba_mxl.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/numba_rrm.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/ordered_logit.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/ordered_logit_mixed.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/predict.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/regularization.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/rrm.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/sample_data.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/sapbil.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/selection_models.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/setup.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/siman.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/skims.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/sparseea_agds.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/test_lc_de.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/test_mario_searches.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/test_sapbil_vs_banditsa.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/threshold.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium/zero_inflated_ordered_probit.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/dependency_links.txt +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/entry_points.txt +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/requires.txt +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/src/SearchLibrium.egg-info/top_level.txt +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/tests/test_destination_distances.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/tests/test_jax_mask_equivalence.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/tests/test_larch_compat.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/tests/test_larch_integration.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/tests/test_lc_smart_init.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/tests/test_mh_choice_estimator.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/tests/test_mxl_random_starts.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/tests/test_per_alternative_random.py +0 -0
- {searchlibrium-0.0.273 → searchlibrium-0.0.274}/tests/test_zero_inflated_ordered_probit.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: SearchLibrium
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.274
|
|
4
4
|
Summary: Automated specification search for discrete choice models (logit, mixed logit, nested logit, RRM and more) using metaheuristic optimisation
|
|
5
5
|
Author: Zeke Ahern, Mario Fernando Taco Morales, Alexander Paz, Prithvi Beeramole, Robert Burdett
|
|
6
6
|
Maintainer-email: Zeke Ahern <z.ahern@qut.edu.au>
|
|
@@ -104,8 +104,10 @@ estimation of each candidate model.
|
|
|
104
104
|
12. [Bundled datasets](#bundled-datasets)
|
|
105
105
|
13. [CLI](#cli)
|
|
106
106
|
14. [Differential Evolution warm start](#differential-evolution-warm-start)
|
|
107
|
-
15. [
|
|
108
|
-
16. [
|
|
107
|
+
15. [ML-guided latent classes](#ml-guided-latent-classes)
|
|
108
|
+
16. [LLM-assisted experiment setup](#llm-assisted-experiment-setup)
|
|
109
|
+
17. [Troubleshooting & FAQ](#troubleshooting--faq)
|
|
110
|
+
18. [License](#license) / [Citation](#citation)
|
|
109
111
|
|
|
110
112
|
---
|
|
111
113
|
|
|
@@ -581,6 +583,217 @@ You can also pass `de_init=False` explicitly to guarantee it stays off.
|
|
|
581
583
|
|
|
582
584
|
---
|
|
583
585
|
|
|
586
|
+
## ML-guided latent classes
|
|
587
|
+
|
|
588
|
+
`SearchLibrium.lc_ml` implements a practical answer to *"what is the class-membership
|
|
589
|
+
model, and what is the best choice model inside each class?"*:
|
|
590
|
+
|
|
591
|
+
1. **Fit latent classes** with EM (`fit_latent_classes`). The posterior class
|
|
592
|
+
probabilities define behaviourally distinct segments without imposing a
|
|
593
|
+
membership equation.
|
|
594
|
+
2. **Discover the membership model with ML** (`discover_membership`). An Extra
|
|
595
|
+
Trees classifier (or Random Forest) predicts class membership from
|
|
596
|
+
person/household covariates. You get cross-validated AUC / accuracy /
|
|
597
|
+
log-loss, permutation importance, a compact multinomial logit and
|
|
598
|
+
decision-tree rules.
|
|
599
|
+
3. **Search inside each class** (`search_within_classes`). People are assigned
|
|
600
|
+
to their most likely class, and the ordinary SearchLibrium search runs
|
|
601
|
+
independently inside every class. Each class gets its own best MNL/MXL/RRM/...
|
|
602
|
+
specification.
|
|
603
|
+
4. **Or search jointly** (`search_joint_latent_class`). The ML-discovered
|
|
604
|
+
membership covariates seed a latent-class specification search in which
|
|
605
|
+
SearchLibrium also searches the per-class utility specifications.
|
|
606
|
+
|
|
607
|
+
```python
|
|
608
|
+
from SearchLibrium import (
|
|
609
|
+
fit_latent_classes, discover_membership, search_within_classes,
|
|
610
|
+
)
|
|
611
|
+
|
|
612
|
+
# long_df: balanced long format, one row per alternative per choice task
|
|
613
|
+
# person_frame: one row per person/panel, indexed by the panel id
|
|
614
|
+
lc = fit_latent_classes(
|
|
615
|
+
long_df,
|
|
616
|
+
utility_vars=["TIME", "COST", "ASC_TRAIN", "ASC_BUS"],
|
|
617
|
+
n_classes=2, n_init=2, maxiter=120,
|
|
618
|
+
)
|
|
619
|
+
|
|
620
|
+
disc = discover_membership(
|
|
621
|
+
lc, person_frame,
|
|
622
|
+
candidate_vars=["INCOME", "CARS", "AGE", "LICENCE", "WORKSTATUS"],
|
|
623
|
+
top_k=5,
|
|
624
|
+
)
|
|
625
|
+
print(disc.summary()) # CV scores + importance + decision rules
|
|
626
|
+
print(disc.selected_vars) # the discovered membership covariates
|
|
627
|
+
|
|
628
|
+
# Assign each person to a class, then run the usual search per class.
|
|
629
|
+
assignment = dict(zip(lc.panel_ids, disc.hard_labels))
|
|
630
|
+
per_class = search_within_classes(
|
|
631
|
+
long_df, assignment,
|
|
632
|
+
utility_vars=["TIME", "COST", "ASC_TRAIN", "ASC_BUS"],
|
|
633
|
+
models=["multinomial"], criterions=[("bic", -1)],
|
|
634
|
+
ctrl=(300, 0.01, 15, 10),
|
|
635
|
+
)
|
|
636
|
+
for cls, best in per_class.items():
|
|
637
|
+
print(cls, best["asvars"], best["bic"])
|
|
638
|
+
```
|
|
639
|
+
|
|
640
|
+
Notes:
|
|
641
|
+
|
|
642
|
+
- Class labels are estimated, so `discover_membership` scores are
|
|
643
|
+
*pseudo-label* scores unless you fit the LC model on a training split and
|
|
644
|
+
evaluate the classifier on held-out people.
|
|
645
|
+
- `search_within_classes` uses hard assignments; `search_joint_latent_class`
|
|
646
|
+
keeps the soft membership equation.
|
|
647
|
+
- Use a held-out choice log-likelihood to compare the pooled and segmented
|
|
648
|
+
models; per-class BICs are not directly comparable to a pooled BIC.
|
|
649
|
+
- A complete HHTS mode-choice example, including pooled-vs-segmented test
|
|
650
|
+
log-likelihood and soft-membership prediction, is in
|
|
651
|
+
`benchmarks/lc_ml_hhts.py`:
|
|
652
|
+
|
|
653
|
+
```bash
|
|
654
|
+
python benchmarks/lc_ml_hhts.py --classes 2 --ctrl 300,0.01,15,10
|
|
655
|
+
```
|
|
656
|
+
|
|
657
|
+
`membership_intercept=True` on `LatentClassMixedLogit` (or `'_inter'` in a
|
|
658
|
+
membership spec) adds the class-share constant to the membership equation.
|
|
659
|
+
|
|
660
|
+
---
|
|
661
|
+
|
|
662
|
+
## LLM-assisted experiment setup
|
|
663
|
+
|
|
664
|
+
Yes — the package ships an optional, provider-agnostic experiment assistant.
|
|
665
|
+
It drives the *setup* conversation (data path → response → model classes →
|
|
666
|
+
variable pruning → constraint hierarchy → objective), then runs the ordinary
|
|
667
|
+
SearchLibrium search, diagnoses the result, and can revise the constraints for
|
|
668
|
+
another round.
|
|
669
|
+
|
|
670
|
+
The LLM is **not required**. With no API key it uses a deterministic offline
|
|
671
|
+
planner. With a provider configured it receives only the schema and summary
|
|
672
|
+
statistics by default — never your rows.
|
|
673
|
+
|
|
674
|
+
```python
|
|
675
|
+
from SearchLibrium import ExperimentAssistant, LLMConfig
|
|
676
|
+
|
|
677
|
+
exp = ExperimentAssistant(
|
|
678
|
+
data=r"C:\data\mode_choice.csv",
|
|
679
|
+
response="choice", # the count/response column
|
|
680
|
+
config=LLMConfig.from_env(), # offline if nothing is configured
|
|
681
|
+
)
|
|
682
|
+
|
|
683
|
+
print(exp.profile().summary()) # file shape, dtypes, missingness
|
|
684
|
+
print(exp.roles().summary()) # choice / alt / ids / AS / IS
|
|
685
|
+
|
|
686
|
+
plan = exp.plan() # models, variables, constraints,
|
|
687
|
+
# objectives, open questions
|
|
688
|
+
print(plan.summary())
|
|
689
|
+
|
|
690
|
+
best = exp.run(plan) # ordinary, full SearchLibrium search
|
|
691
|
+
issues = exp.diagnose(best) # non-convergence, singularity,
|
|
692
|
+
# class collapse, insignificance, ...
|
|
693
|
+
print(issues)
|
|
694
|
+
plan = exp.revise(issues) # apply suggested constraints
|
|
695
|
+
best = exp.run(plan) # retry with the revised plan
|
|
696
|
+
```
|
|
697
|
+
|
|
698
|
+
Interactive mode asks the questions directly:
|
|
699
|
+
|
|
700
|
+
```python
|
|
701
|
+
exp = ExperimentAssistant(interactive=True)
|
|
702
|
+
exp.chat()
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
Provider configuration is via `LLMConfig` or standard environment variables:
|
|
706
|
+
|
|
707
|
+
| Provider | Configuration |
|
|
708
|
+
| --- | --- |
|
|
709
|
+
| OpenAI / OpenAI-compatible | `OPENAI_API_KEY`, or `LLMConfig(provider="openai", model="gpt-4o-mini")` |
|
|
710
|
+
| Anthropic | `ANTHROPIC_API_KEY`, or `LLMConfig(provider="anthropic")` |
|
|
711
|
+
| Ollama (local) | `OLLAMA_HOST`, or `LLMConfig(provider="ollama")` |
|
|
712
|
+
| Downloaded GGUF (local) | `LLMConfig(provider="local", model_path=r"C:\models\model.gguf")` |
|
|
713
|
+
| Custom endpoint | `LLMConfig(provider="custom", base_url=..., api_key=...)` |
|
|
714
|
+
| Offline (default) | no configuration; deterministic planner |
|
|
715
|
+
|
|
716
|
+
### Using a free downloaded local LLM
|
|
717
|
+
|
|
718
|
+
The simplest route is **Ollama** (free, no API key):
|
|
719
|
+
|
|
720
|
+
```bash
|
|
721
|
+
ollama pull qwen2.5:7b-instruct
|
|
722
|
+
```
|
|
723
|
+
|
|
724
|
+
```python
|
|
725
|
+
from SearchLibrium import ExperimentAssistant, LLMConfig
|
|
726
|
+
|
|
727
|
+
exp = ExperimentAssistant(
|
|
728
|
+
data=r"C:\data\mode_choice.csv",
|
|
729
|
+
response="choice",
|
|
730
|
+
config=LLMConfig(provider="ollama", model="qwen2.5:7b-instruct"),
|
|
731
|
+
)
|
|
732
|
+
```
|
|
733
|
+
|
|
734
|
+
If you already have a **GGUF file** (e.g. from Hugging Face, LM Studio, or
|
|
735
|
+
TheBloke), use the direct local backend:
|
|
736
|
+
|
|
737
|
+
```bash
|
|
738
|
+
pip install llama-cpp-python
|
|
739
|
+
```
|
|
740
|
+
|
|
741
|
+
```python
|
|
742
|
+
from SearchLibrium import ExperimentAssistant, LLMConfig, find_local_models
|
|
743
|
+
|
|
744
|
+
# Optional: search common model folders for *.gguf files.
|
|
745
|
+
print(find_local_models(r"C:\models"))
|
|
746
|
+
|
|
747
|
+
exp = ExperimentAssistant(
|
|
748
|
+
data=r"C:\data\mode_choice.csv",
|
|
749
|
+
response="choice",
|
|
750
|
+
config=LLMConfig(
|
|
751
|
+
provider="local",
|
|
752
|
+
model_path=r"C:\models\Qwen2.5-7B-Instruct-Q4_K_M.gguf",
|
|
753
|
+
n_ctx=8192,
|
|
754
|
+
n_gpu_layers=-1, # offload all layers when the build supports it
|
|
755
|
+
),
|
|
756
|
+
)
|
|
757
|
+
```
|
|
758
|
+
|
|
759
|
+
LM Studio is also free and exposes an OpenAI-compatible local server:
|
|
760
|
+
|
|
761
|
+
```python
|
|
762
|
+
LLMConfig(
|
|
763
|
+
provider="custom",
|
|
764
|
+
base_url="http://localhost:1234/v1",
|
|
765
|
+
api_key="lm-studio",
|
|
766
|
+
model="local-model",
|
|
767
|
+
)
|
|
768
|
+
```
|
|
769
|
+
|
|
770
|
+
Suggested small models for experiment planning: **Qwen2.5-7B-Instruct**,
|
|
771
|
+
**Llama-3.1-8B-Instruct**, **Mistral-7B-Instruct**, or **Phi-3.5-mini**.
|
|
772
|
+
A 4-bit quantised 7B/8B model runs on a normal laptop CPU (slowly) or a
|
|
773
|
+
reasonably sized GPU. Once the model is downloaded, setup and planning are
|
|
774
|
+
fully offline; only the schema/summary is sent to the model.
|
|
775
|
+
|
|
776
|
+
Useful details:
|
|
777
|
+
|
|
778
|
+
- `ExperimentAssistant.plan(answers={...})` accepts explicit overrides such as
|
|
779
|
+
`models`, `objectives`, `p_val`, `allow_random`, `force_include`,
|
|
780
|
+
`force_exclude`, `mutually_exclusive` and `min_behavioral`.
|
|
781
|
+
- `diagnose` returns machine-readable `Issue` objects with a `patch` that
|
|
782
|
+
`revise` can apply (e.g. add a mutual-exclusion constraint, increase
|
|
783
|
+
`maxiter`, reduce the number of latent classes).
|
|
784
|
+
- `run_loop(max_rounds=3)` automates run → diagnose → revise → re-run.
|
|
785
|
+
- `send_data=False` (the default) keeps raw values local; only column names,
|
|
786
|
+
dtypes and summary statistics are sent to a remote provider.
|
|
787
|
+
- `read_table` supports CSV/TSV, Parquet, pickle, JSON, Excel and Stata.
|
|
788
|
+
|
|
789
|
+
A zero-configuration demo on the bundled travel-mode dataset:
|
|
790
|
+
|
|
791
|
+
```bash
|
|
792
|
+
python benchmarks/llm_setup_demo.py
|
|
793
|
+
```
|
|
794
|
+
|
|
795
|
+
---
|
|
796
|
+
|
|
584
797
|
## Troubleshooting & FAQ
|
|
585
798
|
|
|
586
799
|
**A model reports `converged: False`.**
|
|
@@ -37,8 +37,10 @@ estimation of each candidate model.
|
|
|
37
37
|
12. [Bundled datasets](#bundled-datasets)
|
|
38
38
|
13. [CLI](#cli)
|
|
39
39
|
14. [Differential Evolution warm start](#differential-evolution-warm-start)
|
|
40
|
-
15. [
|
|
41
|
-
16. [
|
|
40
|
+
15. [ML-guided latent classes](#ml-guided-latent-classes)
|
|
41
|
+
16. [LLM-assisted experiment setup](#llm-assisted-experiment-setup)
|
|
42
|
+
17. [Troubleshooting & FAQ](#troubleshooting--faq)
|
|
43
|
+
18. [License](#license) / [Citation](#citation)
|
|
42
44
|
|
|
43
45
|
---
|
|
44
46
|
|
|
@@ -514,6 +516,217 @@ You can also pass `de_init=False` explicitly to guarantee it stays off.
|
|
|
514
516
|
|
|
515
517
|
---
|
|
516
518
|
|
|
519
|
+
## ML-guided latent classes
|
|
520
|
+
|
|
521
|
+
`SearchLibrium.lc_ml` implements a practical answer to *"what is the class-membership
|
|
522
|
+
model, and what is the best choice model inside each class?"*:
|
|
523
|
+
|
|
524
|
+
1. **Fit latent classes** with EM (`fit_latent_classes`). The posterior class
|
|
525
|
+
probabilities define behaviourally distinct segments without imposing a
|
|
526
|
+
membership equation.
|
|
527
|
+
2. **Discover the membership model with ML** (`discover_membership`). An Extra
|
|
528
|
+
Trees classifier (or Random Forest) predicts class membership from
|
|
529
|
+
person/household covariates. You get cross-validated AUC / accuracy /
|
|
530
|
+
log-loss, permutation importance, a compact multinomial logit and
|
|
531
|
+
decision-tree rules.
|
|
532
|
+
3. **Search inside each class** (`search_within_classes`). People are assigned
|
|
533
|
+
to their most likely class, and the ordinary SearchLibrium search runs
|
|
534
|
+
independently inside every class. Each class gets its own best MNL/MXL/RRM/...
|
|
535
|
+
specification.
|
|
536
|
+
4. **Or search jointly** (`search_joint_latent_class`). The ML-discovered
|
|
537
|
+
membership covariates seed a latent-class specification search in which
|
|
538
|
+
SearchLibrium also searches the per-class utility specifications.
|
|
539
|
+
|
|
540
|
+
```python
|
|
541
|
+
from SearchLibrium import (
|
|
542
|
+
fit_latent_classes, discover_membership, search_within_classes,
|
|
543
|
+
)
|
|
544
|
+
|
|
545
|
+
# long_df: balanced long format, one row per alternative per choice task
|
|
546
|
+
# person_frame: one row per person/panel, indexed by the panel id
|
|
547
|
+
lc = fit_latent_classes(
|
|
548
|
+
long_df,
|
|
549
|
+
utility_vars=["TIME", "COST", "ASC_TRAIN", "ASC_BUS"],
|
|
550
|
+
n_classes=2, n_init=2, maxiter=120,
|
|
551
|
+
)
|
|
552
|
+
|
|
553
|
+
disc = discover_membership(
|
|
554
|
+
lc, person_frame,
|
|
555
|
+
candidate_vars=["INCOME", "CARS", "AGE", "LICENCE", "WORKSTATUS"],
|
|
556
|
+
top_k=5,
|
|
557
|
+
)
|
|
558
|
+
print(disc.summary()) # CV scores + importance + decision rules
|
|
559
|
+
print(disc.selected_vars) # the discovered membership covariates
|
|
560
|
+
|
|
561
|
+
# Assign each person to a class, then run the usual search per class.
|
|
562
|
+
assignment = dict(zip(lc.panel_ids, disc.hard_labels))
|
|
563
|
+
per_class = search_within_classes(
|
|
564
|
+
long_df, assignment,
|
|
565
|
+
utility_vars=["TIME", "COST", "ASC_TRAIN", "ASC_BUS"],
|
|
566
|
+
models=["multinomial"], criterions=[("bic", -1)],
|
|
567
|
+
ctrl=(300, 0.01, 15, 10),
|
|
568
|
+
)
|
|
569
|
+
for cls, best in per_class.items():
|
|
570
|
+
print(cls, best["asvars"], best["bic"])
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
Notes:
|
|
574
|
+
|
|
575
|
+
- Class labels are estimated, so `discover_membership` scores are
|
|
576
|
+
*pseudo-label* scores unless you fit the LC model on a training split and
|
|
577
|
+
evaluate the classifier on held-out people.
|
|
578
|
+
- `search_within_classes` uses hard assignments; `search_joint_latent_class`
|
|
579
|
+
keeps the soft membership equation.
|
|
580
|
+
- Use a held-out choice log-likelihood to compare the pooled and segmented
|
|
581
|
+
models; per-class BICs are not directly comparable to a pooled BIC.
|
|
582
|
+
- A complete HHTS mode-choice example, including pooled-vs-segmented test
|
|
583
|
+
log-likelihood and soft-membership prediction, is in
|
|
584
|
+
`benchmarks/lc_ml_hhts.py`:
|
|
585
|
+
|
|
586
|
+
```bash
|
|
587
|
+
python benchmarks/lc_ml_hhts.py --classes 2 --ctrl 300,0.01,15,10
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
`membership_intercept=True` on `LatentClassMixedLogit` (or `'_inter'` in a
|
|
591
|
+
membership spec) adds the class-share constant to the membership equation.
|
|
592
|
+
|
|
593
|
+
---
|
|
594
|
+
|
|
595
|
+
## LLM-assisted experiment setup
|
|
596
|
+
|
|
597
|
+
Yes — the package ships an optional, provider-agnostic experiment assistant.
|
|
598
|
+
It drives the *setup* conversation (data path → response → model classes →
|
|
599
|
+
variable pruning → constraint hierarchy → objective), then runs the ordinary
|
|
600
|
+
SearchLibrium search, diagnoses the result, and can revise the constraints for
|
|
601
|
+
another round.
|
|
602
|
+
|
|
603
|
+
The LLM is **not required**. With no API key it uses a deterministic offline
|
|
604
|
+
planner. With a provider configured it receives only the schema and summary
|
|
605
|
+
statistics by default — never your rows.
|
|
606
|
+
|
|
607
|
+
```python
|
|
608
|
+
from SearchLibrium import ExperimentAssistant, LLMConfig
|
|
609
|
+
|
|
610
|
+
exp = ExperimentAssistant(
|
|
611
|
+
data=r"C:\data\mode_choice.csv",
|
|
612
|
+
response="choice", # the count/response column
|
|
613
|
+
config=LLMConfig.from_env(), # offline if nothing is configured
|
|
614
|
+
)
|
|
615
|
+
|
|
616
|
+
print(exp.profile().summary()) # file shape, dtypes, missingness
|
|
617
|
+
print(exp.roles().summary()) # choice / alt / ids / AS / IS
|
|
618
|
+
|
|
619
|
+
plan = exp.plan() # models, variables, constraints,
|
|
620
|
+
# objectives, open questions
|
|
621
|
+
print(plan.summary())
|
|
622
|
+
|
|
623
|
+
best = exp.run(plan) # ordinary, full SearchLibrium search
|
|
624
|
+
issues = exp.diagnose(best) # non-convergence, singularity,
|
|
625
|
+
# class collapse, insignificance, ...
|
|
626
|
+
print(issues)
|
|
627
|
+
plan = exp.revise(issues) # apply suggested constraints
|
|
628
|
+
best = exp.run(plan) # retry with the revised plan
|
|
629
|
+
```
|
|
630
|
+
|
|
631
|
+
Interactive mode asks the questions directly:
|
|
632
|
+
|
|
633
|
+
```python
|
|
634
|
+
exp = ExperimentAssistant(interactive=True)
|
|
635
|
+
exp.chat()
|
|
636
|
+
```
|
|
637
|
+
|
|
638
|
+
Provider configuration is via `LLMConfig` or standard environment variables:
|
|
639
|
+
|
|
640
|
+
| Provider | Configuration |
|
|
641
|
+
| --- | --- |
|
|
642
|
+
| OpenAI / OpenAI-compatible | `OPENAI_API_KEY`, or `LLMConfig(provider="openai", model="gpt-4o-mini")` |
|
|
643
|
+
| Anthropic | `ANTHROPIC_API_KEY`, or `LLMConfig(provider="anthropic")` |
|
|
644
|
+
| Ollama (local) | `OLLAMA_HOST`, or `LLMConfig(provider="ollama")` |
|
|
645
|
+
| Downloaded GGUF (local) | `LLMConfig(provider="local", model_path=r"C:\models\model.gguf")` |
|
|
646
|
+
| Custom endpoint | `LLMConfig(provider="custom", base_url=..., api_key=...)` |
|
|
647
|
+
| Offline (default) | no configuration; deterministic planner |
|
|
648
|
+
|
|
649
|
+
### Using a free downloaded local LLM
|
|
650
|
+
|
|
651
|
+
The simplest route is **Ollama** (free, no API key):
|
|
652
|
+
|
|
653
|
+
```bash
|
|
654
|
+
ollama pull qwen2.5:7b-instruct
|
|
655
|
+
```
|
|
656
|
+
|
|
657
|
+
```python
|
|
658
|
+
from SearchLibrium import ExperimentAssistant, LLMConfig
|
|
659
|
+
|
|
660
|
+
exp = ExperimentAssistant(
|
|
661
|
+
data=r"C:\data\mode_choice.csv",
|
|
662
|
+
response="choice",
|
|
663
|
+
config=LLMConfig(provider="ollama", model="qwen2.5:7b-instruct"),
|
|
664
|
+
)
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
If you already have a **GGUF file** (e.g. from Hugging Face, LM Studio, or
|
|
668
|
+
TheBloke), use the direct local backend:
|
|
669
|
+
|
|
670
|
+
```bash
|
|
671
|
+
pip install llama-cpp-python
|
|
672
|
+
```
|
|
673
|
+
|
|
674
|
+
```python
|
|
675
|
+
from SearchLibrium import ExperimentAssistant, LLMConfig, find_local_models
|
|
676
|
+
|
|
677
|
+
# Optional: search common model folders for *.gguf files.
|
|
678
|
+
print(find_local_models(r"C:\models"))
|
|
679
|
+
|
|
680
|
+
exp = ExperimentAssistant(
|
|
681
|
+
data=r"C:\data\mode_choice.csv",
|
|
682
|
+
response="choice",
|
|
683
|
+
config=LLMConfig(
|
|
684
|
+
provider="local",
|
|
685
|
+
model_path=r"C:\models\Qwen2.5-7B-Instruct-Q4_K_M.gguf",
|
|
686
|
+
n_ctx=8192,
|
|
687
|
+
n_gpu_layers=-1, # offload all layers when the build supports it
|
|
688
|
+
),
|
|
689
|
+
)
|
|
690
|
+
```
|
|
691
|
+
|
|
692
|
+
LM Studio is also free and exposes an OpenAI-compatible local server:
|
|
693
|
+
|
|
694
|
+
```python
|
|
695
|
+
LLMConfig(
|
|
696
|
+
provider="custom",
|
|
697
|
+
base_url="http://localhost:1234/v1",
|
|
698
|
+
api_key="lm-studio",
|
|
699
|
+
model="local-model",
|
|
700
|
+
)
|
|
701
|
+
```
|
|
702
|
+
|
|
703
|
+
Suggested small models for experiment planning: **Qwen2.5-7B-Instruct**,
|
|
704
|
+
**Llama-3.1-8B-Instruct**, **Mistral-7B-Instruct**, or **Phi-3.5-mini**.
|
|
705
|
+
A 4-bit quantised 7B/8B model runs on a normal laptop CPU (slowly) or a
|
|
706
|
+
reasonably sized GPU. Once the model is downloaded, setup and planning are
|
|
707
|
+
fully offline; only the schema/summary is sent to the model.
|
|
708
|
+
|
|
709
|
+
Useful details:
|
|
710
|
+
|
|
711
|
+
- `ExperimentAssistant.plan(answers={...})` accepts explicit overrides such as
|
|
712
|
+
`models`, `objectives`, `p_val`, `allow_random`, `force_include`,
|
|
713
|
+
`force_exclude`, `mutually_exclusive` and `min_behavioral`.
|
|
714
|
+
- `diagnose` returns machine-readable `Issue` objects with a `patch` that
|
|
715
|
+
`revise` can apply (e.g. add a mutual-exclusion constraint, increase
|
|
716
|
+
`maxiter`, reduce the number of latent classes).
|
|
717
|
+
- `run_loop(max_rounds=3)` automates run → diagnose → revise → re-run.
|
|
718
|
+
- `send_data=False` (the default) keeps raw values local; only column names,
|
|
719
|
+
dtypes and summary statistics are sent to a remote provider.
|
|
720
|
+
- `read_table` supports CSV/TSV, Parquet, pickle, JSON, Excel and Stata.
|
|
721
|
+
|
|
722
|
+
A zero-configuration demo on the bundled travel-mode dataset:
|
|
723
|
+
|
|
724
|
+
```bash
|
|
725
|
+
python benchmarks/llm_setup_demo.py
|
|
726
|
+
```
|
|
727
|
+
|
|
728
|
+
---
|
|
729
|
+
|
|
517
730
|
## Troubleshooting & FAQ
|
|
518
731
|
|
|
519
732
|
**A model reports `converged: False`.**
|
|
@@ -132,7 +132,7 @@ Documentation = "https://pypi.org/project/SearchLibrium/"
|
|
|
132
132
|
realpython = "SearchLibrium.__main__:main"
|
|
133
133
|
|
|
134
134
|
[tool.bumpver]
|
|
135
|
-
current_version = "0.0.
|
|
135
|
+
current_version = "0.0.274"
|
|
136
136
|
version_pattern = "MAJOR.MINOR.PATCH"
|
|
137
137
|
commit_message = "[skip ci] Bump version {old_version} -> {new_version}"
|
|
138
138
|
commit = true
|
|
@@ -339,8 +339,13 @@ class MixedLogit(DiscreteChoiceModel):
|
|
|
339
339
|
self._person_batch_active = False
|
|
340
340
|
self.draw_seed = int(draw_seed)
|
|
341
341
|
self.halton_opts = dict(halton_opts or {})
|
|
342
|
-
|
|
343
|
-
|
|
342
|
+
# Always seed the draw stream. Draws default to scrambled Sobol,
|
|
343
|
+
# whose scramble is fresh entropy whenever the seed is None, so an
|
|
344
|
+
# identical specification fitted in two processes returned different
|
|
345
|
+
# log-likelihoods (TravelMode, 200 draws: -193.55 vs -193.48). A
|
|
346
|
+
# search that is trained on such a reward is fitting the draw noise.
|
|
347
|
+
# ``draw_seed`` defaults to 0, so this is stable for existing callers.
|
|
348
|
+
self.halton_opts.setdefault("seed", self.draw_seed)
|
|
344
349
|
|
|
345
350
|
# CRITICAL FIX: Recreate draws_generator with proper halton_opts AND rvdist
|
|
346
351
|
# The __init__ creates it with halton_opts=None, but setup() gets the actual options
|
|
@@ -170,6 +170,13 @@ _IMPORT_GROUPS = [
|
|
|
170
170
|
('zero_inflated_ordered_probit', ['ZeroInflatedOrderedProbit',
|
|
171
171
|
'ZeroInflatedProbit']),
|
|
172
172
|
('latent_class', ['LatentClassMixedLogit']),
|
|
173
|
+
('lc_ml', ['MembershipDiscovery', 'discover_membership',
|
|
174
|
+
'fit_latent_classes', 'search_within_classes',
|
|
175
|
+
'search_joint_latent_class']),
|
|
176
|
+
('llm', ['ExperimentAssistant', 'LLMConfig', 'LLMClient', 'LLMUnavailable',
|
|
177
|
+
'DataProfile', 'DataRoles', 'ExperimentPlan', 'Issue',
|
|
178
|
+
'read_table', 'profile_frame', 'infer_data_roles',
|
|
179
|
+
'find_local_models']),
|
|
173
180
|
('lc_rail_guard', ['lc_result_rail']),
|
|
174
181
|
('latent_spec', ['vip_table', 'near_unidentified_report', 'align_classes',
|
|
175
182
|
'propose_class_params_spec']),
|
|
@@ -239,6 +246,11 @@ __all__ = [
|
|
|
239
246
|
"ZeroInflatedOrderedProbit", "ZeroInflatedProbit",
|
|
240
247
|
"LatentClassMixedLogit", "vip_table", "near_unidentified_report",
|
|
241
248
|
"align_classes", "propose_class_params_spec", "MDCEVFitResult", "MDCEVModel", "MultinomialProbit",
|
|
249
|
+
"MembershipDiscovery", "discover_membership", "fit_latent_classes",
|
|
250
|
+
"search_within_classes", "search_joint_latent_class",
|
|
251
|
+
"ExperimentAssistant", "LLMConfig", "LLMClient", "LLMUnavailable",
|
|
252
|
+
"DataProfile", "DataRoles", "ExperimentPlan", "Issue",
|
|
253
|
+
"read_table", "profile_frame", "infer_data_roles", "find_local_models",
|
|
242
254
|
"MixedLogitGSE", "RandomParameters", "ConstraintBuilder", "create_constraints",
|
|
243
255
|
"Parameters", "misc",
|
|
244
256
|
"ChoiceEstimate", "ChoiceEstimateResult", "ChoiceSetFrame",
|