Skip to content

d.linegraph

Generates and displays simple line graphs in the active graphics monitor display frame.

d.linegraph [-xysl] x_file=string y_file=string [,string,...] [directory=string] [y_color=string [,string,...]] [color_table=style] [width=integer [,integer,...]] [title_color=string] [x_title=string] [y_title=string] [title=string] [y_range=min,max] [y_tics=float [,float,...]] [x_scale=float] [y_scale=float] [icon=string] [point_size=float] [secondary_color=name] [secondary_width=float [,float,...]] [--verbose] [--quiet] [--qq] [--ui]

Example:

d.linegraph x_file=string y_file=string

grass.script.run_command("d.linegraph", x_file, y_file, directory=None, y_color=None, color_table=None, width=None, title_color="black", x_title="", y_title="", title="", y_range=None, y_tics=None, x_scale=None, y_scale=None, icon="basic/circle", point_size=5, secondary_color="black", secondary_width=0.1, flags=None, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("d.linegraph", x_file="string", y_file="string")

Parameters

x_file=string [required]
    Name of data file for X axis of graph
y_file=string [,string,...] [required]
    Name of data file(s) for Y axis of graph
directory=string
    Path to files
    Path to the directory where the input files are located
y_color=string [,string,...]
    Color for Y data
color_table=style
    Name of color table
    Allowed values: aspect, aspectcolr, bcyr, bgyr, blues, byg, byr, celsius, corine, curvature, differences, elevation, etopo2, evi, fahrenheit, forest_cover, gdd, grass, greens, grey, grey.eq, grey.log, grey1.0, grey255, gyr, haxby, inferno, kelvin, magma, ndvi, ndwi, nlcd, oranges, plasma, population, population_dens, precipitation, precipitation_daily, precipitation_monthly, rainbow, ramp, random, reds, roygbiv, rstcurv, ryb, ryg, sepia, slope, soilmoisture, srtm, srtm_percent, srtm_plus, terrain, viridis, water, wave
        aspect     aspect: aspect oriented grey colors [range: map values]
        aspectcolr     aspectcolr: aspect oriented rainbow colors [range: 0 to 360]
        bcyr     bcyr: blue through cyan through yellow to red [range: map values]
        bgyr     bgyr: blue through green through yellow to red [range: map values]
        blues     blues: white to blue [range: map values]
        byg     byg: blue through yellow to green [range: map values]
        byr     byr: blue through yellow to red [range: map values]
        celsius     celsius: blue to red for degree Celsius temperature [range: -80 to 80]
        corine     corine: EU Corine land cover colors [range: 111 to 995]
        curvature     curvature: for terrain curvatures (from v.surf.rst and r.slope.aspect) [range: map values]
        differences     differences: differences oriented colors [range: map values]
        elevation     elevation: maps relative ranges of raster values to elevation color ramp [range: map values]
        etopo2     etopo2: colors for ETOPO2 worldwide bathymetry/topography [range: -11000 to 8850]
        evi     evi: enhanced vegetative index colors [range: -1 to 1]
        fahrenheit     fahrenheit: blue to red for Fahrenheit temperature [range: -112 to 176]
        forest_cover     forest_cover: percentage of forest cover [range: 0 to 100]
        gdd     gdd: accumulated growing degree days [range: 0 to 6000]
        grass     grass: GRASS GIS green (perceptually uniform) [range: map values]
        greens     greens: white to green [range: map values]
        grey     grey: grey scale [range: map values]
        grey.eq     grey.eq: histogram-equalized grey scale [range: map values]
        grey.log     grey.log: histogram logarithmic transformed grey scale [range: map values]
        grey1.0     grey1.0: grey scale for raster values between 0.0-1.0 [range: 0 to 1]
        grey255     grey255: grey scale for raster values between 0-255 [range: 0 to 255]
        gyr     gyr: green through yellow to red [range: map values]
        haxby     haxby: relative colors for bathymetry or topography [range: map values]
        inferno     inferno: perceptually uniform sequential color table inferno [range: map values]
        kelvin     kelvin: blue to red for temperature in Kelvin scale [range: 193.15 to 353.15]
        magma     magma: perceptually uniform sequential color table magma [range: map values]
        ndvi     ndvi: Normalized Difference Vegetation Index colors [range: -1 to 1]
        ndwi     ndwi: Normalized Difference Water Index colors [range: -200 to 200]
        nlcd     nlcd: US National Land Cover Dataset colors [range: 0 to 95]
        oranges     oranges: white to orange [range: map values]
        plasma     plasma: perceptually uniform sequential color table plasma [range: map values]
        population     population: color table covering human population classification breaks [range: 0 to 2e+09]
        population_dens     population_dens: color table covering human population density classification breaks [range: 0 to 1e+09]
        precipitation     precipitation: precipitation color table (0..2000mm) [range: 0 to 7000]
        precipitation_daily     precipitation_daily: precipitation color table (0..1000mm) [range: 0 to 10000]
        precipitation_monthly     precipitation_monthly: precipitation color table (0..1000mm) [range: 0 to 1000]
        rainbow     rainbow: rainbow color table [range: map values]
        ramp     ramp: color ramp [range: map values]
        random     random: random color table [range: map values]
        reds     reds: white to red [range: map values]
        roygbiv     roygbiv: [range: map values]
        rstcurv     rstcurv: terrain curvature (from r.resamp.rst) [range: map values]
        ryb     ryb: red through yellow to blue [range: map values]
        ryg     ryg: red through yellow to green [range: map values]
        sepia     sepia: yellowish-brown through to white [range: map values]
        slope     slope: r.slope.aspect-type slope colors for raster values 0-90 [range: 0 to 90]
        soilmoisture     soilmoisture: soilmoisture color table (0.0-1.0) [range: 0 to 1]
        srtm     srtm: color palette for Shuttle Radar Topography Mission elevation [range: -11000 to 8850]
        srtm_percent     srtm_percent: color palette for Shuttle Radar Topography Mission using relative elevation [range: map values]
        srtm_plus     srtm_plus: color palette for Shuttle Radar Topography Mission elevation (with seafloor colors) [range: -11000 to 8850]
        terrain     terrain: global elevation color table covering -11000 to +8850m [range: -11000 to 8850]
        viridis     viridis: perceptually uniform sequential color table viridis [range: map values]
        water     water: water depth [range: map values]
        wave     wave: color wave [range: map values]
width=integer [,integer,...]
    Width of the lines
title_color=string
    Color for axis, tics, numbers, and title
    Default: black
x_title=string
    Title for X data
    Default:
y_title=string
    Title for Y data
    Default:

title=string
    Title for Graph
    Default:
y_range=min,max
    Minimum and maximum value for Y axis (min,max)
y_tics=float [,float,...]
    Tic values for the Y axis
x_scale=float
    Scale for X values
y_scale=float
    Scale for Y values
icon=string
    Symbol for point
    Allowed values: basic/arrow, basic/arrow1, basic/arrow2, basic/arrow3, basic/box, basic/circle, basic/cross1, basic/cross2, basic/cross3, basic/diamond, basic/hexagon, basic/marker, basic/octagon, basic/pin, basic/pin_dot, basic/point, basic/pushpin, basic/star, basic/triangle, basic/x, demo/muchomurka, demo/smrk, extra/4pt_star, extra/adcp, extra/airport, extra/alpha_flag, extra/bridge, extra/dim_arrow, extra/dive_flag, extra/fiducial, extra/fish, extra/half-box, extra/half-circle, extra/offbox_ne, extra/offbox_nw, extra/offbox_se, extra/offbox_sw, extra/pentagon, extra/ping, extra/ring, extra/simple_zia, extra/target, geology/circle_cross, geology/half-arrow_left, geology/half-arrow_right, geology/strike_box, geology/strike_circle, geology/strike_cleavage, geology/strike_half-bowtie, geology/strike_line, geology/strike_parallel, geology/strike_triangle, legend/area, legend/area_curved, legend/line, legend/line_crooked, n_arrows/basic_compass, n_arrows/fancy_compass, n_arrows/n_arrow1a, n_arrows/n_arrow1b, n_arrows/n_arrow2, n_arrows/n_arrow3, n_arrows/n_arrow4, n_arrows/n_arrow5, n_arrows/n_arrow6, n_arrows/n_arrow7a, n_arrows/n_arrow7b, n_arrows/n_arrow8a, n_arrows/n_arrow8b, n_arrows/n_arrow9
    Default: basic/circle
point_size=float
    Point size
    Default: 5
secondary_color=name
    Color
    Color for point symbol edge color
    Default: black
secondary_width=float [,float,...]
    Width of point symbol lines
    Default: 0.1
-x
    Scale only X labels, not values
-y
    Scale only Y labels, not values
-s
    Draw points
-l
    Do not draw lines
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui**
    Force launching GUI dialog

x_file : str, required
    Name of data file for X axis of graph
y_file : str | list[str], required
    Name of data file(s) for Y axis of graph
directory : str, optional
    Path to files
    Path to the directory where the input files are located
y_color : str | list[str], optional
    Color for Y data
    Used as: color
color_table : str, optional
    Name of color table
    Used as: input, colortable, style
    Allowed values: aspect, aspectcolr, bcyr, bgyr, blues, byg, byr, celsius, corine, curvature, differences, elevation, etopo2, evi, fahrenheit, forest_cover, gdd, grass, greens, grey, grey.eq, grey.log, grey1.0, grey255, gyr, haxby, inferno, kelvin, magma, ndvi, ndwi, nlcd, oranges, plasma, population, population_dens, precipitation, precipitation_daily, precipitation_monthly, rainbow, ramp, random, reds, roygbiv, rstcurv, ryb, ryg, sepia, slope, soilmoisture, srtm, srtm_percent, srtm_plus, terrain, viridis, water, wave
        aspect     aspect: aspect oriented grey colors [range: map values]
        aspectcolr     aspectcolr: aspect oriented rainbow colors [range: 0 to 360]
        bcyr     bcyr: blue through cyan through yellow to red [range: map values]
        bgyr     bgyr: blue through green through yellow to red [range: map values]
        blues     blues: white to blue [range: map values]
        byg     byg: blue through yellow to green [range: map values]
        byr     byr: blue through yellow to red [range: map values]
        celsius     celsius: blue to red for degree Celsius temperature [range: -80 to 80]
        corine     corine: EU Corine land cover colors [range: 111 to 995]
        curvature     curvature: for terrain curvatures (from v.surf.rst and r.slope.aspect) [range: map values]
        differences     differences: differences oriented colors [range: map values]
        elevation     elevation: maps relative ranges of raster values to elevation color ramp [range: map values]
        etopo2     etopo2: colors for ETOPO2 worldwide bathymetry/topography [range: -11000 to 8850]
        evi     evi: enhanced vegetative index colors [range: -1 to 1]
        fahrenheit     fahrenheit: blue to red for Fahrenheit temperature [range: -112 to 176]
        forest_cover     forest_cover: percentage of forest cover [range: 0 to 100]
        gdd     gdd: accumulated growing degree days [range: 0 to 6000]
        grass     grass: GRASS GIS green (perceptually uniform) [range: map values]
        greens     greens: white to green [range: map values]
        grey     grey: grey scale [range: map values]
        grey.eq     grey.eq: histogram-equalized grey scale [range: map values]
        grey.log     grey.log: histogram logarithmic transformed grey scale [range: map values]
        grey1.0     grey1.0: grey scale for raster values between 0.0-1.0 [range: 0 to 1]
        grey255     grey255: grey scale for raster values between 0-255 [range: 0 to 255]
        gyr     gyr: green through yellow to red [range: map values]
        haxby     haxby: relative colors for bathymetry or topography [range: map values]
        inferno     inferno: perceptually uniform sequential color table inferno [range: map values]
        kelvin     kelvin: blue to red for temperature in Kelvin scale [range: 193.15 to 353.15]
        magma     magma: perceptually uniform sequential color table magma [range: map values]
        ndvi     ndvi: Normalized Difference Vegetation Index colors [range: -1 to 1]
        ndwi     ndwi: Normalized Difference Water Index colors [range: -200 to 200]
        nlcd     nlcd: US National Land Cover Dataset colors [range: 0 to 95]
        oranges     oranges: white to orange [range: map values]
        plasma     plasma: perceptually uniform sequential color table plasma [range: map values]
        population     population: color table covering human population classification breaks [range: 0 to 2e+09]
        population_dens     population_dens: color table covering human population density classification breaks [range: 0 to 1e+09]
        precipitation     precipitation: precipitation color table (0..2000mm) [range: 0 to 7000]
        precipitation_daily     precipitation_daily: precipitation color table (0..1000mm) [range: 0 to 10000]
        precipitation_monthly     precipitation_monthly: precipitation color table (0..1000mm) [range: 0 to 1000]
        rainbow     rainbow: rainbow color table [range: map values]
        ramp     ramp: color ramp [range: map values]
        random     random: random color table [range: map values]
        reds     reds: white to red [range: map values]
        roygbiv     roygbiv: [range: map values]
        rstcurv     rstcurv: terrain curvature (from r.resamp.rst) [range: map values]
        ryb     ryb: red through yellow to blue [range: map values]
        ryg     ryg: red through yellow to green [range: map values]
        sepia     sepia: yellowish-brown through to white [range: map values]
        slope     slope: r.slope.aspect-type slope colors for raster values 0-90 [range: 0 to 90]
        soilmoisture     soilmoisture: soilmoisture color table (0.0-1.0) [range: 0 to 1]
        srtm     srtm: color palette for Shuttle Radar Topography Mission elevation [range: -11000 to 8850]
        srtm_percent     srtm_percent: color palette for Shuttle Radar Topography Mission using relative elevation [range: map values]
        srtm_plus     srtm_plus: color palette for Shuttle Radar Topography Mission elevation (with seafloor colors) [range: -11000 to 8850]
        terrain     terrain: global elevation color table covering -11000 to +8850m [range: -11000 to 8850]
        viridis     viridis: perceptually uniform sequential color table viridis [range: map values]
        water     water: water depth [range: map values]
        wave     wave: color wave [range: map values]
width : int | list[int] | str, optional
    Width of the lines
title_color : str, optional
    Color for axis, tics, numbers, and title
    Used as: color
    Default: black
x_title : str, optional
    Title for X data
    Default:
y_title : str, optional
    Title for Y data
    Default:

title : str, optional
    Title for Graph
    Default:
y_range : tuple[float, float] | list[float] | str, optional
    Minimum and maximum value for Y axis (min,max)
    Used as: min,max
y_tics : float | list[float] | str, optional
    Tic values for the Y axis
x_scale : float, optional
    Scale for X values
y_scale : float, optional
    Scale for Y values
icon : str, optional
    Symbol for point
    Allowed values: basic/arrow, basic/arrow1, basic/arrow2, basic/arrow3, basic/box, basic/circle, basic/cross1, basic/cross2, basic/cross3, basic/diamond, basic/hexagon, basic/marker, basic/octagon, basic/pin, basic/pin_dot, basic/point, basic/pushpin, basic/star, basic/triangle, basic/x, demo/muchomurka, demo/smrk, extra/4pt_star, extra/adcp, extra/airport, extra/alpha_flag, extra/bridge, extra/dim_arrow, extra/dive_flag, extra/fiducial, extra/fish, extra/half-box, extra/half-circle, extra/offbox_ne, extra/offbox_nw, extra/offbox_se, extra/offbox_sw, extra/pentagon, extra/ping, extra/ring, extra/simple_zia, extra/target, geology/circle_cross, geology/half-arrow_left, geology/half-arrow_right, geology/strike_box, geology/strike_circle, geology/strike_cleavage, geology/strike_half-bowtie, geology/strike_line, geology/strike_parallel, geology/strike_triangle, legend/area, legend/area_curved, legend/line, legend/line_crooked, n_arrows/basic_compass, n_arrows/fancy_compass, n_arrows/n_arrow1a, n_arrows/n_arrow1b, n_arrows/n_arrow2, n_arrows/n_arrow3, n_arrows/n_arrow4, n_arrows/n_arrow5, n_arrows/n_arrow6, n_arrows/n_arrow7a, n_arrows/n_arrow7b, n_arrows/n_arrow8a, n_arrows/n_arrow8b, n_arrows/n_arrow9
    Default: basic/circle
point_size : float, optional
    Point size
    Default: 5
secondary_color : str, optional
    Color
    Color for point symbol edge color
    Used as: input, color, name
    Default: black
secondary_width : float | list[float] | str, optional
    Width of point symbol lines
    Default: 0.1
flags : str, optional
    Allowed values: x, y, s, l
    
x
        Scale only X labels, not values
    
y
        Scale only Y labels, not values
    
s
        Draw points
    
l
        Do not draw lines
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

d.linegraph is a module to draw simple x,y line graphs (plots) based on numerical data contained in separate files.

Data format

The X and Y data files for the graph are essentially a column of numbers in each file, with one input number per line. The program expects that each X value will have a corresponding Y value, therefore the number of lines in each data input file should be the same. Essentially, the X data becomes the X axis reference to which the Y data is plotted as a line. Therefore, the X data should be a monotonically increasing progression of numbers (i.e. "1,2,3,..."; "0, 10, 100, 1000,..."; "...-5,-1,0,1,5..."). If multiple Y data files are used, the Y axis scale will be based on the range of minimum and maximum values from all Y files, then all Y data given will be graphed according to that Y scale. Therefore, if multiple Y data inputs are used with dissimilar units, the graph produced comparing the two will be deceptive.

File inputs

If the directory option is provided, the paths to files can (and should) be only relative paths to these files. While this is not recommended for scripting, it can be advantageous when typing the paths manually. For example when all files are stored in the directory /home/john/data, the user can provide the following in the command line:

d.linegraph directory=/home/john/data x_file=x.txt y_file=y1.txt,y2.txt

Managing colors

The user can specify the y_color option, the color_table option or just leave the defaults to influence the color of the plotted lines.

Colors specified by y_color option are used for drawing the lines in the graph. If multiple Y data files are used, an equal number of colors may be used to control the colors of the lines. Colors will be assigned to Y data in respect to the sequence of instantiation on the command line. It can be one of GRASS GIS named colors or the RGB values from 0-255 separated by colons (RRR:GGG:BBB).

Alternatively, the user can use the color_table option to specify one of the GRASS GIS predefined color tables.

By default, a series of colors will be chosen by the module if none are provided upon invocation. The order of default colors is red, green, violet, blue, orange, gray, brown, magenta, white, and indigo. The user is advised not to rely on the order of default colors but to either use the y_color or the color_table option to obtain predictable and reproducible results.

The color to be used for titles, axis lines, tics, and scale numbers is determined by the title_color option. The user can provide one of the GRASS GIS named colors (such as gray, white, or black) or use the GRASS GIS colon-separated format for RGB (RRR:GGG:BBB).

Titles, labels, and tics

The title option specifies the text for the title of the graph. It will be centered over the top of graph. The x_title option is a text to describe data for X axis. It will be centered beneath the graph. Default is no text unless there is a need for a unit descriptor determined by the d.linegraph module, then string such as "in hundreds" is generated. The y_title option is a text to describe data for Y axis. It will be centered beneath the X data description. Similarly, to the x_title option, default is no text unless there is a need for an auto-generated description. In the case of graphs with multiple lines (multiple inputs for Y axis), user may wish to use more specific text placement using the d.text or v.label programs.

NOTES

For historical reasons, the d.linegraph module accepts titles of more than one word where the underscore character ("_") is used to represent spaces (" "). For example "Census_data_1990" would be printed over the graph as "Census data 1990". The use of underscores is not necessary to use as long as the parameter is quoted in the command line. In general, use of underscores is not recommended and there is no need to use it at all in the GUI or when using d.linegraph in Python scripts.

The way the program locates and labels tic marks is less than perfect:

1) although distances between Y tics are proportional to the value, they are not proportional on the X axis;
2) decimal values between -1 and 1 can be printed on the X axis, but not on Y. (With respect to the later, the input for Y values can all be multiplied by a factor of 10 before graphing).

Depending on the user's needs, it might be easier or more appropriate to use a 3rd party tool such as xgraph, gnuplot, Matplotlib in Python, or R instead of d.linegraph. For a more general solution for plotting in GRASS GIS, the user is advised to use the d.graph module.

EXAMPLE

The following can be executed in Bash to create the input data for this example. The user can just create these files in a text editor, save them and specify path to them.

cat > x.txt <<EOF
1
3
4
6
9
EOF
cat > y1.txt <<EOF
50
58
65
34
27
EOF
cat > y2.txt <<EOF
10
20
35
50
45
EOF

The next command sequence creates a file plot.png in the current directory which is the drawing made by d.linegraph.

d.mon start=cairo output=plot.png width=400 height=400
d.linegraph x_file=x.txt y_file=y1.txt,y2.txt
d.mon stop=cairo

SEE ALSO

d.frame, d.text, v.label, d.graph, d.histogram

AUTHOR

Chris Rewerts, Agricultural Engineering, Purdue University

SOURCE CODE

Available at: d.linegraph source code (history)
Latest change: Friday Feb 07 19:16:09 2025 in commit a82a39f