HoloViews Documentation

HoloViews provides a variety of example notebooks organized by purpose. You can find specific examples in the following directories:

• gallery: Examples featured on the official HoloViews gallery page.
• getting_started: Notebooks designed for beginners, following the official getting started guide.
• reference: Notebooks used in the reference gallery for specific API or feature lookups.
• user_guide: Notebooks that accompany the official HoloViews user guide.

HoloViews provides tools for managing and transforming scientific or engineering data:

• Annotation: Annotate data with dimensions, units, labels, and data ranges.
• High-Dimensional Slicing: Easily slice and access regions of data regardless of dimensionality.
• Dimensionality Reduction: Apply functions to collapse data or reduce dimensionality.
• Extensibility: Highly extensible system to add new operations for custom data transformations.

HoloViews provides several core workflows for data visualization:

• Data Annotation: Use semantic metadata to annotate your data.
• Composition: Use the + and * operators to compose elements into layouts and overlays.
• Customization: Use the options system to declare visual customizations.
• Style Mapping: Map data values to visual attributes of a plot.
• Dimensioned Containers: Use multi-dimensional containers for animation and faceting.
• Data Selection: Index and select subsets of your data using HoloViews primitives.
• Transformations: Apply operations to build data analysis pipelines.
• Interactivity: Respond to Python events using the 'streams' system, use 'linked streams' for Bokeh interaction, or build interactive dashboards with external widget libraries.

The HoloViews 'Getting Started' guide provides a structured path for new users to become productive. It is recommended to follow the guide in order to build a foundational understanding of the library. The learning path covers:

1. Introduction: Understanding what HoloViews is and its core purpose.
2. Customization: Learning how to modify the visual representation of elements.
3. Tabular Datasets: Working with structured, table-like data.
4. Gridded Datasets: Working with array-based or multidimensional data.
5. Live Data: Handling dynamically generated or streaming data.

For specific components or primitives, refer to the Reference Gallery. For practical inspiration, visit the Gallery.

HoloViews uses pre-commit for linting.

• Run linting on all files: pixi run lint
• Install automatic linting on commit: pixi run lint-install (Recommended, as CI will fail if linting does not pass).

If you have pre-commit installed independently, you can also use:

pre-commit install
pre-commit run --all-files

HoloViews uses pixi to manage development environments and tasks. To start developing, follow these steps:

1. Clone and Fork: Fork the repository on GitHub and clone your fork locally.
2. Install Dependencies: Run pixi run install to create the default environment and install HoloViews in editable mode.
3. Download Data: Run pixi run download-data to fetch data required for tests and examples.

Alternatively, you can run pixi run setup-dev to perform both installation and data downloading in one step.

Note: The first time you run pixi, it creates a .pixi directory. Avoid placing your source directory in a cloud-synced folder as this directory can become quite large.

pixi run install
pixi run download-data
# Or use the shortcut:
pixi run setup-dev

HoloViews supports various data structures for exploration:

• Tabular Datasets: Works with NumPy, pandas, and dask.
• Gridded Datasets: Works with n-dimensional arrays using NumPy and XArray.
• Geometry Data: Represents and visualizes path and polygon geometries, including support for multi-geometries and value dimensions.
• Large Datasets: Leverage Datashader to interactively explore millions or billions of datapoints, including using selector for fast interactive hover tooltips.

Use pixi commands to interact with different development environments and tasks:

• List all tasks: pixi task list
• Activate environment: pixi shell (similar to conda activate or source venv/bin/activate).
• Run task in specific environment: Use the -e flag. For example, to install in the test-core environment: pixi run -e test-core install.
• Update Pixi: pixi self-update to get the latest version of the package manager.

Build the documentation locally using:

pixi run docs-build

Note: Building documentation can take approximately one hour because it processes many notebooks. To speed up local builds, you can disable the galleries using environment variables:

• Disable gallery: export HV_DOC_GALLERY=False
• Disable reference gallery: export HV_DOC_REF_GALLERY=False