README.qmd

---
format: gfm
jupyter: python3
---

# pydefm: Python bindings for defm


|      CI              | status |
|----------------------|--------|
| conda.recipe         | [![Conda Actions Status][actions-conda-badge]][actions-conda-link] |
| pip builds           | [![Pip Actions Status][actions-pip-badge]][actions-pip-link] |

This is a python wrapper of the [`barry c++` library][barry-git], and in
particular, of the `defm` module that provides utilities for fitting
discrete exponential family models. This is possible using the
[`pybind11`][] library (which rocks!).

[`pybind11`]: https://pybind11.readthedocs.io/en/stable/

The `defm` module is already
[implemented in R](https://github.com/UofUEpiBio/defm){target="_blank"} and it
can be used to count motifs and build Markov Random fields and other models like
ERGMs. More information in [this preprint](https://arxiv.org/abs/2211.00627).


[barry-git]: https://github.com/USCbiostats/barry
[gitter-badge]:            https://badges.gitter.im/pybind/Lobby.svg
[gitter-link]:             https://gitter.im/pybind/Lobby
[actions-badge]:           https://github.com/UofUEpiBio/pydefm/workflows/Tests/badge.svg
[actions-conda-link]:      https://github.com/UofUEpiBio/pydefm/actions?query=workflow%3AConda
[actions-conda-badge]:     https://github.com/UofUEpiBio/pydefm/actions/workflows/conda.yml/badge.svg
[actions-pip-link]:        https://github.com/UofUEpiBio/pydefm/actions?query=workflow%3APip
[actions-pip-badge]:       https://github.com/UofUEpiBio/pydefm/actions/workflows/pip.yml/badge.svg
[actions-wheels-link]:     https://github.com/UofUEpiBio/pydefm/actions?query=workflow%3AWheels
[actions-wheels-badge]:    https://github.com/UofUEpiBio/pydefm/workflows/Wheels/badge.svg

# Installation


- clone this repository
- `pip install ./pydefm`


# Examples 

## Base setup

Here we show how to create a `defm` object and add terms to it. We will use the following data:

```{python}
# Loading the module
import pydefm as m
import numpy as np

# Creating a binary array
y = np.column_stack(
  (np.array([0, 0, 1, 1, 1, 1]),
  np.array([0, 1, 1, 0, 0, 1]))
)

# Adding some random X plus the ids
x = np.array([1, 2.0, 3.4, 3, 1, 2])
id = np.array([1, 1, 1, 2, 2, 2])
```

Once we have the needed data -- the binary array `y`, the covariates `x` and the ids `id` -- we can create a `defm` object.  

```{python}
# Creating the object
obj = m.new_defm(id, y, x, column_major = False)

# Printing the object on screen shows it is a pointer
obj
```

Adding terms via formula

```{python}
#| echo: true
#| output: true
m.term_formula(obj, "{y0}")
m.term_formula(obj, "{y1}")
m.term_formula(obj, "{0y0, y1}")
obj.init()
obj.print() 
```

```{python}
counts = m.get_stats(obj)
counts
```

Notice the first two columns coincide with the `y` array:

```{python}
y
```

Computing likelihood

```{python}
par = np.array([.5, -.5, 1.0])
obj.likelihood(par, as_log = True)

# Finding the MLE
res = m.defm_mle(obj, np.array([.5, -.5, 1.0]))
print(res)

```

And simulating

```{python}
m.simulate(obj, par)
```



[`cibuildwheel`]:          https://cibuildwheel.readthedocs.io


# Acknowledgements

This port work was supported by the Office of the Assistant Secretary of Defense for Health Affairs through the Epilepsy Research Program under Award No. HT94252310221. Opinions, interpretations, conclusions, and recommendations are those of the author and are not necessarily endorsed by the Department of Defense.