0
# PyStan
1

2
PyStan provides a Python interface to Stan, a state-of-the-art platform for statistical modeling and high-performance statistical computation. It enables Python developers to build, compile, and sample from Bayesian statistical models using Stan's probabilistic programming language, featuring automatic caching of compiled models and samples, and support for complex hierarchical models used in scientific research across social, biological, and physical sciences.
3

4
## Package Information
5

6
- **Package Name**: pystan
7
- **Language**: Python
8
- **Installation**: `pip install pystan`
9

10
## Core Imports
11

12
```python
13
import stan
14

15
# Version information (when available)
16
print(stan.__version__)  # Package version
17
```
18

19
## Basic Usage
20

21
```python
22
import stan
23

24
# Define a simple Bayesian model
25
program_code = """
26
parameters {
27
    real mu;
28
    real<lower=0> sigma;
29
}
30
model {
31
    mu ~ normal(0, 10);
32
    sigma ~ exponential(1);
33
}
34
"""
35

36
# Build (compile) the model
37
model = stan.build(program_code)
38

39
# Sample from the posterior
40
fit = model.sample(num_chains=4, num_samples=1000)
41

42
# Access results
43
print(fit['mu'])  # Parameter samples
44
print(fit.to_frame())  # Pandas DataFrame view
45
```
46

47
## Architecture
48

49
PyStan operates through a client-server architecture where Python manages the high-level interface while delegating computational tasks to httpstan, a Stan HTTP service. The core workflow follows these steps:
50

51
- **Model Building**: Stan code is compiled into executable C++ and cached
52
- **Data Integration**: Python data structures are automatically converted to Stan-compatible formats
53
- **Sampling**: Multiple chains run in parallel processes for robust MCMC inference
54
- **Result Management**: Samples are efficiently stored and accessed through a dictionary-like interface
55

56
This design ensures high performance for computationally intensive Bayesian inference while maintaining Python's ease of use.
57

58
## Capabilities
59

60
### Model Building and Compilation
61

62
Core functionality for building Stan models from program code, including data handling, caching, and compilation management.
63

64
```python { .api }
65
def build(program_code: str, data: Data = frozendict(), random_seed: Optional[int] = None) -> Model:
66
    """
67
    Build (compile) a Stan program.
68
    
69
    Args:
70
        program_code: Stan program code describing a Stan model
71
        data: Dictionary providing data for the model (default: frozendict())
72
        random_seed: Random seed for reproducible results
73
        
74
    Returns:
75
        Model: Compiled model ready for sampling
76
    """
77
```
78

79
[Model Building](./model-building.md)
80

81
### Bayesian Sampling
82

83
MCMC sampling methods for drawing from posterior distributions, including HMC-NUTS and fixed parameter sampling.
84

85
```python { .api }
86
class Model:
87
    def sample(self, *, num_chains: int = 4, **kwargs) -> Fit: ...
88
    def hmc_nuts_diag_e_adapt(self, *, num_chains: int = 4, **kwargs) -> Fit: ...
89
    def fixed_param(self, *, num_chains: int = 4, **kwargs) -> Fit: ...
90
```
91

92
[Bayesian Sampling](./bayesian-sampling.md)
93

94
### Parameter Transformation and Evaluation
95

96
Advanced functionality for parameter space transformations, log probability calculations, and gradient computations.
97

98
```python { .api }
99
class Model:
100
    def constrain_pars(self, unconstrained_parameters: Sequence[float], include_tparams: bool = True, include_gqs: bool = True) -> Sequence[float]: ...
101
    def unconstrain_pars(self, constrained_parameters: Sequence[float]) -> Sequence[float]: ...
102
    def log_prob(self, unconstrained_parameters: Sequence[float], adjust_transform: bool = True) -> float: ...
103
    def grad_log_prob(self, unconstrained_parameters: Sequence[float]) -> Sequence[float]: ...
104
```
105

106
[Parameter Operations](./parameter-operations.md)
107

108
### Results Analysis
109

110
Tools for accessing, analyzing, and transforming MCMC samples into usable formats.
111

112
```python { .api }
113
class Fit:
114
    def to_frame(self): ...
115
    def __getitem__(self, param: str): ...
116
    def __contains__(self, key: str) -> bool: ...
117
    def __iter__(self): ...
118
```
119

120
[Results Analysis](./results-analysis.md)
121

122
## Core Types
123

124
```python { .api }
125
from typing import Dict, Union, Sequence, Optional
126

127
# Type alias for model data
128
Data = Dict[str, Union[int, float, Sequence[Union[int, float]]]]
129

130
@dataclass(frozen=True)
131
class Model:
132
    """Stores data associated with and proxies calls to a Stan model."""
133
    model_name: str
134
    program_code: str
135
    data: Data
136
    param_names: Tuple[str, ...]
137
    constrained_param_names: Tuple[str, ...]
138
    dims: Tuple[Tuple[int, ...]]
139
    random_seed: Optional[int]
140

141
class Fit:
142
    """Stores draws from one or more chains. Acts like a Python dictionary."""
143
    stan_outputs: Tuple[bytes, ...]
144
    num_chains: int
145
    param_names: Tuple[str, ...]
146
    constrained_param_names: Tuple[str, ...]
147
    dims: Tuple[Tuple[int, ...]]
148
    num_warmup: int
149
    num_samples: int
150
    num_thin: int
151
    save_warmup: bool
152
    sample_and_sampler_param_names: Tuple[str, ...]
153
```
154

155
## Plugin System
156

157
PyStan provides a plugin system for extending functionality, primarily for post-sampling analysis.
158

159
```python { .api }
160
# Plugin development (advanced usage)
161
import stan.plugins
162

163
class PluginBase:
164
    """Base class for PyStan plugins."""
165
    def on_post_sample(self, fit: Fit) -> Fit:
166
        """Called with Fit instance when sampling has finished."""
167
        return fit
168

169
def get_plugins():
170
    """Iterate over available plugins."""
171
    ...
172
```