Difference between revisions of "Module:Graph/doc"

From RimWorld Wiki
Jump to navigation Jump to search
(Documentation)
 
m (linkfix)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Module with helper functions for the [[Extension:Graph|Graph]] extension.
+
Module with helper functions for the [https://www.mediawiki.org/wiki/Extension:Graph Graph] extension.
  
 
== Functions for templates ==
 
== Functions for templates ==
Line 10: Line 10:
 
* '''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/Module:Graph/]] should only be referenced by their name while omitting the Module: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 should be assumed to be blocked by the software or browser anyway.</small>
 
* '''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/Module:Graph/]] should only be referenced by their name while omitting the Module: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 should 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 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 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.
+
* ids of geographic entities: The actual parameter names depend on the base map. 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: <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.
+
** '''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 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.
 
** '''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
 
** '''domainMin:''' lower boundary of the data values, i.e. smaller data values are mapped to the lower boundary
Line 25: Line 25:
 
* '''width:''' width of the chart
 
* '''width:''' width of the chart
 
* '''height:''' height of the chart
 
* '''height:''' height of the chart
* '''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>.
+
* '''type:''' type of the chart: <code>line</code> for line charts, <code>area</code> for area charts, and <code>rect</code> for (column) bar charts, and <code>pie</code> for pie charts. Multiple series can stacked using the <code>stacked</code> prefix, e.g. <code>stackedarea</code>.
* '''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.
+
* '''interpolate:''' interpolation method for line and area charts. It is recommended to use <code>monotone</code> 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 <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 is [//github.com/mbostock/d3/wiki/Ordinal-Scales#categorical-colors <code>category10</code>]).
+
* '''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 CSS color name. For <code>#aarrggbb</code> the <code>aa</code> component denotes the alpha channel, i.e. FF=100% opacity, 80=50% opacity/transparency, etc. (The default color palette is [//github.com/mbostock/d3/wiki/Ordinal-Scales#categorical-colors <code>category10</code>]).
 
* '''xAxisTitle''' and '''yAxisTitle:''' captions of the x and y axes
 
* '''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
 
* '''xAxisMin, xAxisMax, yAxisMin,''' and '''yAxisMax:''' minimum and maximum values of the x and y axes
Line 37: Line 37:
 
* '''legend:''' show legend (only works in case of multiple data series)
 
* '''legend:''' show legend (only works in case of multiple data series)
 
* '''y1Title, y2Title,''' …: defines the label of the respective data series in the legend
 
* '''y1Title, y2Title,''' …: defines the label of the respective data series in the legend
 +
* '''xGrid''' and '''yGrid:''' Adds vertical and horizontal lines respectively at the displayed values of the axes for ease of referencing when added as a blank argument i.e <code>|xGrid = |</code>. Unknown function if set to something.
 
* '''linewidth:''' line width for line charts or distance between the pie segments for pie charts
 
* '''linewidth:''' line width for line charts or distance between the pie segments for pie charts
 
* '''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>:
 
* '''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>:
Line 50: Line 51:
 
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 [[:en:canvas element|canvas element]] with vector graphics. However, when saving the page a [[:en:Portable Network Graphics|PNG]] raster graphics is generated instead.
+
'''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.
  
 
'''Note to developers:''' New functionality can be tested with the [https://vega.github.io/vega-editor/index.html?mode=vega Vega Editor], that also contains a large amount of example code.
 
'''Note to developers:''' New functionality can be tested with the [https://vega.github.io/vega-editor/index.html?mode=vega Vega Editor], that also contains a large amount of example code.
 +
 +
<includeonly>[[Category:Module]]</includeonly>
 +
<noinclude>[[Category:Module documentation]]</noinclude>

Latest revision as of 10:04, 23 October 2022

Module with helper functions for the Graph extension.

Functions for templates[edit]

map[edit]

Creates a JSON object for <graph> to display a political map with colored highlights.

Maps can be found at Special:PrefixIndex/Module:Graph/ and new maps should also be saved under Modul: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/Module:Graph/ should only be referenced by their name while omitting the Module: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 should 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.
  • ids of geographic entities: The actual parameter names depend on the base map. 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, and DE=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 palettes category10 and category20 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 as pow 0.5), sqrt for a square-root mapping, and quantize 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[edit]

Creates a JSON object for <graph> to display charts. In the article namespace the 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, and rect for (column) bar charts, and pie for pie charts. Multiple series can stacked using the stacked 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 the aa component denotes the alpha channel, i.e. FF=100% opacity, 80=50% opacity/transparency, etc. (The default color palette is category10).
  • 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
  • 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), and string for ordinal values.
  • x: the x-values as a comma-separated list (if a value itself contains a comma it must be escaped with a backslash, i.e. it needs to be written as \,)
  • 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
  • xGrid and yGrid: Adds vertical and horizontal lines respectively at the displayed values of the axes for ease of referencing when added as a blank argument i.e |xGrid = |. Unknown function if set to something.
  • linewidth: line width for line charts or distance between the pie segments for pie charts
  • 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:
  • innerRadius: For pie charts: defines the inner radius to create a doughnut chart.
  • formatjson: format JSON object for better legibility

Template wrappers[edit]

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.

Note to developers: New functionality can be tested with the Vega Editor, that also contains a large amount of example code.