Extension:WikiPlot

WikiPlot is a plotting extension for MediaWiki, written completely in php. That will enable users to plot graphs from a mathematical expression, like x^2+4.

WikiPlot Administrators Guide
A System Administrators Guidelines The WikiPlot Development Team.

Authors: Jonas F. Jensen, Ismail Faizi

This guide is intended for system administrators. It will help you install WikiPlot, and maintain your installation updated, with as little effort as possible. If you are maintainer/administrator of a MediaWiki installation, this is your guide for WikiPlot.

Source of this documentation: http://wikiplot.googlecode.com/svn/trunk/docs/index.html

Installation
WikiPlot can be installed as any other MediaWiki extension, first you obtain a copy of WikiPlot, we recommend that you download the latest stable from our homepage. You can also checkout a(n) (un)stable from SVN, but if you do that you must also rename some directories and stuff, which is not covered here.

svn checkout http://wikiplot.googlecode.com/svn/trunk/ wikiplot

Once you have obtained a stable copy of WikiPlot, extract it and place the WikiPlot directory in the extensions directory of your MediaWiki installation. Now you will have to activate your extension in the LocalSettings.php file of your MediaWiki installation. This is done by adding following line:

//Enable the WikiPlot extension require_once("$IP/extensions/WikiPlot/WikiPlot.php");

Now you have installed the WikiPlot extension, but you are NOT all done yet. WikiPlot requires access to a cache, before it can work. Configuration of WikiPlot and its cache is covered next.

WikiPlotSettings.php:Settings/Caching
Once you have installed WikiPlot, you must configure its cache before you can use WikiPlot. First you must have a place to save cached images, create an empty directory and give php write permissions to the directory (hint: the directory must be accessible from http). Once you have created a directory for the cache, you must tell WikiPlot where this directory is located, you do that by opening WikiPlotSettings.php from extensions/WikiPlot/WikiPlotSettings.php, and redefining the constants defined there. Like this:

define("WikiPlotCachePath","/w/images/temp/");

The path to the cache directory you have just created. This path is relative to DOCUMENT_ROOT, your DOCUMENT_ROOT is usually /public_html/, which means that if your cache directory is in /public_html/catch/ then WikiPlotCachePath should be /cache/. You can find your DOCUMENT_ROOT in your phpinfo data.

define("WikiPlotCacheURL","http://localhost/w/images/temp/");

The path to the cache directory is the same directory as used in WikiPlotCachePath, but this time your path is relative to http://, which means that if your site is mysite.com and your cache directory is placed in DOCUMENT_ROOT (usually /public_html/) then the URL (WikiPlotCacheURL) to your cache should be http://mysite.com/cache/

More specific configuration of your cache can be done in WikiPlotSettings.php, if you have any questions regarding these settings, take a look at the sourcecode documentation or feel free to contact us. More advanced configuration of the cache is not covered here.

Keep the cache clean If your users uses WikiPlot a lot, and changes the plots a lot, WikiPlot will generate an awful lot of unused images in the cache, at some point this might be considered a waste of server resources. Therefore it is recommended that you cleanup the catch on a regular basis. You can cleanup the cache by running /extensions/WikiPlot/CleanupCache.php, you may run this script as a cron job.

The script removes all images that have not been accessed for a given period. It is also possible to remove all images of a certain age. You can find the settings for this file in WikiPlotSettings.php, advanced configuration of this script is not covered here, see sourcecode documentation for further information.

WikiPlot Userguide
This is a simple guide to learn and become familiar with WikiPlot syntax, if the WikiPlot extension is installed on the wiki you wish to modify, you can add simply just type the WikiPlot syntax in your file. This chapter will not document all the features of WikiPlot but just the basics.

First things first, let's start with a short introduction our terminology. We have one plot and one or more graphs (Note the words I just used). Where plot defines the coordinate space, width, height and axes of the final image. A plot contains one or more graph, which is expressed with a mathematical expression (for instance: x^2+4x+5). If you think this is weird, hold on there, I will clarify in just a moment.

Now let's get dirty, following code will generate an image with 1 graph, from the expression y(x)=x+4.

x+4

Okay that is possibly the shortest we can make it. I would not be surprised if you would consider that a little too basic. So just to match some basic functionality, we are going to add another graph with the expression y(x)=3*x-3, and some optional parameters to modify the output image.

 x+4 3*x-3

Now this is different. This will result in an image with width and height of 200 pixels. It will have a caption saying Simple plot. The image will be a clip of a coordinate space, where minimum X will be -100 and maximum X will be 100, same goes for Y. The image contain 2 labels in the corner, one saying Graph 1 another saying Graph 2, one of them will have the color rgb(255,0,0) which is red. Apart from that there will also be 2 graphs.

To simplify the example, I have divided and explained it here:


 * height:Height of the output image in pixels.
 * width:Width of the output image in pixels.
 * caption:Caption on the output image.
 * xspan and yspan:Values representing minimum x and maximum x, in coordinate space. If you set xspan="-50;75" the lowest x values on your image will be -50 and the highest will be 75. This does not have anything with width to do, and is in no way related to pixels! This feature enables you to zoom in and out on the coordinate space, independent of image size. xspan and yspan are completely similar except for the fact that they change the y or x coordinate space respectively.
 * x+4 and 3*x-3:These are mathematical expressions defining the 2 graphs on the image.
 * label:Labels that are placed in the corner of the image, displayed in the same color as the graphs they represent.
 * color:Color of the graph, in an RGB (Red,Green,Blue) representation.

If you do not understand this, please feel free to contact us, or post your question at http://groups.google.com/group/wikiplot and we will hurry to help. We are well aware that our terminology is very bad, and that some of our syntax might confuse users, so please help us improve.

WikiPlot Syntax Reference
This is a complete syntax reference for WikiPlot, if you are note familiar with xml or the most common MediaWiki syntax, it is recommended that you read the WikiPlot UserGuide first. Below you will find a documentation of the parameters and content for the wikiplot and graph tag, respectively. At the end of the article you will find a complete example of a plot with use of all parameters.

wikiplot parameters and content
The wikiplot tag contains one or more graph tags, the graph tags defines the different mathematical expressions to be plotted. The wikiplot tag defines the image/environment/coordinate-system these mathematical expressions are to be plotted upon. The wikiplot tag takes following parameters:


 * caption:Defines the caption of the plot, is shown i the top centered on the final image. Leave empty or do not define this parameter, you do not want any caption on your image.
 * captionfont:An integer representing font type of the caption, fonts 1-5 are built-in and represents different font sizes 1 being smallest and 5 biggest, defaults to 5.
 * height:An integer, defining the the height of the final image in pixels.
 * width:An integer, defining the width of the final image in pixels.
 * xspan:Two semicolon separated integers, defining the span of the x-axis. If xspan="-5;10" the minimum value on the x-axis will be -5 and the maximum value on the x-axis will be 10. This parameter is very important, because it defines coordinate space to be viewed.
 * yspan:Two semicolon separated integers, defining the span of the y-axis. If yspan="-5;10" the minimum value on the y-axis will be -5 and the maximum value on the y-axis will be 10. This parameter is very important, because it defines coordinate space to be viewed.
 * axis:Enable or disable axis, whether or not to show axis x=0 and y=0. Defaults to true, valid values are: "true" or "false".
 * grid:Enable or disable grid, whether or not to show grid, that makes it easier to read the plot. Defaults to true, valid values are: "true" or "false".
 * gridspace:Two semicolon separated integers, defining the space between the line of the grid. If this is not defined, WikiPlot will calculate some appropriate values, but these might not always look good. If gridspace="10;20" the distance between the grid-lines on the x-axis will be 10 and the distance between the grid-lines on the y-axis will be 20.
 * gridfont:An integer representing font type of the labels at the grid, fonts 1-5 are built-in and represents different font sizes 1 being smallest and 5 biggest, defaults to 1.
 * gridcolor:Three semicolon separated integers, defining the color of the grid-lines, defaults to gray. This gridcolor="240,240,240" is an RGB (Red,Green,Blue) representation of variant of the color gray.
 * graph parameters and content:The graph tags represents different mathematical expressions, that are to be plotted onto the coordinate-system defined by the surrounding/parent wikiplot tag. The graph tag contains the mathematical expression, it is representing. This mathematical expression may contain the variable x, and following mathematical functions:


 * sin
 * sinh
 * arcsin
 * asin
 * arcsinh
 * asinh
 * cos
 * cosh
 * arccos
 * acos
 * arccosh
 * acosh
 * tan
 * tanh
 * arctan
 * atan
 * arctanh
 * atanh
 * sqrt
 * abs
 * ln
 * log

Apart from these mathematical functions you may also use following constants:


 * e
 * pi
 * And last but not least, you may also use following mathematical operators:

If you have any questions regarding these mathematical expressions feel free to contact us, or take a look at the source found in evalmath.class.php. We have not documented this class because we have not written it. The graph tag also takes certain parameters that allow you to affect the way it is represented on the plot. The graph tag takes following parameters:


 * label: A label shown in the top left corner to identify the graph, this label will be printed in same color as the mathematical expression will be plotted. Leave empty or do not define this parameter, if you do not want any label for your mathematical expression.
 * color:Three semicolon separated integers, defining the color of the label and plotted mathematical expression, defaults to black. This color="0,0,0" is an RGB (Red,Green,Blue) representation of the color black.

Complete Example
Following is an advanced example of how WikiPlot could be used. Normally you don't need to used all parameters, most basic ones are covered in depth in the WikiPlot Userguide. This is a pretty extreme example of how to use all parameters:

 x^2+4 3*x-3

Stay updated
Once you have installed WikiPlot, you might want to make sure that your installation is kept updated, both for security and performance reasons. And perhaps there will come some new features as well. To stay updated on the WikiPlot releases subscribe to our announcement list, members of this list will only be contacted regarding new releases, and in case of serious security issues. Subscribe and stay updated.

Support/Help
If you have any questions or problems with WikiPlot, feel free to contact us, you can use our development mailinglist. It is not just a list for WikiPlot development, but a list for everything regarding WikiPlot, help, bug, questions and what ever.

Take a look at the project page, for code, documentation and support:
 * WikiPlot project page at code.google.com