Skip to content

Latest commit

 

History

History
128 lines (91 loc) · 6.34 KB

README.md

File metadata and controls

128 lines (91 loc) · 6.34 KB
Raw

The GR module for Julia

The MIT License GitHub tag GR Downloads DOI Binder Join the chat at https://gitter.im/jheinen/GR.jl

PkgEval CI Coverage Status

Screenshots

This module provides a Julia interface to GR, a framework for visualisation applications.

Installation

From the Julia REPL an up to date version can be installed with:

julia> using Pkg
julia> Pkg.add("GR")

or in the Pkg REPL-mode:

pkg> add GR

The Julia package manager will download and install a pre-compiled run-time (for your hardware architecture), if the GR software is not already installed in the recommended locations.

Getting started

In Julia simply type using GR and begin calling functions in the GR framework API.

Let's start with a simple example. We generate 10,000 random numbers and create a histogram. The histogram function automatically chooses an appropriate number of bins to cover the range of values in x and show the shape of the underlying distribution.

using GR
histogram(randn(10000))

Using GR as backend for Plots.jl

Plots is a powerful wrapper around other Julia visualization "backends", where GR seems to be one of the favorite ones. To get an impression how complex visualizations may become easier with Plots, take a look at these examples.

Plots is great on its own, but the real power comes from the ecosystem surrounding it. You can find more information here.

Alternatives

Besides GR and Plots there is a nice package called GRUtils which provides a user-friendly interface to the low-level GR subsytem, but in a more "Julian" and modular style. Newcomers are recommended to use this package. A detailed documentation can be found here.

GR and GRUtils are currently still being developed in parallel - but there are plans to merge the two modules in the future.

Run-time environment

GR.jl is a wrapper for the GR Framework. Therefore, the GR run-time libraries are required to use the software. These are provided via the GR_jll.jl package, which is an autogenerated package constructed using BinaryBuilder. This is the default setting.

Another alternative is the use of binaries from GR tarballs, which are provided directly by the GR developers as stand-alone distributions for selected platforms - regardless of the programming language. In this case, only one GR runtime environment is required for different language environments (Julia, Python, C/C++), whose installation path can be specified by the environment variable GRDIR.

ENV["JULIA_DEBUG"] = "GR" # Turn on debug statements for the GR package
ENV["GRDIR"] = "<path of you GR installation>" # e.g. "/usr/local/gr"
using GR

For more information about setting up a local GR installation, see the GR Framework website.

However, if you want to permanently use your own GR run-time, you have to set the environment variable GRDIR accordingly before starting Julia, e.g.

  • macOS or Linux: export GRDIR=/usr/local/gr
  • Windows: set GRDIR=C:\gr

Please note that with the method shown here, GR_jll is not imported.

Switching binaries via GR.GRPreferences

To aid in switching between BinaryBuilder and upstream framework binaries, the GR.GRPReferences module implements three methods use_system_binary(), use_upstream_binary(), and use_jll_binary(). These use Preferences.jl to configure GR.jl and GR_jll.jl.

To use an existing GR install, invoke use_system_binary.

using GR
GR.GRPreferences.use_system_binary("/path/to/gr"; force = true)

To download and switch to upstream binaries invoke use_upstream_binary.

using GR # repeat this if there is an error
GR.GRPreferences.use_upstream_binary(; force = true)

use_system_binary and use_upstream_binary accept an override keyword. This may be set to one of the following:

  • :depot (default) - Use Overrides.toml in the Julia depot. This normally resides in .julia/artifacts/Overrides.toml
  • :project - Use LocalPreferences.toml. This is usually located near the Project.toml of your active project environment.
  • (:depot, :project) - Use both of the override mechanisms above.

To switch back to BinaryBuilder binaries supplied with GR_jll, invoke use_jll_binary:

using GR # repeat this if there is an error
GR.GRPreferences.use_jll_binary(; force = true)

This will reset both the :depot and :project override mechanisms above.

If you encounter difficulties switching between binaries, the diagnostics() function will provide useful information. Please include this information when asking for assistance.

using GR
GR.GRPreferences.diagnostics()