Difference between revisions of "Module:Graph/doc"
m (1 revision imported) |
Template>Pietrasagh |
||
Line 1: | Line 1: | ||
− | Module with helper functions for the [[ | + | {{#if:{{{1|}}}||<!-- Parts not to be transcluded from the wrapper templates --> |
+ | {{Module rating |alpha}} | ||
+ | {{Lua sidebar}} | ||
+ | <!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) --> | ||
+ | Module with helper functions for the [[Help:Graph|Graph]] extension to display graphs and maps. From [[:de:Modul:Graph]]. | ||
== Functions for templates == | == Functions for templates == | ||
=== <code>map</code> === | === <code>map</code> === | ||
− | Creates a JSON object for <code><nowiki><graph></nowiki></code> to display a political map with colored highlights. | + | Creates a JSON object for <code><nowiki><graph></nowiki></code> to display a political map with colored highlights. In the article namespace the template {{Template|Graph:Map}} should be used instead. See its page for use cases. |
− | Maps can be found at [[Special: | + | Maps can be found at [[Special:Prefixindex/Template:Graph:Map/Inner/]] (for example [[Template:Graph:Map/Inner/Worldmap2c-json|Worldmap2c-json]] with country borders) and new maps should also be saved under Module:Graph/. |
'''Parameters:''' | '''Parameters:''' | ||
− | * '''basemap:''' sets the base map. The map definitions must follow the [https://github.com/mbostock/topojson/wiki TopoJSON] format and if saved in Wikipedia are available for this module. Maps in the default directory [[Special: | + | }}{{#ifeq:{{{1|map}}}|map|<!-- Parts to be transcluded from the wrapper Template:Graph:Map --> |
+ | * '''basemap:''' sets the base map. The map definitions must follow the [https://github.com/mbostock/topojson/wiki TopoJSON] format and if saved in Wikipedia are available for this module. Maps in the default directory [[Special:Prefixindex/Template:Graph:Map/Inner/]] like [[Template:Graph:Map/Inner/Worldmap2c-json|Worldmap2c-json]] should only be referenced by their name while omitting the Modul:Graph/ prefix to allow better portability. The parameter also accepts URLs, e.g. maps from other Wikipedia versions (the link should follow the scheme of <code>//en.wikipedia.org/w/index.php?title=''mapname''&action=raw</code>, i.e. protocol-relative without leading http/s and a trailing action=raw to fetch the raw content only). <small>URLs to maps on external sites should be avoided for the sake of link stability, performance, security, and she be assumed to be blocked by the software or browser anyway.</small> | ||
* '''scale:''' the scaling factor of the map (default: 100) | * '''scale:''' the scaling factor of the map (default: 100) | ||
* '''projection:''' the [[:en:map projection|map projection]] to use. Supported values are listed at https://github.com/mbostock/d3/wiki/Geo-Projections. The default value is <code>equirectangular</code> for an [[:en:equirectangular projection|equirectangular projection]]. | * '''projection:''' the [[:en:map projection|map projection]] to use. Supported values are listed at https://github.com/mbostock/d3/wiki/Geo-Projections. The default value is <code>equirectangular</code> for an [[:en:equirectangular projection|equirectangular projection]]. | ||
− | * ids of geographic entities: The actual parameter names depend on the base map. For example, for the above mentioned world map the ids are [[:en:ISO country codes|ISO country codes]]. The values can be either colors or numbers in case the geographic entities should be associated with numeric data: <code>DE=lightblue</code> marks Germany in light blue color, and <code>DE=80.6</code> assigns Germany the value 80.6 (population in millions). In the latter case, the actual color depends on the following parameters. | + | * '''center:''' map center (corresponds in the map data to both comma-separated values of the <code>scale</code> field) |
− | + | * '''feature:''' which geographic objects should be displayed (corresponds in the map data to the name of the field under the <code>objects</code> field). The default is value <code>countries</code>. | |
− | + | * '''ids of geographic entities''': The actual parameter names depend on the base map and the selected feature. For example, for the above mentioned world map the ids are [[:en:ISO country codes|ISO country codes]]. The values can be either colors or numbers in case the geographic entities should be associated with numeric data: <code>DE=lightblue</code> marks Germany in light blue color, and <code>DE=80.6</code> assigns Germany the value 80.6 (population in millions). In the latter case, the actual color depends on the following parameters. | |
− | + | * '''colorScale:''' the color palette to use for the color scale. The palette must be provided as a comma-separated list of color values. The color values must be given either as <code>#rgb</code>/<code>#rrggbb</code> or by a [[:en:Web colors#X11 colour names|CSS color name]]. Instead of a list, the built-in color palettes [https://github.com/mbostock/d3/wiki/Ordinal-Scales#categorical-colors <code>category10</code> and <code>category20</code>] can also be used. | |
− | + | * '''scaleType:''' supported values are <code>linear</code> for a linear mapping between the data values and the color scale, <code>log</code> for a log mapping, <code>pow</code> for a power mapping (the exponent can be provided as <code>pow 0.5</code>), <code>sqrt</code> for a square-root mapping, and <code>quantize</code> for a quantized scale, i.e. the data is grouped in as many classes as the color palette has colors. | |
− | + | * '''domainMin:''' lower boundary of the data values, i.e. smaller data values are mapped to the lower boundary | |
+ | * '''domainMax:''' upper boundary of the data values, i.e. larger data values are mapped to the upper boundary | ||
+ | * '''legend:''' show color legend (does not work with <code>quantize</code>) | ||
* '''defaultValue:''' default value for unused geographic entities. In case the id values are colors the default value is <code>silver</code>, in case of numbers it is 0. | * '''defaultValue:''' default value for unused geographic entities. In case the id values are colors the default value is <code>silver</code>, in case of numbers it is 0. | ||
+ | }}{{#if:{{{1|}}}|| | ||
* '''formatjson:''' format JSON object for better legibility | * '''formatjson:''' format JSON object for better legibility | ||
+ | |||
=== <code>chart</code> === | === <code>chart</code> === | ||
− | Creates a JSON object for <code><nowiki><graph></nowiki></code> to display charts. In the article namespace the template | + | Creates a JSON object for <code><nowiki><graph></nowiki></code> to display charts. In the article namespace the template [[Template:Graph:Chart]] should be used instead. See its page for use cases. |
'''Parameters:''' | '''Parameters:''' | ||
− | * '''width | + | }}{{#ifeq:{{{1|chart}}}|chart|<!-- Parts to be transcluded from the wrapper Template:Graph:Chart --> |
− | * '''height | + | * '''width''': width of the chart |
− | * '''type | + | * '''height''': height of the chart |
− | * '''interpolate | + | * '''type''': type of the chart: <code>line</code> for [[:en:line chart|line chart]]s, <code>area</code> for [[:en:area chart|area chart]]s, and <code>rect</code> for (column) [[:en:bar chart|bar chart]]s, and <code>pie</code> for [[:en:pie chart|pie chart]]s. Multiple series can stacked using the <code>stacked</code> prefix, e.g. <code>stackedarea</code>. |
− | * '''colors | + | * '''interpolate''': [[:en:interpolation|interpolation]] method for line and area charts. It is recommended to use <code>monotone</code> for a [[:en:monotone cubic interpolation|monotone cubic interpolation]] – further supported values are listed at https://github.com/vega/vega/wiki/Marks#area. |
− | * '''xAxisTitle''' and '''yAxisTitle | + | * '''colors''': color palette of the chart as a comma-separated list of colors. The color values must be given either as <code>#rgb</code>/<code>#rrggbb</code>/<code>#aarrggbb</code> or by a [[:en:Web colors#X11 colour names|CSS color name]]. For <code>#aarrggbb</code> the <code>aa</code> component denotes the [[:en:alpha channel|alpha channel]], i.e. FF=100% opacity, 80=50% opacity/transparency, etc. (The default color palette if n <= 10 is Category10: {{ChartColors|Categ20|10}} else is Category20: {{ChartColors|Categ20|20}}). |
− | * '''xAxisMin, xAxisMax, yAxisMin | + | * '''xAxisTitle''' and '''yAxisTitle''': captions of the x and y axes |
− | * '''xAxisFormat''' and '''yAxisFormat | + | * '''xAxisMin''', '''xAxisMax''', '''yAxisMin''', and '''yAxisMax''': minimum and maximum values of the x and y axes (not yet supported for bar charts). These parameters can be used to invert the scale of a numeric axis by setting the lowest value to the Max and highest value to the Min. |
− | * '''xAxisAngle | + | * '''xAxisFormat''' and '''yAxisFormat''': changes the formatting of the axis labels. Supported values are listed at https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#numbers for numbers and https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md for date/time. For example, the format <code>%</code> can be used to output percentages. |
− | * '''xType''' and '''yType | + | * '''xAxisAngle''': rotates the x axis labels by the specified angle. Recommended values are: -45, +45, -90, +90 |
− | * ''' | + | * '''xType''' and '''yType''': data types of the values, e.g. <code>integer</code> for integers, <code>number</code> for real numbers, <code>date</code> for dates (e.g. YYYY/MM/DD), and <code>string</code> for ordinal values (use <code>string</code> to prevent axis values from being repeated when there are only a few values). |
− | * '''y''' or '''y1, y2 | + | * '''xScaleType''' and '''yScaleType''': scale types of the x and y axes, e.g. <code>linear</code> for linear scale (default), <code>log</code> for logarithmic scale and <code>sqrt</code> for square root scale. |
− | * '''legend | + | * '''x''': the x-values as a comma-separated list |
− | * '''y1Title, y2Title | + | * '''y''' or '''y1''', '''y2''', …: the y-values for one or several data series, respectively. For pie charts <code>y2</code> denotes the radiuses of the corresponding sectors. |
− | * '''linewidth | + | * '''legend''': show legend (only works in case of multiple data series) |
− | * '''showValues | + | * '''y1Title''', '''y2Title''', …: defines the label of the respective data series in the legend |
− | ** '''format | + | * '''linewidth''': line width for line charts or distance between the pie segments for pie charts. Setting to 0 with <code>type=line</code> creates a scatter plot. |
− | ** '''fontcolor | + | * '''linewidths''': different line widths may be defined for each series of data with csv, if set to 0 with "showSymbols" results with points graph, eg.: <code>linewidths=1, 0, 5, 0.2</code> |
− | ** '''fontsize | + | * '''showSymbols''': show symbol on data point for line graphs, if number is provided it's size of symbol, default 2.5. may be defined for each series of data with csv, eg.: <code>showSymbols=1, 2, 3, 4</code> |
− | ** '''offset | + | * '''symbolsShape''': custom shape for symbol: circle, x, square, cross, diamond, triangle_up, triangle_down, triangle_right, triangle_left. May be defined for each series of data with csv, eg.: <code>symbolsShape= circle, cross, square</code> |
+ | * '''symbolsNoFill''': if true symbol will be without fill (only stroke), | ||
+ | * '''symbolsStroke''': if "x" symbol is used or option "symbolsNoFill" symbol stroke width, default 2.5 | ||
+ | * '''showValues''': Additionally, output the y values as text. (Currently, only (non-stacked) bar and pie charts are supported.) The output can be configured used the following parameters provided as <code>name1:value1, name2:value2</code>: | ||
+ | ** '''format''': Format the output according to https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#numbers for numbers and https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md for date/time. | ||
+ | ** '''fontcolor''': text color | ||
+ | ** '''fontsize''': text size | ||
+ | ** '''offset''': move text by the given offset. For bar charts and pie charts with <code>midangle</code> this also defines if the text is inside or outside the chart. | ||
** '''angle''' (pie charts only): text angle in degrees or <code>midangle</code> (default) for dynamic angles based on the mid-angle of the pie sector. | ** '''angle''' (pie charts only): text angle in degrees or <code>midangle</code> (default) for dynamic angles based on the mid-angle of the pie sector. | ||
− | * '''innerRadius | + | * '''innerRadius''': For pie charts: defines the inner radius to create a ''doughnut chart''. |
− | * '''formatjson | + | * '''xGrid''' and '''yGrid''': display grid lines on the x and y axes. |
+ | }}{{#if:{{{1|}}}|| | ||
+ | * '''formatjson''': format JSON object for better legibility | ||
=== Template wrappers === | === Template wrappers === | ||
The functions <code>mapWrapper</code> and <code>chartWrapper</code> are wrappers to pass all parameters of the calling template to the respective <code>map</code> and <code>chart</code> functions. | The functions <code>mapWrapper</code> and <code>chartWrapper</code> are wrappers to pass all parameters of the calling template to the respective <code>map</code> and <code>chart</code> functions. | ||
+ | }} | ||
− | '''Note:''' In the editor preview the graph extension creates a [[ | + | '''Note:''' In the editor preview the graph extension creates a [[canvas element]] with vector graphics. However, when saving the page a [[Portable Network Graphics|PNG]] raster graphics is generated instead. |
+ | {{#if:{{{1|}}}||<!-- Parts not to be transcluded from the wrapper templates --> | ||
+ | <nowiki>{{</nowiki>#invoke:{{BASEPAGENAME}}{{!}}''function_wrapper_name''<nowiki>}}</nowiki> | ||
+ | }} | ||
− | + | {{#ifeq:{{{nocat}}}|yes|| | |
+ | <includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | | | ||
+ | <!-- Categories below this line, please; interwikis at Wikidata --> | ||
+ | [[Category:Graph, chart and plot templates]] | ||
+ | }}</includeonly> | ||
+ | }} |
Revision as of 02:15, 8 August 2020
This module is rated as alpha. It is ready for third-party input, and may be used on a few pages to see if problems arise, but should be watched. Suggestions for new features or changes in their input and output mechanisms are welcome. |
Related pages |
---|
Module with helper functions for the Graph extension to display graphs and maps. From de:Modul:Graph.
Functions for templates
map
Creates a JSON object for <graph>
to display a political map with colored highlights. In the article namespace the template Template:Template should be used instead. See its page for use cases.
Maps can be found at Special:Prefixindex/Template:Graph:Map/Inner/ (for example Worldmap2c-json with country borders) and new maps should also be saved under Module:Graph/.
Parameters:
- basemap: sets the base map. The map definitions must follow the TopoJSON format and if saved in Wikipedia are available for this module. Maps in the default directory Special:Prefixindex/Template:Graph:Map/Inner/ like Worldmap2c-json should only be referenced by their name while omitting the Modul:Graph/ prefix to allow better portability. The parameter also accepts URLs, e.g. maps from other Wikipedia versions (the link should follow the scheme of
//en.wikipedia.org/w/index.php?title=mapname&action=raw
, i.e. protocol-relative without leading http/s and a trailing action=raw to fetch the raw content only). URLs to maps on external sites should be avoided for the sake of link stability, performance, security, and she be assumed to be blocked by the software or browser anyway. - scale: the scaling factor of the map (default: 100)
- projection: the map projection to use. Supported values are listed at https://github.com/mbostock/d3/wiki/Geo-Projections. The default value is
equirectangular
for an equirectangular projection. - center: map center (corresponds in the map data to both comma-separated values of the
scale
field) - feature: which geographic objects should be displayed (corresponds in the map data to the name of the field under the
objects
field). The default is valuecountries
. - ids of geographic entities: The actual parameter names depend on the base map and the selected feature. For example, for the above mentioned world map the ids are ISO country codes. The values can be either colors or numbers in case the geographic entities should be associated with numeric data:
DE=lightblue
marks Germany in light blue color, andDE=80.6
assigns Germany the value 80.6 (population in millions). In the latter case, the actual color depends on the following parameters. - colorScale: the color palette to use for the color scale. The palette must be provided as a comma-separated list of color values. The color values must be given either as
#rgb
/#rrggbb
or by a CSS color name. Instead of a list, the built-in color palettescategory10
andcategory20
can also be used. - scaleType: supported values are
linear
for a linear mapping between the data values and the color scale,log
for a log mapping,pow
for a power mapping (the exponent can be provided aspow 0.5
),sqrt
for a square-root mapping, andquantize
for a quantized scale, i.e. the data is grouped in as many classes as the color palette has colors. - domainMin: lower boundary of the data values, i.e. smaller data values are mapped to the lower boundary
- domainMax: upper boundary of the data values, i.e. larger data values are mapped to the upper boundary
- legend: show color legend (does not work with
quantize
) - defaultValue: default value for unused geographic entities. In case the id values are colors the default value is
silver
, in case of numbers it is 0. - formatjson: format JSON object for better legibility
chart
Creates a JSON object for <graph>
to display charts. In the article namespace the template Template:Graph:Chart should be used instead. See its page for use cases.
Parameters:
- width: width of the chart
- height: height of the chart
- type: type of the chart:
line
for line charts,area
for area charts, andrect
for (column) bar charts, andpie
for pie charts. Multiple series can stacked using thestacked
prefix, e.g.stackedarea
. - interpolate: interpolation method for line and area charts. It is recommended to use
monotone
for a monotone cubic interpolation – further supported values are listed at https://github.com/vega/vega/wiki/Marks#area. - colors: color palette of the chart as a comma-separated list of colors. The color values must be given either as
#rgb
/#rrggbb
/#aarrggbb
or by a CSS color name. For#aarrggbb
theaa
component denotes the alpha channel, i.e. FF=100% opacity, 80=50% opacity/transparency, etc. (The default color palette if n <= 10 is Category10: else is Category20: ). - xAxisTitle and yAxisTitle: captions of the x and y axes
- xAxisMin, xAxisMax, yAxisMin, and yAxisMax: minimum and maximum values of the x and y axes (not yet supported for bar charts). These parameters can be used to invert the scale of a numeric axis by setting the lowest value to the Max and highest value to the Min.
- xAxisFormat and yAxisFormat: changes the formatting of the axis labels. Supported values are listed at https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#numbers for numbers and https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md for date/time. For example, the format
%
can be used to output percentages. - xAxisAngle: rotates the x axis labels by the specified angle. Recommended values are: -45, +45, -90, +90
- xType and yType: data types of the values, e.g.
integer
for integers,number
for real numbers,date
for dates (e.g. YYYY/MM/DD), andstring
for ordinal values (usestring
to prevent axis values from being repeated when there are only a few values). - xScaleType and yScaleType: scale types of the x and y axes, e.g.
linear
for linear scale (default),log
for logarithmic scale andsqrt
for square root scale. - x: the x-values as a comma-separated list
- y or y1, y2, …: the y-values for one or several data series, respectively. For pie charts
y2
denotes the radiuses of the corresponding sectors. - legend: show legend (only works in case of multiple data series)
- y1Title, y2Title, …: defines the label of the respective data series in the legend
- linewidth: line width for line charts or distance between the pie segments for pie charts. Setting to 0 with
type=line
creates a scatter plot. - linewidths: different line widths may be defined for each series of data with csv, if set to 0 with "showSymbols" results with points graph, eg.:
linewidths=1, 0, 5, 0.2
- showSymbols: show symbol on data point for line graphs, if number is provided it's size of symbol, default 2.5. may be defined for each series of data with csv, eg.:
showSymbols=1, 2, 3, 4
- symbolsShape: custom shape for symbol: circle, x, square, cross, diamond, triangle_up, triangle_down, triangle_right, triangle_left. May be defined for each series of data with csv, eg.:
symbolsShape= circle, cross, square
- symbolsNoFill: if true symbol will be without fill (only stroke),
- symbolsStroke: if "x" symbol is used or option "symbolsNoFill" symbol stroke width, default 2.5
- showValues: Additionally, output the y values as text. (Currently, only (non-stacked) bar and pie charts are supported.) The output can be configured used the following parameters provided as
name1:value1, name2:value2
:- format: Format the output according to https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#numbers for numbers and https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md for date/time.
- fontcolor: text color
- fontsize: text size
- offset: move text by the given offset. For bar charts and pie charts with
midangle
this also defines if the text is inside or outside the chart. - angle (pie charts only): text angle in degrees or
midangle
(default) for dynamic angles based on the mid-angle of the pie sector.
- innerRadius: For pie charts: defines the inner radius to create a doughnut chart.
- xGrid and yGrid: display grid lines on the x and y axes.
- formatjson: format JSON object for better legibility
Template wrappers
The functions mapWrapper
and chartWrapper
are wrappers to pass all parameters of the calling template to the respective map
and chart
functions.
Note: In the editor preview the graph extension creates a canvas element with vector graphics. However, when saving the page a PNG raster graphics is generated instead. {{#invoke:Graph|function_wrapper_name}}