structuralsearchmodels 1.0.0

Estimating structural search models in Python

structuralsearchmodels

A Python wrapper for 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. The Python interface exposes the same types and functions. It works by calling the Julia package through the juliacall interface. Moreover, the wrapper automatically installs Julia and the required Julia packages on first import (via jill), making it easy to use without needing to set up a Julia environment.

Note that 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:

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.

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.

# 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

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 package, which provides a Python wrapper for the Julia package DifferentialEquations.jl.

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.