Psiz

Breaking Changes
* Removed deprecated classes:
* `GroupLevel`
* `Stimuli`
* `WeightedMinkowski`
* `GroupAttention`
* `GroupAttentionVariational`
* `Kernel`
* `AttentionKernel`
* `SharedEmbedding`
* Removed deprecated arguments for `Behavior` base class:
* n_group
* group_level
* Removed optional argument `verbose` from `load_trials`
* Removed `EmbeddingND` since it causes code coherency issues. This class may be added back in the future.
* Removed `matrix_comparison` and `pairwise_matrix` since these utility functions are incompatible with the more general purpose batch-processing pipeline.
* Stimuli indices are now consistent between PsiZ trial objects and TF dataset versions, calling `as_dataset` no longer increments stimuli indices by one. A `mask_zero` argument has been added to the similarity observations classes. See the docs for a discussion of this masking strategy.
* Move `wpnorm` from `keras.layers.ops` to `psiz.tf.ops`
* Remove `NegLogLikelihood` loss and metric
* Removed alias `psiz.models`, users must use `psiz.keras.models`.
* Change `psiz.datasets.load` to `psiz.datasets.load_dataset`
* Organization of information gain computations has been updated.
* A new submodule has been created: `psiz.trials.information_gain`
* The function `expected_information_gain_rank` has been renamed `ig_categorical` and moved to `psiz.trials.information_gain`.
* The input shape of information gain function has changed from `(n_sample, n_trial, n_outcome)` to `(n_trial, n_sample, n_outcome)`. This change makes the dimension semantics consistent with the output of psiz.keras.models (i.e., `(batch_size, n_sample, n_outcome)`).
* Rename `RandomAttention` initializer to `Dirichlet`.
* For trials.experimental, change `as_dataset` to `export`.
* Update plotter signature in mplot module. Update removes `fig` as an argument and makes `ax` an optional argument.
* remove `verbose` from load_trials

Major Features and Improvements
* Reorganized documentation
* Added Beginner Tutorial
* Add `random_combinations` which handles sampling k-combinations with and without replacement and leans on already existing `choice_wo_replace`.
* Add `ig_model_categorical`, which takes one or more models as an input and computes ensemble-based information gain. Assumes that models generate samples from the posterior on the forward pass (e.g, a variational inference model) and output units are categorical.
* Enhanced `RandomRank` generator:
* Added weighting functionality.
* Added `per_query` functionality.

Bug Fixes and Other Changes
* Multiple changes to docstrings.
* Fix handling of shape argument on call of Dirichlet initializer. Was only using first dimension of shape array.
* Add `docs` section to optional install that includes packages listed in `conf.py` extensions
* Add optional `rng` argument to `choice_wo_replace`.
* Add dynamic version to PsychologicalEmbedding `get_config`
* For trials.experimental make `_save` and `_load` public methods `save` and `load`.
* Add `__all__` definition to `__init__` files satisfying PEP8 and removing linter complaints "imported but unused".

Miscellaneous
* Bump tensorflow-probability requirement to 0.13.0.
* Bump minimum TensorFlow version requirement to v2.4.3 for security fixes.
* Bump maximum TensorFlow version to v2.6.x.
* Add h5py >= 3.0 to setup.cfg so that TrialDataset `_load_h5_group` can safely assume h5py `asstr()` method is available

* No API feature changes.
* Expands documentation, tests, coverage reports, and CI/CD (via GitHub Actions).
* Source code has been modified to eliminate flake8 and pylint errors, but user-facing functionality is unchanged.
* Use `setuptools_scm` to automatically determine version number based on version tags.
* Fixes runtime error in `ActiveRank`.

This release focus on integration with TF 2.4, cleaning up redundancies in the PsiZ API, and laying the ground-work for a stable API.

Major Feature Changes
* TF 2.4 improves support for saving custom models.
* The internal sampling mechanics for stochastic models has changed. 1) Sampling is now handled at the input of the model by creating an additional "sample" axis. 2) The sampling axis is now located at `axis=1`. This is a departure from the previous implementation which followed tensorflow-probability, which prepends sample dimensions. Placing the sampling dimensions at axis=0 created many downstream problems where there are often strict assumptions that the first axis is the "batch" axis. Together, these two changes have yielded cleaner code that is easier to reason about. In particular, non-input layers can remain ignorant of the sampling strategy implemented at the input.
* Added sparse dispatching functionality (`GroupGate` and `GroupGateMulti`) to facilitate generic group-specific layers.
* New similarity kernel strategy. New strategy is more general, exhibits looser coupling, and does not rely on Embedding layers. New strategy uses a generic `DistanceBased` container layer along with the reworked `Minkowski` layer. The `Minkowski` layer uses a standard set of trainable weights rather than an Embedding layer. Combined with `GroupGateMulti` users can assemble group-specific layers (see `examples/rank/mle_3g.py`). The classes `Kernel`, `AttentionKernel`, `WeightedMinkowski`, `GroupAttention` and `GroupAttentionVariational` have been deprecated and will be removed in a future release. Instead use `DistanceBased`, `Minkowski`, `MinkowksiVariational`, and `GroupGateMulti`.
* Expanded tests. Added `slow` pytest marker for slow running tests.
* Added `trials.experimental` which introduces an alternative set of classes for tracking trial data. The primary differences are the use of compositionality and the coding of trials sequences.

Breaking Changes
* Calling `model.save` uses TF save method instead of PsiZ's custom save method. See Issue 17 and 19 for advice on converting old models.
* Removed `Proxy` class from API. All examples have been updated. (See Issue 20)
* Replaced `procrustes_2d` utility function with more general and robust `procrustes_rotation` which uses SVD instead of iteration-based optimization. All examples have been updated.
* Shape assumptions for `wpnorm` have changed to be more inclusive. This is only a breaking change for gradient computations.

Other Changes
* Moved `models` module into `keras`. A full import looks something like `psiz.keras.models.Rank`. Users can still import models the old way (e.g., `psiz.models.Rank`) although this may be deprecated in the future. This was primarily done to safeguard against future model additions that do not follow the Keras API. A side-effect is that this organization mimics TF.
* Moved `generators` module into trials.
* Removed `preprocessing` module.
* Replaced `visualization` module with `mplot` module. Some functionality is overlapping.
* Internal changes to source code file naming and directory organization.

Resolved Issues
* Issue 19: The problem was due to an if statement in the `Rank` call method. The `Rank` refactor creates tighter guarantees on Tensor shapes, eliminating the need for the if statement.

Update TensorFlow requirement to address TF 2.3.0 vulnerability.

Embeddings with Variational Inference
Substantial API changes have been made to facilitate variational inference and group-specific embeddings.

Update to TensorFlow 2.0 idioms
The internal code has been updated to use TensorFlow 2.0 style. All old idioms, like explicit sessions, have been removed. As part of the transition, the core of the model is now implemented using a tf.keras model composed of layers.