datamapplot

Widgets can declare specific JavaScript and CSS dependencies using a dependencies list. Dependencies follow the format type:name (e.g., js:d3 or css:histogram).

• js:name: Loads a local JavaScript file from the project's static directory.
• css:name: Loads a local CSS file from the project's static directory.
• http...: If the dependency string starts with http, it is treated as an external CDN library.

Dependency Loading Priority:

1. Core DataMap files (datamap.js, data_selection_manager.js).
2. Widget-specific JS files.
3. Widget-specific CSS files.
4. External CDN libraries.

class HistogramWidget(WidgetBase):
    dependencies = ["js:d3", "js:histogram", "css:histogram"]

# Example of how dependencies are parsed internally
# 'js:d3' -> type: 'js', name: 'd3'
# 'https://cdn...' -> type: 'external', name: 'https://cdn...'

DataMapPlot provides two distinct ways to handle offline requirements:

Use use_system_fonts for simple static plots. For interactive plots that need to work offline, use the offline_mode configuration which caches JavaScript dependencies and fonts.

In datamapplot, widgets are self-contained components that interact through a central communication hub: window.datamap.

Instead of direct widget-to-widget communication, widgets register themselves with the datamap instance. Events (such as a selection in a HistogramWidget) flow through the datamap selection system, allowing other widgets (like a LegendWidget) to react to those changes. This architecture ensures that widgets remain decoupled while still enabling complex, interactive data visualizations.

The datamapplot.selection_handlers module provides a set of classes designed to handle user interactions and data selection within plots. By implementing or using these handlers, you can extend the functionality of your data maps to include features like word clouds, summaries, or tag-based filtering.

Available selection handler classes include:

• SelectionHandlerBase: The base class for all selection handlers.
• DisplaySample: Likely used for displaying specific data samples upon selection.
• WordCloud: Generates a word cloud based on selected data.
• CohereSummary: Provides summaries using Cohere (requires integration with Cohere).
• TagSelection: Handles selection based on specific tags.

Examples serve as both documentation and end-to-end tests. When adding a new example to the examples/ directory, ensure it follows these requirements:

1. Descriptive Docstring: Include a title and explanation.
2. Standalone: The script must be runnable on its own.
3. Realistic Data: Use data that is realistic but manageable.
4. Specific Use Case: Demonstrate a particular feature or capability.

Workflow:

1. Create a new .py file in examples/ (e.g., plot_new_feature.py).
2. Implement the example following the structure above.
3. Verify it runs without errors.
4. Add it to the documentation and (optionally) include it in the CI pipeline.

DataMapPlot provides two primary functions for generating plots: create_plot for static plots and create_interactive_plot for interactive HTML plots. Both functions require the coordinates of the data map and an array or list of labels for the data points. You can pass additional keyword arguments (**style_keywords) to customize the aesthetic output.

import datamapplot

datamapplot.create_plot(data_map_coords, data_map_labels, **style_keywords)

DataMapPlot returns standard Matplotlib Figure and Axes objects. You can use these objects to apply any standard Matplotlib commands to add extra elements or modify the plot.

Note: Custom modifications are performed at your own risk as they may interact with the library's internal rendering logic.

DataMapPlot uses Sphinx with Read the Docs. Documentation is written in reStructuredText (.rst) or Jupyter Notebooks (.ipynb) and is located in the doc/ directory. To build the HTML documentation on your local machine, install the documentation dependencies and use make html within the doc directory.

To view the built documentation, open _build/index.html in your web browser.

# Install documentation dependencies
pip install -r doc/requirements.txt

# Build HTML documentation
cd doc
make html

# View the documentation (open _build/index.html in a browser)

To develop for DataMapPlot, you need Python 3.10+ (3.10, 3.11, or 3.12 recommended), Git, and Node.js. Follow these steps to configure your environment:

1. Clone the repository
2. Install Python dependencies: Install the package in editable mode, then install testing and documentation requirements.
3. Install Node.js dependencies: Required for running interactive Playwright tests.

Note: Use a virtual environment for Python dependencies.

# 1. Clone the repository
git clone https://github.com/TutteInstitute/datamapplot.git
cd datamapplot

# 2. Install Python dependencies
pip install -e .
pip install -r test-requirements.txt
pip install -r doc/requirements.txt

# 3. Install Node.js dependencies (for interactive tests)
cd datamapplot/interactive_tests
npm ci
npx playwright install --with-deps