PHPlot

Intentemos crear una sencilla gr�fica de l�neas y puntos.

Primero debemos incluir la librer�a a nuestro script (suponemos que su c�digo se encuentra en el mismo directorio que el c�digo del script del Listado 1):

include_once("phplot.php");

Luego creamos el array y lo llenamos con datos:

$data=array(array(..));

El siguiente paso ser� la creaci�n de una instancia de la clase PHPlot:

$graph = new PHPlot;

seguidamente, la transferencia de datos (la transferencia del array $data, preparado anteriormente, como par�metro):

$graph->SetDataValues($data);

Para terminar, utilizamos el m�todo que permite mostrar la gr�fica por pantalla:

$graph->DrawGraph();

Si alguien cree que esta es una soluci�n m�gica, deber�a leer el script completo que se despliega en el Listado 1 y el resultado de su funcionamiento que se presenta en la Figura 1.

<?php
   include_once("phplot.php");
   $data=
      array(
         array("label1",2.4,3,
               3.7,4,5.1),
         array("label2",3,4,5,
               6,7),
         array("label3",1.1,2.2,
               3.3,4.4,5.5),
         array("label4",1.7,2,3,
               1.4,2),
     );
   $graph = new PHPlot;
   $graph->SetDataValues($data);
   $graph->DrawGraph();
?>

Despu�s de analizar el c�digo y la gr�fica obtenida de su ejecuci�n, podemos sacar varias conclusiones interesantes. Primero, es f�cil notarlo; PHPlot es una librer�a orientada a objetos. As�, empieza a �existir�, despu�s de crear las instancias de la clase PHPlot, y todos los atributos de la gr�fica son establecidos gracias a la llamada de diferentes m�todos de esta clase. Esta metodolog�a garantiza la sencillez en la creaci�n de gr�ficas, ya que es suficiente conocer varios m�todos b�sicos para poder crear y personalizar libremente cualquier gr�fica. Segundo; a los campos de la clase se les asignan valores por defecto, lo que no obliga al programador a tener que recordar diferentes m�todos gr�ficos. Aquel que no quiere o no tiene tiempo para personalizar la gr�fica, puede aceptar su apariencia por defecto, la cual � como se puede apreciar en la Figura 1 � no es peor que las gr�ficas profesionales que se han realizado en hojas de c�lculos comerciales. Adem�s, de acuerdo con lo que fue descrito anteriormente, el m�todo DrawGraph() realiza dos funciones, dado que coloca la gr�fica en el dibujo y despliega ese dibujo en la ventana del navegador.Ya sabemos que esta forma de funcionamiento del m�todo antes mencionado s�lo es posible si en el dibujo colocamos una sola gr�fica. Como veremos despu�s, para desplegar dibujos que contengan varias gr�ficas, deberemos utilizar el m�todo PrintImage().

En la versi�n por defecto de la gr�fica, la escala del eje de las ordenadas se selecciona de acuerdo a los valores de los datos. Las coordenadas de los puntos se calculan con respecto al inicio del sistema de las coordenadas cartesianas, lo que parece ser natural, pero teniendo en cuenta que internamente utiliza la librer�a GD, no es tan obvio. Las funciones de esta librer�a utilizan coordenadas de la pantalla (p�xeles), calculados a partir de la esquina izquierda superior de la pantalla. Las funciones internas de la librer�a PHPlot recalculan las coordenadas transferidas en el array de datos a coordenadas de la pantalla requeridas por la librer�a GD. El tipo de datos transferidos por defecto en la tabla es de tipo texto-dato (los puntos de datos se colocan conservando la misma distancia entre ellos sobre el eje X). A�ad�mos la siguiente l�nea al c�digo del Listado 1:

$graph->SetDataType("data-data");

y veamos como ser�a ahora nuestra gr�fica. Esta se presenta en la Figura 2.

Como podemos apreciar, el aspecto de la gr�fica cambia diametralmente. El m�todo SetDataType() se puede utilizar en cualquier lugar del c�digo, entre el rengl�n en el que se crea el objeto de la clase PHPlot, y la l�nea que contiene el acceso al m�todo DrawGraph().

Los usos avanzados de la librer�a PHPlot consistir�n en la adaptaci�n del aspecto de la gr�fica a nuestras necesidades. Como veremos a continuaci�n, el programador tiene grandes posibilidades.

Adaptaci�n de la gr�fica a los requerimientos propios.

El ejemplo estar� compuesto de dos scripts. La responsabilidad del primero de ellos consistir� en proporcionar un formulario, y el segundo ser� responsable de interpretar los datos recibidos de este formulario y de desplegar la gr�fica. Supongamos que la gr�fica que queremos crear debe presentar los ingresos y gastos reales, y planeados de un negocio; ingresos/gastos en el rango de los a�os 1999-2003. Los datos para la gr�fica ser� introducidos con la ayuda del formulario, que tambi�n nos servir� para definir los par�metros de la gr�fica (su aspecto, tipo, etc.). El aspecto de este formulario se presenta en la Figura 3. Aqu� no presentaremos su c�digo, ya que no proporciona nada nuevo. Esto es simplemente un formulario amplia en HTML. Es f�cil notar que la cantidad de opciones que permiten las modificaciones de la gr�fica es notable. A�n m�s, la forma permite la manipulaci�n de s�lamente un subconjunto de todas las posibilidades. En realidad la librer�a PHPlot ofrece varias decenas de m�todos, con la ayuda de los cuales se pueden personalizar las gr�ficas creadas. Gracias a estos m�todos, el usuario puede influir en casi cualquier elemento de la gr�fica, modific�ndolo de manera similar a como se hace en las hojas de c�lculo profesionales.

Los datos reunidos en el formulario, que se presenta en la Figura 3, se env�an con la ayuda del m�todo POST al script graph.php, donde se utilizan para dibujar la gr�fica y adaptar su aspecto a las necesidades del usuario. El c�digo del script graph.php se presenta en el Listado 2, y algunos de los efectos de sus funcionamiento en las Figuras 4, 5 y 6.

<?php
   include("phplot.php");
   //preparaci�n del array de los datos
   $data=array(array("1999",$_POST['ip1'], $_POST['ir1'], $_POST['ep1'],
                            $_POST['er1']),
               array("2000",$_POST['ip2'], $_POST['ir2'], $_POST['ep2'],
                            $_POST['er2']),
               array("2001",$_POST['ip3'], $_POST['ir3'], $_POST['ep3'],
                            $_POST['er3']),
               array("2002",$_POST['ip4'], $_POST['ir4'], $_POST['ep4'],
                            $_POST['er4']),
               array("2003",$_POST['ip5'], $_POST['ir5'], $_POST['ep5'],
                            $_POST['er5']),
              );
   //creaci�n del objeto de la clase PHPlot,
   //transferencia de datos y definici�n de su tipo
   $graph = new PHPlot($_POST['graph_width'], $_POST['graph_height']);
   $graph->SetDataValues($data);
   $graph->SetDataType("text-data");
   //formateo de la gr�fica
   $graph->SetPlotType($_POST['graph_type']);
   $graph->SetVertTickIncrement($_POST['tick_inc']);
   $graph->SetTickLength($_POST['tick_length']);
   $graph->SetTickColor($_POST['tick_color']);
   $graph->SetPointShape($_POST['point_shape']);
   $graph->SetPointSize($_POST['point_size']);
   $graph->SetTitle($_POST['title_graph']);
   $graph->SetXLabel($_POST['title_X']);
   $graph->SetYLabel($_POST['title_Y']);
   if($_POST['is_legend'])
      $graph->SetLegend(array("Ingresos planeados", "Ingresos reales",
                              "Gastos planeados", "Gastos reales")
                       );
   $graph->SetLegendPixels($_POST['legend_X'],
                           $_POST['legend_Y']);
   $graph->SetLineWidth($_POST['line_width']);
   $graph->SetLineStyles($_POST['line_style']);
   $graph->SetShading($_POST['line_shadow']);
   $graph->SetBackgroundColor($_POST['bg_color']);
   $graph->SetGridColor($_POST['grid_color']);
   $graph->SetDataColors(array($_POST['data_color1'], $_POST['data_color2'],
                               $_POST['data_color3'], $_POST['data_color4'])
                        );
   $graph->SetTextColor($_POST['scale_color']);
   $graph->SetTitleColor($_POST['title_color']);
   $graph->SetLightGridColor($_POST['grid_color']);
   //Visualizaci�n de la gr�fica
   $graph->DrawGraph();
?>

Intentemos analizar un poquito m�s a fondo el c�digo del Listado 2. Despu�s de haber incluido la librer�a PHPlot, creamos el array de datos que se compone de cinco tablas de valores. Cada una de estas tablas representa un a�o, cuyo nombre ser� transferido en el primer elemento. Los elementos restantes son los valores que fueron enviados desde el formulario en el array superglobal $_POST. Estos valores representan cuatro series de datos, que son respectivamente los ingresos y gastos analizados en los a�os consecutivos. Merece la pena notar que la cantidad de series de datos en el modo texto-dato es igual a la cantidad de los elementos en el array de valores menos uno.

La forma de colocaci�n de los datos en los arrays de valores es muy importante, dado que �sta decide sobre el aspecto de la gr�fica. Si en el ejemplo presentado hubieramos invertido el orden de los datos, creando cuatro arrays de valores correspondientes a los ingresos y gastos analizados, donde cada uno de ellos contuviera la etiqueta del par�metro analizado y cinco elementos, representando los valores de ese par�metro en los a�os consecutivos, obtendr�amos una gr�fica, en la cual en el eje de las ordenadas se encontrar�an los valores de los ingresos y gastos ocurridos en estos a�os, y en el eje de las abscisas estar�an colocadas las etiquetas de los par�metros consecutivos. Tal array de datos se presenta en el Listado 3, y la gr�fica que le corresponde est� colocada en la Figura 7. Vemos que una forma diferente de leer los datos, no solamente cambia el aspecto de las gr�fica, sino tambi�n su interpretaci�n.

$data=
   array(
      array("Ingresos reales",$_POST['ip1'], $_POST['ip2'],
             $_POST['ip3'], $_POST['ip4'], $_POST['ip5']),
      array("Ingresos planeados",$_POST['ir1'], $_POST['ir2'],
            $_POST['ir3'], $_POST['ir4'], $_POST['ir5']),
      array("Gastos reales ",$_POST['er1'], $_POST['er2'],
            $_POST['er3'], $_POST['er4'], $_POST['er5']),
      array(" Gastos planeados ",$_POST['ep1'], $_POST['ep2'],
            $_POST['ep3'], $_POST['ep4'], $_POST['ep5'])
        );

Regresemos otra vez al c�digo presentado en el Listado 2. Despu�s de construir el array de datos, creamos el objeto de la clase PHPlot, pero esta vez, al constructor de este objeto le pasaremos un par�metro que defina el �rea de la gr�fica. Si llamaramos a este constructor sin par�metros, se le asignar�an los valores por defecto, por lo que el �rea de la gr�fica ocupar�a un tama�o de 600x400 p�xeles. En este momento, merece la pena enfatizar que a pesar de que en la gr�fica utilizamos coordenadas cartesianas, los diferentes par�metros que deciden sobre el aspecto de la gr�fica (como el tama�o de los puntos de datos, longitud de las etiquetas de los datos, el ancho de las series de datos) los definimos utilizando coordenadas de pantalla, es decir, p�xeles.

Despu�s de definir el �rea de la gr�fica, descargamos el array de datos a PHPlot desde SetDataValues() con el par�metro que representa la tabla antes mencionada. En la siguiente l�nea definimos el tipo de datos (en nuestro caso, es el tipo texto-dato), y despu�s llamamos a toda una serie de m�todos que deciden sobre el aspecto de la gr�fica (v�ase el apartado M�todos utilizados en graph.php, responsables del aspecto de la gr�fica).

Despu�s de los m�todos de maquetaci�n, recurrimos al m�todo DrawGraph() que abre la gr�fica en la ventana del navegador. Debemos subrayar que no es importante el orden en el que utilizamos los m�todos . Lo �nico importante es que primero debemos crear el array de los datos y transferirlo al objeto, despu�s dise�ar la gr�fica y, al final, aplicar DrawGraph().

Como mencionamos anteriormente, las funciones utilizadas en el script graph.php representan una peque�a parte de las muchas posibilidades que ofrece la librer�a PHPlot. Si queremos conocer otros m�todos, deber�amos revisar la documentaci�n de la librer�a.

Tal vez nos preguntamos porqu� los elementos de dise�o de la gr�fica (el color de la l�nea, el estilo de las l�neas, el estilo de los puntos de datos, etc.) no forman parte de los elementos de los arrays de datos. Dado que estas definiciones est�n relacionadas con las series de datos en forma concreta. Resulta ser que una soluci�n as� ser�a poco pr�ctica. Por lo general, los datos presentados en la gr�fica provienen de bases de datos, de p�ginas de negocios, o son introducidos manualmente. Son datos en crudo, sin informaci�n sobre su aspecto. Esto �ltimo se a�ade durante la creaci�n de la gr�fica. Soluciones similares fueron utilizadas en hojas de c�lculos profesionales.

Como mencionamos anteriormente, parte de las definiciones se refieren solamente a ciertos tipos de gr�ficas (por ejemplo, a la funci�n SetShading() que define el ancho de la sombra de las gr�ficas de barras, no se le encontrar� un uso en las gr�ficas de l�neas).

�M�todos utilizados en graph.php responsables del aspecto de la gr�fica

SetPlotType()

define el tipo de la gr�fica en base a su nombre en ingl�s , utilizado en el par�metro. Los nombres permitidos son: bar (de barras), lines (de l�neas), linepoints (de l�neas y puntos), area (de �rea), points (de puntos), pie (de pastel) y squared (escalonado),

SetVertTickIncrement()

define la distancia (expresada en coordenadas cartesianas) entre las etiquetas de datos colocadas a lo largo del eje Y. Por ejemplo, al proporcionarle el valor 3, las etiquetas consecutivas sobre el eje Y tendr�n los valores 0, 3, 6, 9, 12, etc.

SetTickLength()

define la longitud de las etiquetas colocadas sobre los ejes X y Y, expresadas en p�xeles.

SetTickColor()

define el color de las etiquetas de los datos. Al igual que en otros m�todos responsables de la definici�n de colores, podremos utilizar los t�picos nombres ingleses (por ejemplo: red, green, yellow, etc.) o tablas de tres elementos, que correspnden a los tres colores b�sicos RGB, por ejemplo: array(125,176,50),

SetPointShape()

le permite asignar una forma a los puntos de datos. Establecerlo s�lo tiene sentido en el caso de aquellas gr�ficas en las que son visibles los puntos de datos (por ejemplo: gr�ficas de l�neas y puntos). Los posibles valores del par�metro son: rec (rect�ngulo), circle (c�rculo), diamond (rombo), triangle (tri�ngulo), dot (punto), line (segmento) y halfline (semisegmento),

SetPointSize()

define el tama�o de los puntos de datos expresados en p�xeles,

SetTitle()

permite definir el t�tulo de la gr�fica. El t�tulo ser� colocado en la parte superior de la gr�fica,

SetXLabel()

permite definir el t�tulo del eje X,

SetYLabel()

en forma similar al anterior, pero para el eje de las Y,

SetLegend()

define el aspecto de la leyenda. El par�metro de este m�todo es un array cuyos elementos corresponden a las series consecutivas de datos presentados en la gr�fica,

SetLegendPixels()

define la posici�n de la leyenda en la gr�fica. Los par�metros de este m�todo est�n expresados en p�xeles, y definen las coordenadas del extremo izquierdo superior de la leyenda. Se calculan en relaci�n al extremo superior izquierdo de la pantalla,

SetLineWidth()

en el caso de gr�ficas de l�neas, define el ancho de los segmentos que representan la serie de datos,

SetLineStyles()

define el estilo de las l�neas que representan la serie de datos. Igual que el anterior, �ste m�todo tambi�n se refiere a gr�ficas de l�neas. Los par�metros posibles son: dashed (l�nea discontinua) y solid (l�nea continua),

SetShading()

define el grosor de la sombra de las columnas de las gr�ficas de barras,

SetBackgroundColor()

define el color del fondo del �rea, sobre el cual est� colocada la gr�fica,

SetGridColor()

define el color del eje de la gr�fica,

SetDataColors()

define los colores de las series de datos. El par�metro de este m�todo es un array cuyos elementos correponden a las series de datos consecutivas, es decir, los elementos consecutivos de cualquiera de los arrays de valores (a excepci�n del primer elemento de estos arrays). Los par�metros en esta forma los aplicamos siempre que se ejecute el m�todo que formatea las series de datos respectivas,

SetTextColor()

define el color en el que se desplegar�n los valores del eje Y y las etiquetas del eje X,

SetTitleColor()

define el color del t�tulo de la gr�fica y de los nombres de los ejes,

SetLightGridColor()

define el color de la escala de la gr�fica, por ejemplo, las l�neas auxiliares colocadas en las gr�fica. Si no queremos visualizar esas l�neas, debemos proporcionarles el mismo color que tiene el fondo.