README.Rmd

---
  output: github_document
---
  
  <!-- README.md is generated from README.Rmd. Please edit that file -->
  
```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# maxent.ot

<!-- badges: start -->
  [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13774033.svg)](https://doi.org/10.5281/zenodo.13774033)
<!-- badges: end -->
  
  This package allows you to fit Maximum Entropy Optimality Theory models to data 
sets, generate the predictions made by such models for novel data, and compare 
the fit of different models using a variety of metrics. This package is still in
development, and is being prepared for submission to CRAN.

The authors of this package are [Connor Mayer](http://connormayer.com), [Adeline Tan](https://www.linkedin.com/in/adeline-tan-ph-d-aa67742a9), 
and [Kie Zuraw](https://linguistics.ucla.edu/people/zuraw/).

## Citing maxent.ot
If you publish work that uses `maxent.ot`, please cite the following paper and repository:

> ```Mayer, C., Tan, A., & Zuraw, K. (in press). Introducing maxent.ot: an R package for Maximum Entropy constraint grammars. Phonological Data and Analysis.```

> ```Mayer, C., Tan, A., & Zuraw, K.(2024). maxent.ot: A package for doing Maximum Entropy Optimality Theory in R (Version 1.0.0) [Computer software]. 10.5281/zenodo.7246366```


## Installation

You can install the released version of maxent.ot from [CRAN](https://CRAN.R-project.org) with:

  ``` r
install.packages("maxent.ot")
```

  You can install the development version from [GitHub](https://github.com/) with:
  
  ``` r
if (!require(devtools)) {
  install.packages("devtools", repos = "http://cran.us.r-project.org")
}
if (!require(maxent.ot)) {
  devtools::install_github("connormayer/maxent.ot")
}
```
## Example

This is a simple example workflow of fitting two MaxEnt OT models to the same
data (with different constraint sets), examining their predicted frequencies, 
and comparing their fits using the likelihood ratio test.

```{r example}
library(maxent.ot)

# Get paths to input files.
# This file has two constraints
data_file_simple <- system.file(
  "extdata", "sample_data_frame.csv", package = "maxent.ot"
)
# This file has three constraints
data_file_complex <- system.file(
  "extdata", "sample_data_frame_large.csv", package = "maxent.ot"
)

# Read files into data frames
df_simple <- read.csv(data_file_simple)
df_complex <- read.csv(data_file_complex)

# Fit weights to both data sets with simple regularization
simple_model <- optimize_weights(df_simple, mu=0, sigma=10)
complex_model <- optimize_weights(df_complex, mu=0, sigma=10)

# Examine predicted probabilities of each model
# Also displayed: log likelihood (of weights given prediction data)
predict_probabilities(df_simple, simple_model$weights)
predict_probabilities(df_complex, complex_model$weights)


# Compare model fit to training data using the likelihood ratio test
compare_models(simple_model, complex_model, method='lrt')
```