DOCSEARCHbyAlgolia
Submit Docs

Minari Documentation

repository·main·Indexed 23 days ago

https://github.com/farama-foundation/minari

A Python library for offline reinforcement learning research providing a standard format for datasets. Minari includes tools to manage, load, and create datasets, featuring a CLI for dataset interaction, the MinariDataset class for sampling and filtering episodes, and the DataCollector for recording experience from Gymnasium environments.

Tokens
13.8K
Snippets
25
Records
95
Agent score
79%

What's inside Minari

  1. Understand Minari dataset ID syntax and structure

    main

    Minari dataset directories are named using a specific id syntax: (namespace/)(env_name/)dataset_name(-v(version)).

    • namespace: (Optional) A string for grouping datasets (e.g., D4RL/). Can be arbitrarily nested.
    • env_name: (Optional) Describes the environment (e.g., door/).
    • dataset_name: A string describing the content (e.g., human).
    • version: An integer representing the version, starting from 0 (e.g., -v0).

    Examples:

    • door/human-v0 (No namespace)
    • D4RL/door/human-v0 (With namespace)

  2. Use minari.DataCollector for data collection

    main

    The minari.DataCollector class is used to collect experience from an environment and save it into a Minari dataset. It provides a structured way to record steps, manage episode buffers, and eventually write the collected data to a dataset on disk.

    Key lifecycle methods include:

    • step(): Records a single transition (step) in the environment.
    • reset(): Resets the internal buffers for a new episode.
    • create_dataset(): Initializes a new dataset on disk.
    • add_to_dataset(): Appends collected episodes to an existing dataset.
    • close(): Finalizes the collection process.

  3. Use namespaces to group Minari datasets

    main

    Minari supports hierarchical organization of datasets using namespaces. You can create a namespace by including a forward slash / in the dataset_id.

    For example, using dataset_id="classic_control/cartpole-test-v0" will store the dataset within the classic_control namespace. This allows you to group related datasets (e.g., all classic control environments) together. Namespaces can also be managed via the Namespace API.

  4. Build the Minari documentation

    main

    To build the documentation locally, you must first clone the repository, install Minari in editable mode, and install the documentation requirements.

    To perform a one-time build, use make dirhtml within the docs directory.

    To enable live rebuilding (automatic updates whenever a change is detected), use sphinx-autobuild within the docs directory.

    # Install dependencies
git clone https://github.com/Farama-Foundation/Minari.git --single-branch
cd Minari
pip install -e .
pip install -r docs/requirements.txt

# Build once
cd docs
make dirhtml

# Rebuild automatically on change
cd docs
sphinx-autobuild -b dirhtml . _build

  6. Download and list remote Minari datasets

    main

    Minari provides access to remote datasets hosted on servers like Google Cloud Platform (GCP) and Hugging Face Hub.

    To list available datasets on the remote Farama server, use the minari list remote command.

    To download a specific dataset to your local storage, use the minari download command followed by the dataset name.

    To use a custom remote server, set the MINARI_REMOTE environment variable using the format remote-type://remote-path (e.g., gcp://my-datasets). For Hugging Face, use hf://username-or-org (e.g., hf://farama-minari).

  7. Install Minari from source

    main

    If you want to contribute to Minari or test the latest development version, install it from the GitHub repository in editable mode with all dependencies.

    git clone https://github.com/Farama-Foundation/Minari.git --single-branch
cd Minari
pip install -e ".[all]"

  8. Load and inspect local Minari datasets

    main

    Minari can only load datasets stored in your local root directory. Use minari list local to see which datasets are currently available locally.

    To use a dataset in Python, load it as a minari.MinariDataset object using minari.load_dataset(). Once loaded, you can inspect its properties such as observation_space, action_space, total_episodes, and total_steps.

    import minari

# List local datasets via CLI
# minari list local

# Load dataset in Python
dataset = minari.load_dataset('D4RL/door/human-v2')
print("Observation space:", dataset.observation_space)
print("Action space:", dataset.action_space)
print("Total episodes:", dataset.total_episodes)
print("Total steps:", dataset.total_steps)

  9. How to add a dataset group to the Minari community page

    main

    To contribute a dataset group to the Minari community documentation, you must submit a Pull Request that modifies the docs/datasets/community/community.yaml file. You need to add a new entry to this YAML file following a specific schema.

    Each entry requires two fields:

    1. dataset_group: The full path to the dataset group (e.g., hf://username/group-name).
    2. display_name: A human-readable name for the group.

    After editing the file, you can optionally run the local generator script to preview how your changes will appear on the documentation site.

    - dataset_group: hf://your-username/your-group-name  # Full path to dataset group
  display_name: Your Dataset Group Name              # Human-readable name
    python docs/_scripts/gen_community.py

  10. Install Minari

    main

    You can install the latest version of Minari using pip. To install the core library with minimum dependencies, use pip install minari. To install all available dependencies for various use cases at once, use the [all] extra.

    If you are contributing to the project or want to install from source, clone the repository and install in editable mode with the [all] extra.

    # Install minimum dependencies
pip install minari

# Install all dependencies
pip install "minari[all]"

# Install from source for development
git clone https://github.com/Farama-Foundation/Minari.git --single-branch
cd Minari
pip install -e ".[all]"

  12. Create a Minari dataset using DataCollector

    main

    To collect data for a Minari dataset, use the minari.DataCollector wrapper around a Gymnasium environment. The wrapper manages internal memory buffers and computes metadata during collection.

    1. Initialize: Wrap your environment with DataCollector. Use record_infos=True if you want to include the info dictionaries returned by the environment in your dataset.
    2. Collect: Run your environment using the standard Gymnasium MDP API (looping through reset() and step()).
    3. Save: Call env.create_dataset() to move the buffered data to a permanent location in the local Minari root path. You must provide a dataset_id and metadata like algorithm_name, code_permalink, author, and author_email.
    import minari
import gymnasium as gym
from minari import DataCollector

# 1. Initialize the wrapper
env = gym.make('CartPole-v1')
env = DataCollector(env, record_infos=True)

total_episodes = 100

# 2. Collect data using standard Gymnasium API
for _ in range(total_episodes):
    env.reset(seed=123)
    while True:
        action = env.action_space.sample()  # random policy
        obs, rew, terminated, truncated, info = env.step(action)
        if terminated or truncated:
            break

# 3. Save the dataset with metadata
dataset = env.create_dataset(
    dataset_id="cartpole/test-v0",
    algorithm_name="Random-Policy",
    code_permalink="https://github.com/Farama-Foundation/Minari",
    author="Farama",
    author_email="contact@farama.org"
)