### Install IRTorch from GitHub

Source: https://github.com/joakimwallmark/irtorch/blob/main/README.md

Use this command to install the latest development version of IRTorch directly from its GitHub repository.

```bash
pip install git+https://github.com/joakimwallmark/irtorch.git
```

--------------------------------

### Install JupyterLab

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/installation.md

Install JupyterLab, a web-based interactive development environment for working with notebooks and code.

```bash
pip install jupyterlab
```

--------------------------------

### Install IRTorch from PyPI

Source: https://github.com/joakimwallmark/irtorch/blob/main/README.md

Use this command to install the latest stable version of IRTorch from the Python Package Index.

```bash
pip install irtorch
```

--------------------------------

### Start JupyterLab Session

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/installation.md

Run this command in your terminal to start a JupyterLab session.

```bash
jupyter lab
```

--------------------------------

### Import IRTorch in Jupyter Notebook

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/installation.md

Verify IRTorch installation by importing the package in a new Jupyter notebook.

```python
import irtorch
print("IRTorch successfully installed")
```

--------------------------------

### Fit MonotonePolynomial Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Example of initializing and fitting a MonotonePolynomial model using the MML estimation algorithm with provided data.

```python
>>> from irtorch.models import MonotonePolynomial
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_national_mathematics_1
>>> data = swedish_national_mathematics_1()
>>> model = MonotonePolynomial(data)
>>> model.fit(train_data=data, algorithm=MML())
```

--------------------------------

### Install IRTorch in Google Colab

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/installation.md

Install IRTorch within a Google Colab notebook cell. This command is prefixed with '!' to run as a shell command.

```bash
!pip install irtorch
```

--------------------------------

### Load Libraries for IRTorch Analysis

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Imports necessary libraries including pandas, numpy, torch, irtorch, and specific modules for models, rescaling, and estimation algorithms. Ensure these libraries are installed before running.

```python
import pandas as pd
import numpy as np
import torch
import irtorch
from irtorch.models import GeneralizedPartialCredit, MonotoneNN
from irtorch.rescale import Bit
from irtorch.estimation_algorithms import MML, JML
```

--------------------------------

### Approximate Starting Theta for Bit Scores (MC Models)

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/scales.md

Approximates the starting theta score for computing bit scores in multiple-choice models. Allows customization of theta estimation method, device, learning rate, and guessing probabilities.

```python
bit_score_starting_theta_mc(theta_estimation: str = 'ML', ml_map_device: str = 'cpu', lbfgs_learning_rate: float = 0.25, items: list[int] | None = None, guessing_probabilities: list[float] | None = None, guessing_iterations: int = 10000)
```

--------------------------------

### set_start_theta

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/scales.md

Sets the starting theta scores for the bit scale computation.

```APIDOC
## set_start_theta

### Description
Sets the starting theta scores for the bit scale computation.

### Parameters
#### Parameters
- **start_theta** (*torch.Tensor*) – The starting theta scores for the bit scale computation.
```

--------------------------------

### Fit One-Parameter Logistic Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Example of fitting a 1PL model using MML estimation. Requires importing the model, estimation algorithm, and dataset.

```python
from irtorch.models import OneParameterLogistic
from irtorch.estimation_algorithms import MML
from irtorch.load_dataset import swedish_sat_binary
# Use quantitative part of the SAT data
data = swedish_sat_binary()[:, :80]
model = OneParameterLogistic(items=80)
model.fit(train_data=data, algorithm=MML())
```

--------------------------------

### Get Item Parameters (Weights and Biases)

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Retrieves item parameters for a fitted model, returning weights and biases when `irt_format` is False.

```python
>>> model.item_parameters(irt_format=False)
```

--------------------------------

### Fit Mixed GPC and MNN Models

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Example of fitting a mix of Generalized Partial Credit (GPC) and Monotone Neural Network (MNN) models to a dataset. This snippet shows the necessary imports and model instantiation for a mixed model approach.

```python
from irtorch.models import GeneralizedPartialCredit, MonotoneNN, ModelMix
from irtorch.estimation_algorithms import MML
from irtorch.load_dataset import swedish_national_mathematics_2
data_math = swedish_national_mathematics_2()
gpc = GeneralizedPartialCredit(data=data_math[:, :14])
mnn = MonotoneNN(data = data_math[:, 14:])
mix_model = ModelMix([gpc, mnn])
mix_model.fit(train_data=data_math, algorithm=MML())
```

--------------------------------

### Create and Convert Example DataFrame to Tensor

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Generates a pandas DataFrame with random integer data simulating test responses, including missing values (NaN). Converts this DataFrame into a PyTorch tensor, which is the required format for IRTorch.

```python
np.random.seed(42)
example_df = pd.DataFrame({f"Item {i}": np.random.randint(0, 5, 10) for i in range(1, 6)})
missing_indices = np.random.choice(example_df.index, size=10, replace=False)
for col in example_df.columns:
    example_df.loc[np.random.choice(missing_indices, size=2, replace=False), col] = np.nan

example_tensor = torch.tensor(example_df.to_numpy())
print(example_tensor)
```

--------------------------------

### Set Starting Theta for Bit Scale Computation

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/scales.md

Manually sets the initial theta scores used for the bit scale computation. Requires a torch.Tensor as input.

```python
set_start_theta(start_theta: torch.Tensor)
```

--------------------------------

### Initialize and Fit SurprisalSpline Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Demonstrates how to initialize a SurprisalSpline model with data and fit it using the MML estimation algorithm. Ensure data is loaded before model instantiation.

```python
>>> from irtorch.models import SurprisalSpline
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_national_mathematics_1
>>> data = swedish_national_mathematics_1()
>>> model = SurprisalSpline(data)
>>> model.fit(train_data=data, algorithm=MML())
```

--------------------------------

### Initialize and Fit MonotoneNN Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Demonstrates how to load data, initialize a MonotoneNN model, and fit it using the MML algorithm. Ensure you have the necessary data and algorithm classes imported.

```python
>>> from irtorch.models import MonotoneNN
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_national_mathematics_1
>>> data = swedish_national_mathematics_1()
>>> model = MonotoneNN(data)
>>> model.fit(train_data=data, algorithm=MML())
```

--------------------------------

### Initialize and Fit MonotoneBSpline Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Demonstrates initializing a MonotoneBSpline model and fitting it to data using the MML algorithm. Ensure necessary imports are present.

```python
>>> from irtorch.models import MonotoneBSpline
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_national_mathematics_1
>>> data = swedish_national_mathematics_1()
>>> model = MonotoneBSpline(data)
>>> model.fit(train_data=data, algorithm=MML())
```

--------------------------------

### Get Item Parameters (IRT Format)

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Retrieves item parameters for a fitted model. Set `irt_format=True` to get parameters in the traditional IRT format.

```python
>>> model.item_parameters(irt_format=True)
```

--------------------------------

### Instantiate and Fit GradedResponse Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Demonstrates how to instantiate a GradedResponse model and fit it using the MML estimation algorithm with provided data.

```python
>>> from irtorch.models import GradedResponse
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_national_mathematics_1
>>> data = swedish_national_mathematics_1()
>>> model = GradedResponse(data)
>>> model.fit(train_data=data, algorithm=MML())
```

--------------------------------

### Get Item Parameters in IRT Format

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Retrieve estimated item parameters for parametric IRT models using the `item_parameters()` method. Set `irt_format=True` to get parameters in the traditional IRT format. Zeros are expected for items with fewer than 4 response points.

```python
gpc.item_parameters(irt_format=True)
```

--------------------------------

### Fit GeneralizedPartialCredit Model with MML

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Demonstrates how to initialize and fit a GeneralizedPartialCredit model using the MML estimation algorithm with sample data.

```python
>>> from irtorch.models import GeneralizedPartialCredit
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_national_mathematics_1
>>> data = swedish_national_mathematics_1()
>>> model = GeneralizedPartialCredit(data)
>>> model.fit(train_data=data, algorithm=MML())
```

--------------------------------

### Fit and Evaluate Generalized Partial Credit Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/evaluator.md

Demonstrates fitting a Generalized Partial Credit Model using MML estimation and evaluating it using Q3 with hypothesis testing.

```python
>>> from irtorch.models import GeneralizedPartialCredit
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_national_mathematics_1
>>> data = swedish_national_mathematics_1()
>>> model = GeneralizedPartialCredit(data)
>>> model.fit(train_data=data, algorithm=MML())
>>> q3, p_value = model.evaluate.q3(data, sample_hypothesis_test=True, samples=300)
```

--------------------------------

### Fit NestedLogit Model with MML

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Demonstrates fitting a NestedLogit model using the MML estimation algorithm with Swedish SAT quantitative data. Ensure necessary imports and data loading are performed.

```python
>>> from irtorch.models import NestedLogit, ThreeParameterLogistic
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_sat_quantitative
>>> data, correct_responses = swedish_sat_quantitative()
>>> model_3pl = ThreeParameterLogistic(items = data.shape[1])
>>> model_nested = NestedLogit(correct_responses, model_3pl, data=data)
>>> model_nested.fit(train_data=data, algorithm=MML())
```

--------------------------------

### Get Item Parameters

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Retrieves the item parameters from a fitted IRT model. Returns a pandas DataFrame containing the parameters.

```python
item_parameters() → DataFrame
```

--------------------------------

### item_theta_relationship_directions

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Gets the relationship directions between each item and latent variable for a fitted OneParameterLogistic model. For this specific model, theta is not needed.

```APIDOC
## item_theta_relationship_directions(theta: Tensor = None) -> Tensor

### Description
Get the relationship directions between each item and latent variable for a fitted model.

### Parameters
#### Path Parameters
- **theta** (torch.Tensor, optional) - Not needed for this model. (default is None)

### Returns
- **torch.Tensor** - A 2D tensor with the relationships between the items and latent variables. Items are rows and latent variables are columns.
```

--------------------------------

### Apply and Use Bit Scale Transformation

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/scales.md

Demonstrates loading data, fitting a MonotoneNN model, initializing and applying the Bit scale transformation, and plotting results. It shows how to rescale theta scores and visualize item probabilities on the transformed scale.

```python
>>> import irtorch
>>> from irtorch.models import MonotoneNN
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.rescale import Bit
>>> data, mc_correct = irtorch.load_dataset.swedish_sat_quantitative()
>>> model = MonotoneNN(data, mc_correct=mc_correct)
>>> model.fit(train_data=data, algorithm=MML())
>>> thetas = model.latent_scores(data)
>>> # Initalize the scale transformation
>>> # mc_start_theta_approx sets the starting theta to the approximate score of a randomly guessing respondent
>>> bit = Bit(model, population_theta=thetas, mc_start_theta_approx=True)
>>> # Supply the new scale to the model
>>> model.add_scale_transformation(bit)
>>> # Estimate thetas on the transformed scale
>>> rescaled_thetas = model.latent_scores(data)
>>> # Or alternatively by directly converting the old ones
>>> rescaled_thetas = model.transform_theta(thetas)
>>> # Plot the differences
>>> model.plot.latent_score_distribution(thetas).show()
>>> model.plot.latent_score_distribution(rescaled_thetas).show()
>>> # Plot an item on the bit transformed scale
>>> model.plot.item_probabilities(1).show()
```

--------------------------------

### Get Item-Theta Relationship Directions

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Calculates the directions of the relationship between each item and latent variable. For NR models, the optional theta parameter is required.

```python
item_theta_relationship_directions(theta: Tensor = None) → Tensor
```

--------------------------------

### Get Item-Theta Relationship Directions

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Obtains the relationship directions between items and latent variables for a fitted model. The `theta` parameter is not needed for this model.

```python
>>> model.item_theta_relationship_directions()
```

--------------------------------

### Fit TwoParameterLogistic Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Demonstrates how to initialize and fit a TwoParameterLogistic model using MML estimation with the Swedish SAT binary dataset. Ensure the necessary modules are imported.

```python
>>> from irtorch.models import TwoParameterLogistic
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_sat_binary
>>> # Use quantitative part of the SAT data
>>> data = swedish_sat_binary()[:, :80]
>>> model = TwoParameterLogistic(items=80)
>>> model.fit(train_data=data, algorithm=MML())
```

--------------------------------

### latent_mean_se

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/estimation_algorithms.md

Get the posterior mean and standard error of the latent variables. This method is useful for understanding the uncertainty associated with the latent variable estimates.

```APIDOC
## latent_mean_se

### Description
Get the posterior mean and standard error of the latent variables. This method is useful for understanding the uncertainty associated with the latent variable estimates.

### Method
latent_mean_se

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **input_data** (*torch.Tensor*) – Required - The input data.

### Request Example
None

### Response
#### Success Response (200)
- **mean** (*torch.Tensor*) - The posterior mean of the latent variables.
- **standard_error** (*torch.Tensor*) - The standard error of the latent variables.

#### Response Example
None
```

--------------------------------

### Plot Training History

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Visualizes the training history for both GPC and MNN models to assess convergence. The `.show()` method displays the plot.

```python
gpc.plot.training_history().show()
mnn.plot.training_history().show()
```

--------------------------------

### latent_credible_interval

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/estimation_algorithms.md

Get the credible interval for the latent variables. This method returns the lower bound, mean, and upper bound of the credible interval for the latent variables.

```APIDOC
## latent_credible_interval

### Description
Get the credible interval for the latent variables. This method returns the lower bound, mean, and upper bound of the credible interval for the latent variables.

### Method
latent_credible_interval

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **input_data** (*torch.Tensor*) – Required - The input data.
* **alpha** (*float* *,* *optional*) – The significance level. (default is 0.05)

### Request Example
None

### Response
#### Success Response (200)
- **lower_bound** (*torch.Tensor*) - The lower bound of the credible interval.
- **mean** (*torch.Tensor*) - The mean of the credible interval.
- **upper_bound** (*torch.Tensor*) - The upper bound of the credible interval.

#### Response Example
None
```

--------------------------------

### Initialize MNN Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Initializes a Monotone Neural Network (MNN) model for comparison. This model is more flexible than GPC.

```python
irtorch.set_seed(42)
mnn = MonotoneNN(data = data_math)
```

--------------------------------

### Fit and Evaluate IRT Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/evaluator.md

This snippet demonstrates how to load a dataset, instantiate a GeneralizedPartialCredit model, fit it using the MML algorithm, and evaluate it using mutual information difference with hypothesis testing.

```python
>>> import irtorch
>>> from irtorch.models import GeneralizedPartialCredit
>>> from irtorch.estimation_algorithms import MML
>>> data = irtorch.load_dataset.swedish_national_mathematics_1()
>>> model = GeneralizedPartialCredit(data)
>>> model.fit(train_data=data, algorithm=MML())
>>> mid, amid, p_value = model.evaluate.mutual_information_difference(data, sample_hypothesis_test=True, samples=300)
```

--------------------------------

### Initialize GPC Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Initializes a Generalized Partial Credit (GPC) model. The number of possible responses can be computed from the data.

```python
irtorch.set_seed(42)
gpc = GeneralizedPartialCredit(data=data_math)
```

--------------------------------

### Transform Theta to Bit Scores

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/scales.md

Transforms standard theta scores into the bit score scale. Returns both the transformed scores and the starting theta values used.

```python
transform(theta: torch.Tensor) -> torch.Tensor
```

--------------------------------

### Initialize Three-Parameter Logistic Model

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/swedish_sat.ipynb

Instantiate a 3PL model by specifying the number of items. Ensure the `ThreeParameterLogistic` class is imported.

```python
from irtorch.models import ThreeParameterLogistic

threepl = ThreeParameterLogistic(items = data_sat.shape[1])
```

--------------------------------

### Get Latent Scores with Autoencoder

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/estimation_algorithms.md

Obtains latent scores for a given dataset using the trained autoencoder's encoder. Input data should be a 2D tensor.

```python
latent_scores = ae_model.theta_scores(test_data)
```

--------------------------------

### bit_score_starting_theta_mc

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/scales.md

Approximates the starting theta score for computing bit scores in multiple-choice models. This is crucial for initializing the bit score calculation, especially when incorporating guessing probabilities.

```APIDOC
## bit_score_starting_theta_mc

### Description
For multiple choice models, approximate the starting theta score $\mathbf{\theta}^{(0)}$ from which to compute bit scores. See notes under `bit_scores()` for the bit score formula.

### Parameters
#### Parameters
- **theta_estimation** (*str*, *optional*) – Method used to obtain the theta scores. Can be ‘NN’, ‘ML’, ‘EAP’ or ‘MAP’ for neural network, maximum likelihood, expected a posteriori or maximum a posteriori respectively. (default is ‘ML’)
- **ml_map_device** (*str*, *optional*) – For ML and MAP. The device to use for computation. Can be ‘cpu’ or ‘cuda’. (default is “cuda” if available else “cpu”)
- **lbfgs_learning_rate** (*float*, *optional*) – For ML and MAP. The learning rate to use for the LBFGS optimizer. (default is 0.3)
- **items** (*list*[*int*]*, *optional*) – The item indices for the items to use to compute the bit scores. (default is None and uses all items)
- **guessing_probabilities** (*list*[*float*]*, *optional*) – The guessing probability for each item. The same length as the number of items. Guessing is not supported for polytomously scored items and the probabilities for them will be ignored. (default is None and uses no guessing or, for multiple choice models, 1 over the number of item categories)
- **guessing_iterations** (*int*, *optional*) – The number of iterations to use for approximating a minimum theta when guessing is incorporated. (default is 200)

### Returns
A tensor with all the starting theta values.

### Return type
torch.Tensor
```

--------------------------------

### Model Convergence and Q3 Scores Output

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

This snippet shows the typical output logs during model optimization, indicating convergence status and identifying potential item pairs with large Q3 values, which might suggest model misspecification.

```text
INFO: Finding training data theta scores to use as initial theta estimates...
INFO: Sampling training data theta scores to avoid running out of memory...
INFO: Optimizing theta scores...


```

```text
Iteration 4: Current Loss = 23594.384765625 

```

```text
INFO: Converged at iteration 4.
INFO: Largest Q3 is 0.60 between Item 21 and Item 22.


```

--------------------------------

### Fit ThreeParameterLogistic Model with MML

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Demonstrates fitting a ThreeParameterLogistic model using the MML estimation algorithm with Swedish SAT binary data. Ensure data is loaded and the model is initialized before fitting.

```python
>>> from irtorch.models import ThreeParameterLogistic
>>> from irtorch.estimation_algorithms import MML
>>> from irtorch.load_dataset import swedish_sat_binary
>>> # Use quantitative part of the SAT data
>>> data = swedish_sat_binary()[:, :80]
>>> model = ThreeParameterLogistic(items=80)
>>> model.fit(train_data=data, algorithm=MML())
```

--------------------------------

### irtorch.estimation_algorithms.ae.AE.theta_scores

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/estimation_algorithms.md

Get the latent scores (theta) from an input dataset using the trained autoencoder's encoder. This is useful for evaluating the model or making predictions on new data.

```APIDOC
## irtorch.estimation_algorithms.ae.AE.theta_scores

### Description
Get the latent scores from an input dataset using the encoder.

### Method
theta_scores

### Parameters
#### Path Parameters
* **data** (*torch.Tensor*) – A 2D tensor with test data. Columns are items and rows are respondents.

### Response
#### Success Response (200)
* **theta_scores** – A 2D tensor of latent scores. Rows are respondents and latent variables are columns.
* **Return type:** torch.Tensor
```

--------------------------------

### Compute and Display Q3 Statistics for First 7 Items

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Computes Q3 statistics to check the local independence assumption for GPC and MNN models. Displays the Q3 values for the first 7 items. Close to zero values suggest conditional independence.

```python
q3_gpc, _ = gpc.evaluate.q3(data=data_math)
q3_mnn, _ = mnn.evaluate.q3(data=data_math)
print(q3_gpc.iloc[:7, :7])
print(q3_mnn.iloc[:7, :7])
```

--------------------------------

### Load IRTorch Libraries

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/swedish_sat.ipynb

Imports necessary libraries and modules from the IRTorch package and PyTorch for data analysis.

```python
import copy
import torch
import irtorch
from irtorch.models import NestedLogit, ThreeParameterLogistic
from irtorch.estimation_algorithms import MML
```

--------------------------------

### Get Item Categories from Response Data

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/utils.md

Determine the number of possible responses for each item in a given dataset. The input data should be a 2D tensor with respondents as rows and items as columns, using -1 or 'nan' for missing responses.

```python
>>> import torch
>>> from irtorch.utils import get_item_categories
>>> data = torch.tensor([[0, 1, -1], [1, 0, 0]])
>>> item_categories = get_item_categories(data)
>>> print(item_categories)
[2, 2, 1]
```

--------------------------------

### Package Configuration

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/index.md

Functions for configuring the IRTorch package.

```APIDOC
## Package Configuration

Utilities for configuring the IRTorch package's behavior.

### Function

*   `set_verbosity(level)`: Sets the verbosity level for the package.
```

--------------------------------

### Load and Preprocess Big Five Dataset

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/datasets.md

This snippet demonstrates the complete process of downloading, unpacking, cleaning, and preprocessing the Big Five personality dataset for use with IRTorch. It handles data cleaning, reverse-coding items, and converting the data to a PyTorch tensor.

```python
import os
import urllib.request
import shutil
import tempfile
import torch
import pandas as pd

data_url = "https://openpsychometrics.org/_rawdata/IPIP-FFM-data-8Nov2018.zip"
with tempfile.TemporaryDirectory() as tmpdirname:
    zip_filepath = os.path.join(tmpdirname, "big_five.zip")
    data_dir = os.path.join(tmpdirname, "IPIP-FFM-data-8Nov2018")
    filepath = os.path.join(data_dir, "data-final.csv")
    urllib.request.urlretrieve(data_url, zip_filepath)
    shutil.unpack_archive(zip_filepath, tmpdirname)
    original_data = pd.read_csv(filepath, sep=" ", header=0)

data = original_data.copy()
data.iloc[:, 50:100] = data.iloc[:, 50:100] / 1000 # time in seconds
# drop anyone with negative or really long response times (5min+).
keep = ((data.iloc[:, 50:100] < 0).sum(axis=1) == 0) & ((data.iloc[:, 50:100] > 300).sum(axis=1) == 0)
data = data[keep]
data = data[data["IPC"] == 1] # Drop multiple submissions from same IP address.
data = data.iloc[:, :50] # keep only response columns
data = data.dropna() # Drop people with NaN values.
data = data[data.sum(1) > 0] # Drop people with all missing responses (0 is missing).
data = data.mask(data == 0, float("nan")) # encode missing as nan
# Reverse-code reverse-coded items.
reverse_items = [
    "EXT2", "EXT4", "EXT6", "EXT8", "EXT10", "AGR1", "AGR3", "AGR5", "AGR7",
    "CSN2", "CSN4", "CSN6", "CSN8", "EST2", "EST4", "OPN2", "OPN4", "OPN6"
]
data[reverse_items] = ((1 - data[reverse_items] / 5) * 5 + 1).mask(lambda col: col == 6, 0)
data = data - 1 # code first option as 0, second as 1, etc.
torch_data = torch.tensor(data.to_numpy(), dtype=torch.float32)
```

--------------------------------

### Fit 3PL Model with MML and Save Parameters

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/swedish_sat.ipynb

Fit the initialized 3PL model using the Marginal Maximum Likelihood (MML) algorithm. The model training data should be in binary format. Optionally, save the fitted model parameters to a file for later use. Ensure `irtorch.set_seed` is called for reproducibility.

```python
import irtorch
from irtorch.estimation import MML

irtorch.set_seed(42)
threepl.fit(train_data=train_data_binary, algorithm=MML())
threepl.save_model("swesat_3pl.pt")
```

--------------------------------

### Split Data for Training and Testing

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/swedish_sat.ipynb

Splits the loaded test data into training and testing sets using a specified ratio (80% for training). Ensures reproducibility by setting a seed.

```python
irtorch.set_seed(42)
train_data, test_data = irtorch.split_data(data_sat, 0.8)
```

--------------------------------

### Fit IRT Models with Data Splitting

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Fits the initialized GPC and MNN models using MML and JML algorithms, respectively. Data is split into training and testing sets. Fitting can utilize GPU if available, or CPU.

```python
irtorch.set_seed(42)
train_data, test_data = irtorch.split_data(data_math, 0.8)
gpc.fit(train_data=train_data, algorithm=MML())
mnn.fit(train_data=train_data, algorithm=JML())
```

--------------------------------

### Compare Model Log-Likelihood

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Compares the log-likelihood of GPC and MNN models on test data. A higher log-likelihood indicates a better model fit.

```python
print(gpc.evaluate.log_likelihood(data=test_data, theta=theta_test_gpc))
print(mnn.evaluate.log_likelihood(data=test_data, theta=theta_test_mnn))
```

--------------------------------

### irtorch.load_dataset.swedish_sat_quantitative

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/datasets.md

Loads a sample from the quantitative part of the Swedish SAT dataset and the correct item responses. Returns a tuple containing the dataset and responses.

```APIDOC
## irtorch.load_dataset.swedish_sat_quantitative

### Description
Loads a sample from the quantitative part Swedish SAT dataset and the correct item responses. The correct item responses start from one, and thus a 1 corresponds to a response of 0 in the data.

### Method
N/A (Function Call)

### Parameters
None

### Response
#### Success Response
- **Returns:** A tuple containing the loaded dataset and the correct item responses.
- **Return type:** tuple (torch.Tensor, list[int])
```

--------------------------------

### Load Saved Model Parameters

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/swedish_sat.ipynb

Load previously saved model parameters into a new model instance. The new instance must be initialized with the same parameters (e.g., number of items) as the original model.

```python
from irtorch.models import ThreeParameterLogistic

threepl = ThreeParameterLogistic(items = data_sat.shape[1])
threepl.load_model("swesat_3pl.pt")
```

--------------------------------

### Perform Q3 Hypothesis Test and Display P-values

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/notebooks/national_mathematics.ipynb

Performs a Q3 hypothesis test by sampling data under the null hypothesis to compute p-values. Displays the p-values for the first 7 items for GPC and MNN models. Small p-values indicate potential violation of the local independence assumption.

```python
_, p_values_gpc = gpc.evaluate.q3(data=data_math, sample_hypothesis_test=True)
_, p_values_mnn = mnn.evaluate.q3(data=data_math, sample_hypothesis_test=True)
print(f"\ngpc: 
{p_values_gpc.iloc[:7, :7]}\n")
print(f"mnn: 
{p_values_mnn.iloc[:7, :7]}")
```

--------------------------------

### Datasets

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/index.md

Functions for loading built-in datasets.

```APIDOC
## Datasets

Functions to load various datasets for use with IRTorch.

### Functions

*   `big_five()`: Loads the Big Five dataset.
*   `swedish_national_mathematics_1()`: Loads the Swedish National Mathematics 1 dataset.
*   `swedish_national_mathematics_2()`: Loads the Swedish National Mathematics 2 dataset.
*   `swedish_sat()`: Loads the Swedish SAT dataset.
*   `swedish_sat_binary()`: Loads the binary version of the Swedish SAT dataset.
*   `swedish_sat_quantitative()`: Loads the quantitative version of the Swedish SAT dataset.
*   `swedish_sat_verbal()`: Loads the verbal version of the Swedish SAT dataset.
```

--------------------------------

### MonotonePolynomial Model Initialization

Source: https://github.com/joakimwallmark/irtorch/blob/main/docs/source/irt_models.md

Shows how to initialize the MonotonePolynomial IRT model. This model uses monotonic polynomials for item response categories and allows customization of latent variables, polynomial degree, and relationships.

```python
MonotonePolynomial(data: Tensor | None = None, latent_variables: int = 1, item_categories: list[int] | None = None, degree: int = 3, item_theta_relationships: Tensor | None = None, separate: str = 'categories', negative_latent_variable_item_relationships: bool = True)
```