Torch-choice

Updates
Modeling Outside Option
Now our models are capable of modeling the "outside option" (i.e., the user chooses not to purchase any items). The outside option is modeled as an additional "item" that always provides exactly zero utility in all cases. The outside option is useful when the user has the option to choose none of the items. The outside option is particularly useful in the context of conditional logit and nested logit models.
You can enable the outside option by setting the keyword argument `model_outside_option=True` while initializing the `ConditionalLogitModel` or `NestedLogitModel`.
To indicate that the outside option is chosen, you could use the item index `-1` in `item_index` tensor to indicate that the user exerted the outside option in that observation.
We will be adding more detailed descriptions in our document.

Please Specify the Number of items/users/sessions Explicitly
Please explicitly specify the number of items, users, and sessions using keyword arguments `num_{items, users, sessions}` while calling the initialization methods of `ChoiceDataset` or `EasyDataWrapper` in the future. Without explicitly specifying the number of items/users/sessions, the `ChoiceDataset`` class will infer the number of items/users/sessions by calculating the number of unique items, which might lead to unexpected incorrect behavior.

Here is one example illustrating the caveat of not specifying the number of items explicitly.


item_index = [-1, 0, 0, -1, 1, 2, 3, 5, 6]

Since we required items to be encoded using consecutive integers from 0, `max(item_index)=6` suggests that there should be 7 items in this setting.
However, there are only 6 unique numbers in the `item_index` (expecting for `-1`, which denotes the outside option) and the item `4` was never chosen and missing from the `item_index`.
Without explicitly specifying `num_items=7` while constructing `ChoiceDataset`, the dataset object will incorrectly infer there are only 6 items.
This kind of unexpected behavior will affect models constructed on top of the affected dataset.
The scenario described above could happen when the researcher does a train-test split but some splits do not have all items (e.g., item `4` was only chosen in the training set but not the test set).



Technical Changes
What's Changed
* Refactor pivot method in EasyDatasetWrapper class by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/47 to support the recent update with Pandas discussed in this [issue](https://github.com/gsbDBI/torch-choice/issues/46).
* fix a typo by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/45
* Fix shared lambda by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/49
* Update the outside option branch from latest changes in main. by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/51
* Add the implementation of the outside option for conditional logit and nested logit models by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/42
* Thanks kdzhang for the outside option implementation discussed in [issue](https://github.com/gsbDBI/torch-choice/issues/41).
* Thanks Serena9070 for spotting bugs in the code and providing suggestions for improvement.

**Full Changelog**: https://github.com/gsbDBI/torch-choice/compare/v1.0.5...v1.0.6

What's Changed
* Enables users to control for the initialization strategies of different coefficients. by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/33
* fix issue with num_sessions attribute/property after subsetting. by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/36
* Support flexible observable naming prefixes by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/37 For example, the `ChoiceDataset` will understand both `useritem_obs` and `itemuser_obs` as (user, item)-specific observable tensor.
* 38 add user session obs support by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/39 The package is now supporting all seven types of observable tensors: user-specific, item-specific, session-specific, (user, item)-specific, (user, session)-specific, (item, session)-specific, and (user, session, item)-specific.
* The `ChoiceDataset.__repr__()` method now reports the `num_{users, items, sessions}`.


**Full Changelog**: https://github.com/gsbDBI/torch-choice/compare/v1.0.3...v1.0.5

What's Changed
* Enables users to control for the initialization strategies of different coefficients. by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/33
The model convergence can be sensitive to the initial weights of coefficients. We added a `weight_initialization` keyword argument to the `ConditionalLogitModel` class and `{nest, item}_weight_initialization` keyword arguments to the `NestedLogitModel` class. These arguments allow users to control the initialization of coefficients (e.g., initialize to zeros, uniform random, or Gaussian random). Please see the notebook here: [`./tutorial/coefficient_initialization.ipynb`](https://github.com/gsbDBI/torch-choice/blob/main/tutorials/coefficient_initialization.ipynb) or this [documentation page](https://gsbdbi.github.io/torch-choice/coefficient_initialization/) for demonstrations.

**Full Changelog**: https://github.com/gsbDBI/torch-choice/compare/v1.0.3...v1.0.4a

What's Changed
Version `v1.0.3` supports user-item specific observables and user-session-item specific observables in the `ChoiceDataset` data structure.

* 28 allowing for user item and user item session specific observables by TianyuDu in https://github.com/gsbDBI/torch-choice/pull/30


**Full Changelog**: https://github.com/gsbDBI/torch-choice/compare/v1.0.2...v1.0.3

Updates
1. We have added the LBFGS support.
2. Now, the training loop is fully integrated with PyTorch-Lightning, `run()` method is much easier to use.
3. We have updated the regression table to include z-values and p-values.
4. Website and GitHub landing page refreshed.


**Full Changelog**: https://github.com/gsbDBI/torch-choice/compare/v1.0.1...v1.0.2

1. Fixed the issue/enhancement described here: https://github.com/gsbDBI/torch-choice/issues/20.
2. We have added the `get_coefficient()` method for both the `ConditionalLogitModel` and `NestedLogitModel` classes, which allows researchers to retrieve coefficient tensors easily. Demonstrations to the `get_coefficient()` method can be found here: https://gsbdbi.github.io/torch-choice/post_estimation_demos/