Module:Graph/doc: Difference between revisions

Revision as of 18:56, 27 April 2017

Revision as of 19:35, 5 August 2017

Line 5:

== Functions for templates ==

=== <ttcode>map</ttcode> ===

Creates a JSON object for <ttcode><nowiki><graph></nowiki></ttcode> 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:Prefixindex/Module:Graph/]] (for example [[Module:Graph/WorldMap-iso2.json|WorldMap-iso2.json]] with country borders) and new maps should also be saved under Module:Graph/.

Line 12:

'''Parameters:'''

}}{{#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/Module:Graph/]] such as [[Module:Graph/WorldMap-iso2.json|WorldMap-iso2.json]] 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 <ttcode>//en.wikipedia.org/w/index.php?title=''mapname''&action=raw</ttcode>, 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)

* '''projection''': the [[map projection]] to use. Supported values are listed at https://github.com/mbostock/d3/wiki/Geo-Projections. The default value is <ttcode>equirectangular</ttcode> 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: <ttcode>DE=lightblue</ttcode> marks Germany in light blue color, and <ttcode>DE=80.6</ttcode> 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 <ttcode>#rgb</ttcode>/<ttcode>#rrggbb</ttcode> or by a [[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 <ttcode>category10</ttcode> and <ttcode>category20</ttcode>] can also be used.

** '''scaleType''': supported values are <ttcode>linear</ttcode> for a linear mapping between the data values and the color scale, <ttcode>log</ttcode> for a log mapping, <ttcode>pow</ttcode> for a power mapping (the exponent can be provided as <ttcode>pow 0.5</ttcode>), <ttcode>sqrt</ttcode> for a square-root mapping, and <ttcode>quantize</ttcode> 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 <ttcode>quantize</ttcode>)

* '''defaultValue''': default value for unused geographic entities. In case the id values are colors the default value is <ttcode>silver</ttcode>, in case of numbers it is 0.

}}{{#if:{{{1|}}}||

* '''formatjson''': format JSON object for better legibility

=== <ttcode>chart</ttcode> ===

Creates a JSON object for <ttcode><nowiki><graph></nowiki></ttcode> to display charts. In the article namespace the template [[Template:Graph:Chart]] should be used instead. See its page for use cases.

'''Parameters:'''

Line 31:

* '''width''': width of the chart

* '''height''': height of the chart

* '''type''': type of the chart: <ttcode>line</ttcode> for [[:en:line chart|line chart]]s, <ttcode>area</ttcode> for [[:en:area chart|area chart]]s, and <ttcode>rect</ttcode> for (column) [[:en:bar chart|bar chart]]s, and <ttcode>pie</ttcode> for [[:en:pie chart|pie chart]]s. Multiple series can stacked using the <ttcode>stacked</ttcode> prefix, e.g. <ttcode>stackedarea</ttcode>.

* '''interpolate''': [[:en:interpolation|interpolation]] method for line and area charts. It is recommended to use <ttcode>monotone</ttcode> for a [[:en:monotone cubic interpolation|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 <ttcode>#rgb</ttcode>/<ttcode>#rrggbb</ttcode>/<ttcode>#aarrggbb</ttcode> or by a [[:en:Web colors#X11 colour names|CSS color name]]. For <ttcode>#aarrggbb</ttcode> the <ttcode>aa</ttcode> component denotes the [[:en:alpha channel|alpha channel]], i.e. FF=100% opacity, 80=50% opacity/transparency, etc. (The default color palette is [http://github.com/d3/d3-scale/blob/master/README.md#schemeCategory10 <ttcode>category10</ttcode>]).

* '''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)

* '''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 <ttcode>%</ttcode> can be used to output percentages.

* '''xType''' and '''yType''': Data types of the values, e.g. <ttcode>integer</ttcode> for integers, <ttcode>number</ttcode> for real numbers, <ttcode>date</ttcode> for dates (e.g. YYYY/MM/DD), and <ttcode>string</ttcode> for ordinal values.

* '''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 <ttcode>y2</ttcode> 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

* '''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 <ttcode>name1:value1, name2:value2</ttcode>:

** '''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 <ttcode>midangle</ttcode> this also defines if the text is inside or outside the chart.

** '''angle''' (pie charts only): text angle in degrees or <ttcode>midangle</ttcode> (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''.

}}{{#if:{{{1|}}}||

Line 54:

=== Template wrappers ===

The functions <ttcode>mapWrapper</ttcode> and <ttcode>chartWrapper</ttcode> are wrappers to pass all parameters of the calling template to the respective <ttcode>map</ttcode> and <ttcode>chart</ttcode> functions.

}}