Merge remote-tracking branch 'origin/main' into docs-tests

.github/ISSUE_TEMPLATE/bug.md

@@ -14,7 +14,7 @@ Save time, add code.
 
 **System Info**
 Describe the characteristic of your environment:
- * Describe how Gymnasium was installed (pip, docker, source, ...)
+ * Describe how Minari was installed (pip, docker, source, ...)
  * Operating system: 
  * Python version:
 
@@ -23,4 +23,4 @@ Add any other context about the problem here.
 
 ### Checklist
 
-- [ ] I have checked that there is no similar [issue](https://github.com/Farama-Foundation/PettingZoo/issues) in the repo (**required**)
+- [ ] I have checked that there is no similar [issue](https://github.com/Farama-Foundation/Minari/issues) in the repo (**required**)

.github/ISSUE_TEMPLATE/proposal.md

@@ -1,6 +1,6 @@
 ---
 name: Proposal
-about: Propose changes that are not fixes bugs
+about: Propose changes that do not fix bugs
 title: "[Proposal] Proposal title"
 ---
 
@@ -28,4 +28,4 @@ Add any other context or screenshots about the feature request here.
 
 ### Checklist
 
-- [ ] I have checked that there is no similar [issue](https://github.com/Farama-Foundation/PettingZoo/issues) in the repo (**required**)
+- [ ] I have checked that there is no similar [issue](https://github.com/Farama-Foundation/Minari/issues) in the repo (**required**)

.github/workflows/build-publish.yml

@@ -22,9 +22,6 @@ jobs:
     strategy:
       matrix:
         include:
-        - os: ubuntu-latest
-          python: 37
-          platform: manylinux_x86_64
         - os: ubuntu-latest
           python: 38
           platform: manylinux_x86_64

.github/workflows/build.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.7', '3.8', '3.9', '3.10', '3.11']
+        python-version: ['3.8', '3.9', '3.10', '3.11']
     steps:
       - uses: actions/checkout@v3
       - run: |

README.md

@@ -1,3 +1,6 @@
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://pre-commit.com/) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) 
+
+
 <p align="center">
     <img src="minari-text.png" width="500px"/>
 </p>
@@ -10,8 +13,12 @@ Note: Minari was previously developed under the name Kabuki.
 
 
 ## Installation
+To install Minari from [PyPI](https://pypi.org/project/minari/):
+```
+pip install minari
+```
 
-Currently the beta release is under development. If you'd like to start testing or contribute to Minari please install this project from source with: 
+Note that currently Minari is under a beta release. If you'd like to start testing or contribute to Minari please install this project from source with: 
 
 ```bash
 git clone https://github.com/Farama-Foundation/Minari.git
@@ -46,15 +53,15 @@ To download a dataset:
 ```python
 import minari
 
-minari.download_dataset("door-cloned-v0")
+minari.download_dataset("door-cloned-v1")
 ```
 
 To load a dataset:
 
 ```python
 import minari
 
-dataset = minari.load_dataset("door-cloned-v0")
+dataset = minari.load_dataset("door-cloned-v1")
 ```
 
 ## Project Maintainers

docs/README.md

@@ -3,3 +3,28 @@
 This folder contains the documentation for Minari.
 
 For more information about how to contribute to the documentation go to our [CONTRIBUTING.md](https://github.com/Farama-Foundation/Celshast/blob/main/CONTRIBUTING.md)
+
+## Build the Documentation
+
+Install the required packages and Minari:
+
+```bash
+git clone https://github.com/Farama-Foundation/Minari.git
+cd Minari
+pip install -e .
+pip install -r docs/requirements.txt
+```
+
+To build the documentation once:
+
+```bash
+cd docs
+make dirhtml
+```
+
+To rebuild the documentation automatically every time a change is made:
+
+```bash
+cd docs
+sphinx-autobuild -b dirhtml . _build
+```

docs/_scripts/gen_dataset_md.py

@@ -8,7 +8,8 @@
 
 from minari import list_remote_datasets
 from minari.dataset.minari_dataset import parse_dataset_id
-from minari.storage.hosting import find_highest_remote_version
+from minari.serialization import deserialize_space
+from minari.storage.hosting import get_remote_dataset_versions
 
 
 filtered_datasets = defaultdict(defaultdict)
@@ -19,7 +20,7 @@
     env_name, dataset_name, version = parse_dataset_id(dataset_id)
 
     if dataset_name not in filtered_datasets[env_name]:
-        max_version = find_highest_remote_version(env_name, dataset_name)
+        max_version = get_remote_dataset_versions(env_name, dataset_name, True)[0]
         max_version_dataset_id = "-".join([env_name, dataset_name, f"v{max_version}"])
         filtered_datasets[env_name][dataset_name] = all_remote_datasets[
             max_version_dataset_id
@@ -44,10 +45,19 @@
         dataset_id = dataset_spec["dataset_id"]
         total_timesteps = dataset_spec["total_steps"]
         total_episodes = dataset_spec["total_episodes"]
+        dataset_action_space = (
+            deserialize_space(dataset_spec["action_space"]).__repr__().replace("\n", "")
+        )
+        dataset_observation_space = (
+            deserialize_space(dataset_spec["observation_space"])
+            .__repr__()
+            .replace("\n", "")
+        )
         author = dataset_spec["author"]
         email = dataset_spec["author_email"]
         algo_name = dataset_spec["algorithm_name"]
         code = dataset_spec["code_permalink"]
+        minari_version = dataset_spec["minari_version"]
 
         description = None
         if "description" in dataset_spec:
@@ -97,10 +107,13 @@
 |----|----|
 |Total Timesteps| `{total_timesteps}`|
 |Total Episodes | `{total_episodes}` |
+| Dataset Observation Space | `{dataset_observation_space}` |
+| Dataset Action Space | `{dataset_action_space}` |
 | Algorithm           | `{algo_name}`           |
 | Author              | `{author}`              |
 | Email               | `{email}`               |
 | Code Permalink      | `{code}`                |
+| Minari Version      | `{minari_version}`      |
 | download            | `minari.download_dataset("{dataset_id}")` |
 
 

docs/api/minari_functions.md

@@ -50,3 +50,9 @@ minari_dataset/episode_data
 ```{eval-rst}
 .. autofunction:: minari.combine_datasets
 ```
+
+## Normalize Score
+
+```{eval-rst}
+.. autofunction:: minari.get_normalized_score
+```

docs/content/basic_usage.md

@@ -7,6 +7,20 @@ title: Basic Usage
 
 Minari is a standard dataset hosting interface for Offline Reinforcement Learning applications. Minari is compatible with most of the RL environments that follow the Gymnasium API and facilitates Offline RL dataset handling by providing data collection, dataset hosting, and dataset sampling capabilities.
 
+## Installation
+
+To install the most recent version of the Minari library run this command: `pip install minari`
+
+The beta release is currently under development. If you'd like to start testing or contribute to Minari then please install this project from source with:
+
+```bash
+git clone https://github.com/Farama-Foundation/Minari.git
+cd Minari
+pip install -e .
+```
+
+We support Python 3.8, 3.9, 3.10 and 3.11 on Linux and macOS.
+
 ## Create Minari Dataset
 
 ### Collecting Data

docs/content/dataset_standards.md

@@ -313,10 +313,10 @@ In this case, the resulting Minari dataset `HDF5` file will end up looking as fo
                 <li class="folder">actions
                 <ul>
                     <li class="dataset">_index_0</li>
-                    <li class="folder">_index_1_
+                    <li class="folder">_index_1
                     <ul>
                     <li class="dataset"> _index_0 </li>
-                    <li class="dataset"> _index_1_ </li>
+                    <li class="dataset"> _index_1 </li>
                     </ul>
                     </li>
                 </ul>
@@ -360,10 +360,10 @@ In this case, the resulting Minari dataset `HDF5` file will end up looking as fo
                     <li class="folder-white">actions
                         <ul>
                             <li class="dataset-white">_index_0</li>
-                            <li class="folder-white">_index_1_
+                            <li class="folder-white">_index_1
                             <ul>
                             <li class="dataset-white"> _index_0 </li>
-                            <li class="dataset-white"> _index_1_ </li>
+                            <li class="dataset-white"> _index_1 </li>
                             </ul>
                             </li>
                         </ul>
@@ -502,6 +502,7 @@ When creating a Minari dataset with the `DataCollectorV0` wrapper the default gl
 | `algorithm_name`        | `str`      | Name of the expert policy used to create the dataset. |
 | `action_space`          | `str`      | Serialized Gymnasium action space describing actions in dataset. |
 | `observation_space`     | `str`      | Serialized Gymnasium observation space describing observations in dataset. |
+| `minari_version`        | `str`      | Version specifier of Minari versions compatible with the dataset. |
 
 
 
@@ -528,23 +529,43 @@ Statistical metrics are also computed as metadata for the individual datasets in
 ## Observation and Action Spaces
 The Minari storage format supports the following observation and action spaces:
 
-### Observation Spaces
+### Supported Spaces
 
-| Observation Space                                                                                 | Description                                                                                              |
+| Space                                                                                 | Description                                                                                              |
 | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
 | [Discrete](https://github.com/Farama-Foundation/Gymnasium/blob/main/gymnasium/spaces/discrete.py) |Describes a discrete space where `{0, 1, ..., n-1}` are the possible values our observation can take. An optional argument can be used to shift the values to `{a, a+1, ..., a+n-1}`.|
 | [Box](https://github.com/Farama-Foundation/Gymnasium/blob/main/gymnasium/spaces/box.py)           |An n-dimensional continuous space. The `upper` and `lower` arguments can be used to define bounded spaces.|
 | [Tuple](https://github.com/Farama-Foundation/Gymnasium/blob/main/gymnasium/spaces/tuple.py)       |Represents a tuple of spaces.                                                                             |
 | [Dict](https://github.com/Farama-Foundation/Gymnasium/blob/main/gymnasium/spaces/dict.py)         |Represents a dictionary of spaces.                                                                        |
-
-### Action Spaces
-
-| Action Space                                                                                      | Description                                                                                               |
-| ------------------------------------------------------------------------------------------------- |---------------------------------------------------------------------------------------------------------- |
-| [Discrete](https://github.com/Farama-Foundation/Gymnasium/blob/main/gymnasium/spaces/discrete.py) |Describes a discrete space where `{0, 1, ..., n-1}` are the possible values our action can take. An optional argument can be used to shift the values to `{a, a+1, ..., a+n-1}`. |
-| [Box](https://github.com/Farama-Foundation/Gymnasium/blob/main/gymnasium/spaces/box.py)           |An n-dimensional continuous space. The `upper` and `lower` arguments can be used to define bounded spaces. |
-| [Tuple](https://github.com/Farama-Foundation/Gymnasium/blob/main/gymnasium/spaces/tuple.py)       |Represents a tuple of spaces.                                                                              |
-| [Dict](https://github.com/Farama-Foundation/Gymnasium/blob/main/gymnasium/spaces/dict.py)         |Represents a dictionary of spaces.                                                                         |
+| [Text](https://github.com/Farama-Foundation/Gymnasium/blob/main/gymnasium/spaces/text.py)         |The elements of this space are bounded strings from a charset. Note: at the moment, we don't guarantee support for all surrogate pairs.                                                                        |                                                                       |
 
 #### Space Serialization
 Spaces are serialized to a JSON format when saving to disk. This serialization supports all space types supported by Minari, and aims to be both human, and machine readable. The serialized action and observation spaces for the episodes in the dataset are saved as strings in the global HDF5 group metadata in `main_data.hdf5` for a particular dataset as `action_space` and `observation_space` respectively. All episodes in `main_data.hdf5` must have observations and actions that comply with these action and observation spaces. 
+
+## Minari Data Structures
+
+A Minari dataset is encapsulated in the `MinariDataset` class which allows for iterating and sampling through episodes which are defined as `EpisodeData` data class.
+
+### EpisodeData Structure
+
+Episodes can be accessed from a Minari dataset through iteration, random sampling, or even filtering episodes from a dataset through an arbitrary condition via the `filter_episodes` method. Take the following example where we load the `door-human-v0` dataset and randomly sample 10 episodes:
+
+```python
+dataset = minari.load_dataset("door-human-v0")
+sampled_episodes = dataset.sample_episodes(10)
+```
+
+The `sampled_episodes` variable will be a list of 10 `EpisodeData` elements, each containing episode data. An `EpisodeData` element is a data class consisting of the following fields:
+
+| Field             | Type                                 | Description                                                   |
+| ----------------- | ------------------------------------ | ------------------------------------------------------------- |
+| `id`              | `np.int64`                           | ID of the episode.                                            |
+| `seed`            | `np.int64`                           | Seed used to reset the episode.                               |
+| `total_timesteps` | `np.int64`                           | Number of timesteps in the episode.                           |
+| `observations`    | `np.ndarray`, `list`, `tuple`, `dict` | Observations for each timestep including initial observation. |
+| `actions`         | `np.ndarray`, `list`, `tuple`, `dict` | Actions for each timestep.                                    |
+| `rewards`         | `np.ndarray`                         | Rewards for each timestep.                                    |
+| `terminations`    | `np.ndarray`                         | Terminations for each timestep.                               |
+| `truncations`     | `np.ndarray`                         | Truncations for each timestep.                                |
+
+As mentioned in the `Supported Spaces` section, many different observation and action spaces are supported so the data type for these fields are dependent on the environment being used.

docs/content/minari_cli.md

@@ -52,7 +52,14 @@ The `minari list COMMAND` command shows a table with the existing Minari dataset
 This command comes with other two required sub-commands:
 
 - `remote`: the Minari dataset table shows the datasets currently available in the remote Farama server.
-- `local`: the Minari dataset table shows the datasets currently accessible in the local device. 
+- `local`: the Minari dataset table shows the datasets currently accessible in the local device.
+
+```{eval-rst}
+
+.. note::
+   These commands will list the latest remote/local dataset versions that are compatible with your local installed Minari version. To list all the dataset versions (also incompatible) add the option :code:`--all` or :code:`-a` to the command.
+
+```
 
 <div class="termy">
 
@@ -93,6 +100,13 @@ $ minari list remote
 With the command `minari download DATASETS` you can download a group of datasets that are available in the remote Farama server. If the dataset name already exist locally, the Minari CLI will prompt you to override the
 current content of the local dataset.
 
+```{eval-rst}
+
+.. note::
+   The download is aborted if the remote dataset is not compatible with your local installed Minari version or through a warning if the dataset already exists locally. To perform a force download add :code:`--force` or :code:`-f` to the download command.
+
+```
+
 <div class="termy">
 
 ```console