Metadata-Version: 2.4
Name: structuralsearchmodels
Version: 0.1.0
Summary: Estimating structural search models in Python
Author-email: "Rafael P. Greminger" <r.greminger@ucl.ac.uk>
License-Expression: MIT
Project-URL: Homepage, https://github.com/rgreminger/structuralsearchmodels
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: juliacall>=0.9.14
Requires-Dist: jill
Dynamic: license-file

# structuralsearchmodels

A Python wrapper for [StructuralSearchModels.jl](https://github.com/rgreminger/StructuralSearchModels.jl), a Julia package that provides the following functionality for structural search models: 

- Estimation
- Data simulation
- Model fit evaluation
- Welfare analysis

The full documentation of the Julia package is available at [rgreminger.github.io/StructuralSearchModels.jl](https://rgreminger.github.io/StructuralSearchModels.jl/dev). The Python interface exposes the same types and functions. It works by calling the Julia package through the [juliacall](https://juliapy.github.io/PythonCall.jl/stable/juliacall/) interface. Moreover, the wrapper automatically installs Julia and the required Julia packages on first import (via [jill](https://github.com/JuliaPy/jill)), making it easy to use without needing to set up a Julia environment.

Note that [juliacall](https://juliapy.github.io/PythonCall.jl/stable/juliacall/) supports multi-threading only experimentally, but in my own testing I have found that it works well. The examples here thus use multiple threads, which improves estimation speed substantially. 

## Installation

The Python package is registered on PyPI and can be installed using pip:

```bash
pip install structuralsearchmodels
```

Julia and the required Julia packages are installed automatically on first import.

## Minimal example

The following provides a minimal example of how to define, simulate data from, and then estimate a search and discovery model. For more examples, see the [documentation](https://rgreminger.github.io/StructuralSearchModels.jl/dev).

```python
import os
# set environment variables before importing, allowing Julia to use multiple threads 
os.environ['JULIA_NUM_THREADS'] = "8"                   # use 8 threads
os.environ['PYTHON_JULIACALL_HANDLE_SIGNALS'] = "yes"   # needed for multi-threading to work properly
from structuralsearchmodels import ssm

# Define model
m = ssm.SD(
    β = [-0.05, 3.5],       # preference parameters
    Ξ = 4.0,                # discovery value
    ρ = [-0.1],             # decrease in discovery value across positions
    ξ = 3.0,                # search value
    dE = ssm.Normal(),      # distribution of εᵢⱼ (shocks revealed from search)
    dV = ssm.Normal(),      # distribution of νᵢⱼ (shocks revealed on list)
    dU0 = ssm.Uniform(),    # distribution of outside option
    zdfun = "log"           # functional form of discovery value across positions
)

# Generate data
d = ssm.generate_data(m, 1000, 1, seed=1)

# Estimate model
e = ssm.SMLE(100)  # Simulated MLE with 100 simulation draws
m_hat, estimates, likelihood, result, std_errors = ssm.estimate(m, e, d, seed=1)
```

The package also supports non-unicode Greek letters through the respective alternative `NU` versions of the model types. 

```python
# Define model
m = ssm.SDNU(
    beta = [-0.05, 3.0],  
    Xi = 4.0,              
    rho = [-0.1],          
    xi = 3.0,              
    dE = ssm.Normal(),     
    dV = ssm.Normal(),     
    dU0 = ssm.Uniform(),   
    zdfun = "log"
)
```

## Other Examples 

#### Monte Carlo Simulation 

The `examples/monte_carlo.py` file provides a complete example of how to perform a Monte Carlo simulation, where data is generated from a known model and then the model is estimated using the generated data. 

#### Importing Data 

The `examples/import_data.py` file provides an example of how to import data from a CSV file and then use it for estimation.

#### Setting the Information Structure 

The `examples/information_structure.py` file provides an example of how to set the information structure of the model, which determines which product attributes are revealed when discovering an alternative and which ones are only revealed when searching an alternative. 

#### Advanced Usage with Keywords

The `examples/advanced_usage.py` file provides an example of how to use keywords to specify additional options for estimation, such as the optimizer. It uses the `jl.seval` function to execute Julia code from Python, which allows for more advanced usage of the underlying Julia package, but requires some understanding of Julia basics. 

## Python Utilities

```python
import structuralsearchmodels

# Reinstall the Julia package (e.g., to update to the latest version)
structuralsearchmodels.reinstall()
```

## Acknowledgements

Much of the code for this package is based on the amazing [diffeqpy](https://github.com/SciML/diffeqpy) package, which provides a Python wrapper for the Julia package [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/). 

## Citation

If you use this package in your research, please cite:

> Greminger, R. P. (2025). Trade-Offs Between Ranking Objectives: Descriptive Evidence and Structural Estimation. arXiv preprint available at https://arxiv.org/abs/2210.16408.

If you use the search and discovery model, please also cite:

> Greminger, R. P. (2022). Optimal Search and Discovery. *Management Science* 68(5), 3904–3924.
