Lets-Plot Documentation

When using a "dev" version of the Python package, lets-plot embeds the current development JS into Jupyter notebooks. To serve the development JS script from the js-package project:

1. Build the development JS package:

./gradlew js-package:jsBrowserDevelopmentWebpack

2. Start a local web server to serve the files (e.g., on port 8080):

python -m http.server 8080

The JS library can be found in the js-package/build/kotlin-webpack/js/developmentExecutable folder.

To debug plots by extracting their JSON specification from a Jupyter notebook, follow these steps:

1. Install pickleshare: Run !pip install pickleshare in a Jupyter cell and restart the kernel.
2. Install the hook: Run the installation script to add the _repr_html_ hook to your IPython startup directory (typically ~/.ipython/profile_default/startup/):

   ./install_lets_plot_hook.sh

3. Generate Plot: Run any cell that produces a plot.
4. Copy Spec: Click the "Copy Spec" button located in the top-right corner of the plot to copy the JSON string to your clipboard.
5. Use in Debugger: Use the copied JSON string by setting the PLOT_SPEC environment variable in the PlotSpecDebugger Run Configuration, or paste it directly into the app's editor element.

To build the custom manylinux_x64 Docker image (which includes ImageMagick), navigate to the manylinux-x64-image directory and run the provided build script.

cd manylinux-x64-image
./build_image.sh

To install your locally built version of lets-plot:

1. Change directory to lets-plot/python-package.
2. Create or activate your desired Python environment.
3. Run the following command to reinstall the package from the local dist/ directory without dependencies:

pip install --no-index --find-links=dist/ lets-plot --no-deps --force-reinstall

To build custom manylinux images (which include ImageMagick) for Lets-Plot, your Linux build host must meet these requirements:

1. Docker: Must be installed on the host.
2. QEMU: Required for cross-architecture builds (specifically for aarch64 on x86_64 hosts). On Ubuntu, install via:

   sudo apt update && sudo apt install qemu binfmt-support qemu-user-static

3. QEMU Registration: Register the QEMU script using the multiarch/qemu-user-static Docker image:

   docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

4. QEMU Binary: Copy the qemu-aarch64-static binary to the manylinux-arm-image directory:

   cp /usr/bin/qemu-aarch64-static ./manylinux-arm-image/.

To run the browser-based demos, you must first build the JavaScript package module, then build the browser demo module, and finally execute a demo using the demoRunnerMain entry point.

1. Build the js-package module: ./gradlew :js-package:build
2. Build the demo-plot-browser module: ./gradlew :demo-plot-browser:build
3. Run any demo inside the demoRunnerMain.

Lets-Plot provides a bridge between R (ggplot2) and Python for data visualization. For detailed usage, API references, and tutorials, visit the official Python documentation site.

https://lets-plot.org/python

To work with the Python sources in IntelliJ IDEA (IDEA), you must create a Python module manually as this is not a Gradle-based module.

1. Create the Conda environment: Use the provided environment file to create an environment named lets-plot-python-module.
2. Configure IDEA:
   • Ensure the IDEA Python plugin is installed.
   • Create a new Python module with the content root set to <path>/lets-plot/python-package.
   • Set the lets-plot-python-module conda environment as the "Module SDK" for this module.
3. Configure Test Runner: To run Python tests within IDEA, set pytest as the test runner in Preferences | Tools | Python Integrated Tools.

conda env create -f lets-plot/python-package/module_env.yml

To run tests against the lets-plot package installed in your module environment, follow these steps:

1. Navigate to the package directory: lets-plot/python-package.
2. Update the lets-plot-python-module conda environment using the module_env.yml file.
3. Install the development version of Lets-Plot into the lets-plot-python-module environment using the local distribution files.

Depending on your changes, you can perform a full build or a targeted Python-only build.

Full Build with Gradle

Use this method to build both the Kotlin multiplatform binaries and the Python package. The target Python version is determined by your local.properties configuration.

./gradlew :python-package-build:build

Python Package Only Build

If you have only modified Python code, you can rebuild just the Python wheel. Prerequisites:

• You must be inside the python-package directory.
• You must have an active Python environment with the build package installed.
• The resulting wheel will target the Python version of your active environment.

python -m build -w

Lets-Plot supports several Kotlin environments:

• Notebooks: Create plots in Kotlin Notebook, Datalore, Jupyter with Kotlin Kernel, or any notebook supporting a Kotlin Kernel.
• Compose Multiplatform: Embed charts in Compose Multiplatform applications via the Lets-Plot Compose Frontend project.
• JVM and Kotlin/JS: Embed charts in JVM (Swing, JavaFX) and Kotlin/JS applications.

For the core API, refer to the Lets-Plot Kotlin API project. Documentation is available at lets-plot.org/kotlin.