macocci7/php-boxplot

it's easy to use for creating boxplots.

1.3.1 2025-01-02 11:45 UTC

Requires

• php: >=8.1
• fakerphp/faker: ^1.24
• macocci7/php-frequency-table: ^1.4
• macocci7/php-plotter2d: ^0.3
• nette/neon: ^3.4

Requires (Dev)

• php-parallel-lint/php-parallel-lint: ^1.4
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5
• squizlabs/php_codesniffer: ^3.11

MIT

• macocci7

README

1. Features

PHP-Boxplot is a PHP Library which is easy to use for creating boxplots.

Outlier Detection can be turned on/off.

Plotting Mean, Plotting Jitter and Plotting Outliers are available.

　

Multiple datasets can be displayed side by side at the same time.

Legends can also be displayed.

Transparent background is also supported.

Contents

• 1. Features
• 2. Contents
• 3. Requirements
• 4. Installation
• 5. Usage
  • 5.1. Basic Usage
  • 5.2. Adjusting the Display By Methods
  • 5.3. Multiple Data Set
  • 5.4. Adjusting the Display By Neon File
  • 5.5. Adjusting the Display By Array
  • 5.6. Transparent Background
• 6. Examples
• 7. LICENSE

3. Requirements

• PHP 8.1 or later

• Imagick PHP Extension

  Check with commands:

  php -i | grep imagick

• Composer

4. Installation

composer require macocci7/php-boxplot

5. Usage

• 5.1. Basic Usage
• 5.2. Adjusting the Display By Methods
• 5.3. Multiple Data Set
• 5.4. Adjusting the Display By Neon File
• 5.5. Adjusting the Display By Array
• 5.6. Transparent Background

5.1. Basic Usage

• PHP: examples/BasicUsage.php

  <?php
  
  require_once __DIR__ . '/../vendor/autoload.php';
  
  use Macocci7\PhpBoxplot\Boxplot;
  
  $data = [
      '1st' => [ 75, 82, 96, 43, 78, 91, 84, 87, 93, ],
      '2nd' => [ 66, 74, 62, 100, 72, 68, 59, 76, 65, ],
      '3rd' => [ 56, 0, 45, 76, 58, 52, 13, 48, 54, 68, ],
      '4th' => [ 68, 32, 56, 92, 67, 72, 45, 76, 48, 73, ],
      '5th' => [ 70, 58, 62, 88, 62, 68, 56, 63, 64, 78, ],
  ];
  
  $bp = new Boxplot();
  
  $bp->setData($data)
     ->create('img/BasicUsage.png');

• Result:

  
  • Outlier Detection is enabled by default.
  • Outliers are plotted as red dods.
  • The Scale Range is 10% larger than the Data Range.
  • Horizontal grid lines are drawn at intervals of 10% of the Scale Range.
  • The hash keys of the data are used as the labels for the X axis.

• Details:

  • Import Autoloader: require_once __DIR__ . '/../vendor/autoload.php'
  • Declare: use Macocci7\PhpBoxplot\Boxplot
  • Instantiate: new Boxplot()
  • Set Data: setData($data)
    • Acceptable Data Type: array<int|string, array<int|float>>
  • Create Image: create($path)

5.2. Adjusting the Display By Methods

Adjusting Scale Size, Grid Pitch, Showing Vertical Grids,

Setting Labels for Each Boxplot, Labels for X Axis, Labels For Y Axis

And Setting Caption can be done as follows:

• PHP:

  <?php
  
  require_once __DIR__ . '/../vendor/autoload.php';
  
  use Macocci7\PhpBoxplot\Boxplot;
  
  $data = [
      '1st' => [ 75, 82, 96, 43, 78, 91, 84, 87, 93, ],
      '2nd' => [ 66, 74, 62, 100, 72, 68, 59, 76, 65, ],
      '3rd' => [ 56, 0, 45, 76, 58, 52, 13, 48, 54, 68, ],
      '4th' => [ 68, 32, 56, 92, 67, 72, 45, 76, 48, 73, ],
      '5th' => [ 70, 58, 62, 88, 62, 68, 56, 63, 64, 78, ],
  ];
  
  $bp = new Boxplot();
  
  $bp->setData($data)
     ->limit(0, 100)
     ->gridHeightPitch(20)
     ->gridVerticalOn()
     ->meanOn()
     ->jitterOn()
     ->legendOn()
     ->labels([ '#1', '#2', '#3', '#4', '#5', ])
     ->labelX('Achievement Test')
     ->labelY('Score')
     ->caption('Achievement Test Results in 2023')
     ->legends(['Donald Biden'])
     ->create('img/AdjustDisplayByMethods.png');

• Result:

  

• Details:

  • Set Limits: limit(int|float $lower, int|float $upper)

  • Set Grid Pitch: gridHeightPitch(int|float $pitch)

  • Set Vertical Grid Visibility:

    • gridVerticalOn()
    • gridVerticalOff()

  • Set Labels: labels(string[] $labels)

  • Set Label for X Axis: labelX(string $labelX)

  • Set Label for Y Axis: labelY(string $labelY)

  • Set Caption: caption(string $caption)

  • Available Methods:

    Note: $colorCode must be in #RGB or #RRGGBB format.

5.3. Multiple Data Set

Multiple datasets can be displayed side by side at the same time.

• PHP: examples/MultipleDataSet.php

  <?php
  
  require_once __DIR__ . '/../vendor/autoload.php';
  
  use Macocci7\PhpBoxplot\Boxplot;
  
  $dataSet = [
      'John' => [
          '1st' => [75, 82, 96, 43, 78, 91, 84, 87, 93, ],
          '2nd' => [66, 74, 62, 100, 72, 68, 59, 76, 65, ],
          '3rd' => [56, 0, 45, 76, 58, 52, 13, 48, 54, 68, ],
          '4th' => [68, 32, 56, 92, 67, 72, 45, 76, 48, 73, ],
          '5th' => [70, 58, 62, 88, 62, 68, 56, 63, 64, 78, ],
      ],
      'Jake' => [
          'test#1' => [62, 35, 48, 43, 56, 78, 32, 24, 29, ],
          'test#2' => [37, 92, 56, 36, 14, 86, 41, 58, 47, ],
          'test#3' => [49, 83, 0, 48, 64, 73, 50, 46, 38, 92, ],
          'test#4' => [53, 44, 34, 51, 74, 68, 53, 86, 24, 66, ],
          'test#5' => [83, 61, 55, 96, 87, 46, 21, 19, 88, 68, ],
      ],
      'Hugo' => [
          'test01' => [73, 36, 0, 11, 40, 76, 24, 46, 83, ],
          'test02' => [69, 42, 76, 8, 92, 84, 45, 34, 67, ],
          'test03' => [100, 46, 34, 77, 85, 47, 91, 85, 66, 79, ],
          'test04' => [0, 14, 32, 24, 54, 44, 56, 32, 59, 38, ],
          'test05' => [69, 84, 65, 42, 33, 80, 74, 54, 75, 56, ],
      ],
  ];
  
  $bp = new Boxplot();
  $bp->setDataset($dataSet)
     ->limit(0, 100)
     ->gridHeightPitch(20)
     ->gridVerticalOn()
     ->legendOn()
     ->meanOn()
     ->labelX('Achievement Test')
     ->labelY('Score')
     ->caption('Achievement Test Results in 2023')
     ->create('img/MultipleDataSet.png');

• Result: examples/img/MultipleDataSet.png

  

• Details:

  • Set Data Set: setDataset(array $dataSet)
    • $dataSet: array<int|string, array<int|string, array<int|float>>>
  • The result of array_keys($dataSet) will be set as the legends.
    • In this case: [ 'John', 'Jake', 'Hugo', ] will be set as the legends.
  • The result of array_keys($dataSet[array_keys($dataSet)[0]]) will be set as the labels.
    • In this case: [ '1st', '2nd', '3rd', '4th', '5th', ] will be set as the legends.
  • legends(array $legends) can overwrite legends.
  • labels(array $labels) can overwrite labels.

5.4. Adjusting the Display By Neon File

You can adjust the display by using Neon file.

First, prepare a Neon file like this:

• Neon: examples/AdjustDisplayByNeon.neon

  # Configuration for BoxplotExample.php
  
  dataSet:
      'John': [
          1st: [75, 82, 96, 43, 78, 91, 84, 87, 93]
          2nd: [66, 74, 62, 100, 72, 68, 59, 76, 65]
          3rd: [56, 0, 45, 76, 58, 52, 13, 48, 54, 68]
          4th: [68, 32, 56, 92, 67, 72, 45, 76, 48, 73]
          5th: [70, 58, 62, 88, 62, 68, 56, 63, 64, 78]
      ]
      'Jake': [
          'test#1': [62, 35, 48, 43, 56, 78, 32, 24, 29]
          'test#2': [37, 92, 56, 36, 14, 86, 41, 58, 47]
          'test#3': [49, 83, 0, 48, 64, 73, 50, 46, 38, 92]
          'test#4': [53, 44, 34, 51, 74, 68, 53, 86, 24, 66]
          'test#5': [83, 61, 55, 96, 87, 46, 21, 19, 88, 68]
      ]
      'Hugo': [
          'test01': [73, 36, 0, 11, 40, 76, 24, 46, 83]
          'test02': [69, 42, 76, 8, 92, 84, 45, 34, 67]
          'test03': [100, 46, 34, 77, 85, 47, 91, 85, 66, 79]
          'test04': [0, 14, 32, 24, 54, 44, 56, 32, 59, 38]
          'test05': [69, 84, 65, 42, 33, 80, 74, 54, 75, 56]
      ]
  
  limitUpper: 100
  limitLower: 0
  
  #canvasWidth: 600
  #canvasHeight: 400
  canvasBackgroundColor: '#333399'
  #frameXRatio: 0.7
  #frameYRatio: 0.6
  
  axisColor: '#999999'
  axisWidth: 2
  
  #gridColor: '#cccccc'
  #gridWidth: 1
  
  gridHeightPitch: 10
  gridVertical: true
  
  #boxWidth: 20
  #boxBackgroundColors:
  #    - '#9999cc'
  #    - '#cc9999'
  #    - '#99cc99'
  #    - '#99cccc'
  #    - '#cc6666'
  #    - '#ffcc99'
  #    - '#cccc99'
  #    - '#cc99cc'
  #boxBorderColor: '#3333cc'
  #boxBorderWidth: 1
  
  whiskerColor: '#ffff00'
  #whiskerWidth: 1
  
  #fontPath: 'fonts/ipaexg.ttf' # IPA ex Gothic 00401
  #fontSize: 16
  fontColor: '#cccccc'
  
  outlier: true
  #outlierDiameter: 2
  #outlierColor: '#ff0000'
  
  #jitter: true
  #jitterColor: '#009900'
  #jitterDiameter: 2
  
  mean: true
  #meanColor: '#ff0000'
  
  #labels: [ '1st', '2nd', '3rd', '4th', '5th' ]
  labelX: 'Achievement Test'
  labelY: 'Score'
  caption: 'Adjusting the Display By Neon File'
  
  legend: true
  legendBackgroundColor: '#666666'
  #legends: [ 'John', 'Jake', 'Hugo', ]
  legendWidth: 100
  legendFontSize: 10
  
  # Default Color Set
  #colors:
  #    - '#9999cc'
  #    - '#cc9999'
  #    - '#99cc99'
  #    - '#99cccc'
  #    - '#cc6666'
  #    - '#ffcc99'
  #    - '#cccc99'
  #    - '#cc99cc'

Second, Code PHP like this:

• PHP: examples/AdjustDisplayByNeon.php

  <?php
  
  require_once __DIR__ . '/../vendor/autoload.php';
  
  use Macocci7\PhpBoxplot\Boxplot;
  
  $bp = new Boxplot();
  $bp->config('AdjustDisplayByNeon.neon')
     ->create('img/AdjustDisplayByNeon.png');

Then, run the PHP Code.

• Result: examples/img/AdjustDisplayByNeon.png

  

5.5. Adjusting the Display By Array

You can Adjust the Display by using Array.

• PHP: examples/AdjustDisplayByArray.php

  <?php
  
  require_once __DIR__ . '/../vendor/autoload.php';
  
  use Macocci7\PhpBoxplot\Boxplot;
  
  $conf = [
      'dataSet' => [
          'John' => [
              '1st' => [75, 82, 96, 43, 78, 91, 84, 87, 93, ],
              '2nd' => [66, 74, 62, 100, 72, 68, 59, 76, 65, ],
              '3rd' => [56, 0, 45, 76, 58, 52, 13, 48, 54, 68, ],
              '4th' => [68, 32, 56, 92, 67, 72, 45, 76, 48, 73, ],
              '5th' => [70, 58, 62, 88, 62, 68, 56, 63, 64, 78, ],
          ],
          'Jake' => [
              'test#1' => [62, 35, 48, 43, 56, 78, 32, 24, 29, ],
              'test#2' => [37, 92, 56, 36, 14, 86, 41, 58, 47, ],
              'test#3' => [49, 83, 0, 48, 64, 73, 50, 46, 38, 92, ],
              'test#4' => [53, 44, 34, 51, 74, 68, 53, 86, 24, 66, ],
              'test#5' => [83, 61, 55, 96, 87, 46, 21, 19, 88, 68, ],
          ],
          'Hugo' => [
              'test01' => [73, 36, 0, 11, 40, 76, 24, 46, 83, ],
              'test02' => [69, 42, 76, 8, 92, 84, 45, 34, 67, ],
              'test03' => [100, 46, 34, 77, 85, 47, 91, 85, 66, 79, ],
              'test04' => [0, 14, 32, 24, 54, 44, 56, 32, 59, 38, ],
              'test05' => [69, 84, 65, 42, 33, 80, 74, 54, 75, 56, ],
          ],
      ],
      'limitUpper' => 100,
      'limitLower' => 0,
      'canvasBackgroundColor' => '#333399',
      'axisColor' => '#999999',
      'axisWidth' => 2,
      'gridHeightPitch' => 10,
      'gridVertical' => true,
      'whiskerColor' => '#ffff00',
      'fontColor' => '#cccccc',
      'outlier' => true,
      'mean' => true,
      'labelX' => 'Achievement Test',
      'labelY' => 'Score',
      'caption' => 'Adjusting the Display By Array',
      'legend' => true,
      'legendBackgroundColor' => '#666666',
      'legendWidth' => 100,
      'legendFontSize' => 10,
  ];
  
  $bp = new Boxplot();
  $bp->config($conf)
     ->create('img/AdjustDisplayByArray.png');

• Result: examples/img/AdjustDisplayByArray.png

  

5.6. Transparent Background

You can set transparent background like this.

• PHP: examples/TransparentBackground.php

  <?php
  
  require_once __DIR__ . '/../vendor/autoload.php';
  
  use Macocci7\PhpBoxplot\Boxplot;
  
  $data = [
      '1st' => [75, 82, 96, 43, 78, 91, 84, 87, 93],
      '2nd' => [66, 74, 62, 100, 72, 68, 59, 76, 65],
      '3rd' => [56, 0, 45, 76, 58, 52, 13, 48, 54, 68],
      '4th' => [68, 32, 56, 92, 67, 72, 45, 76, 48, 73],
      '5th' => [70, 58, 62, 88, 62, 68, 56, 63, 64, 78],
  ];
  
  $bp = new Boxplot();
  
  $bp->setData($data)
     ->config([
      // This results in Transparent Background
      'canvasBackgroundColor' => null,
  ])
     ->limit(0, 100)
     ->gridHeightPitch(10)
     ->gridVerticalOn()
     ->outlierOn()
     ->meanOn()
     ->labelX('Examination')
     ->labelY('Score')
     ->caption('Transparent Background')
     ->create('img/TransparentBackground.png');

• Result: examples/img/TransparentBackground.png

  

Examples

• BasicUsage.php >> results in:

  

• AdjustDisplayByMethods.php >> results in:

  

• AdjustDisplayByNeon.php >> results in:

  

• AdjustDisplayByArray.php >> results in:

  

• MultipleDataSet.php >> results in:

  

• TransparentBackground.php >> results in:

  

• DetmersReidBoxplot2023.php >> results in:

• BoxplotExampleCase.php >> results in:

  

License

MIT

Document created: 2023/05/28

Document updated: 2025/01/02

Copyright 2023 - 2025 macocci7