macocci7/php-lorenz-curve

A PHP Library to plot a Lorenz Curve.

0.0.4 2024-08-14 05:38 UTC

Requires

• php: >=8.1
• macocci7/php-frequency-table: ^1.4
• macocci7/php-plotter2d: ^0.1
• nette/neon: ^3.4

Requires (Dev)

• php-parallel-lint/php-parallel-lint: 1.3
• phpmd/phpmd: ^2.15
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.5
• squizlabs/php_codesniffer: ^3.7

MIT

• macocci7

README

A PHP Library to draw a Lorenz Curve.

1. Features

PHP-LorenzCurve draws a Lorenz Curve and also calculates the Gini's coefficient.

2. Contents

• 1. Features
• 2. Contents
• 3. Requirements
• 4. Installation
• 5. Usage
  • 5.1. Basic Usage
  • 5.2. Adjusting the Appearance
    • 5.2.1. Drawing Grid Lines
    • 5.2.2. Drawing an Upward Convex Curve
    • 5.2.3. Setting the Image Size
    • 5.2.4. Setting the Attributes of Plotarea
    • 5.2.5. Setting Caption and Labels
    • 5.2.6. Setting Attributes with Array
    • 5.2.7. Setting Attributes with Neon File
    • 5.2.8. Customisable Attributes
  • 5.3. Gini's Coefficient
• 6. Examples
• 7. LICENSE

3. Requirements

• PHP 8.1 or later
• Imagick PHP Extention
• Composer

4. Installation

composer require macocci7-lorenz-curve

5. Usage

5.1. Basic Usage

To draw a Lorenz Curve, create an instance of LorenzCurve class at first.

<?php

require_once __DIR__ . '/../vendor/autoload.php';

use Macocci7\PhpLorenzCurve\LorenzCurve;

$lc = new LorenzCurve();

Next, set the data, the class range and save the image into a file.

$lc
    ->setData([1, 5, 10, 15, 20])
    ->setClassRange(5)
    ->create('img/BasicUsage.png');

This results in the image below.

5.2. Adjusting the Appearance

5.2.1. Drawing Grid Lines

You can draw grid lines with grid() method specifying the width and the color.

Note: Specifying null as a color code results in transparent.

$lc
    ->setData([1, 5, 10, 15, 20])
    ->setClassRange(5)
    ->grid(1, '#ffcccc')    // width: 1 pix, color: '#ffcccc'
    ->create('img/DrawGrid.png');

This results in the image below.

5.2.2. Drawing an Upward Convex Curve

You can create an upward convex Lorenz Curve by sorting the list of the classes in decending order with reverseClasses() method.

$lc
    ->setData([1, 5, 10, 15, 20])
    ->setClassRange(5)
    ->reverseClasses()
    ->grid(1, '#ffcccc')
    ->create('img/UpwardConvexCurve.png');

This results in the image below.

5.2.3. Setting the Image Size

PHP-LorenzCurve generates images with a width of 400 pixels and a height of 300 pixels by default.

You can change the image size with resize() method.

• format: resize(int $width, int $height)

$lc
    ->setData([1, 5, 10, 15, 20])
    ->setClassRange(5)
    ->grid(1, '#ffcccc')
    ->resize(450, 400)
    ->create('img/ResizeImage.png');

This code results in as below:

5.2.4. Setting the Attributes of Plotarea

By default, PHP-LorenzCurve sets the Attributes of Plotarea:

• offsetX: 10% of the image width
• offsetY: 10% of the image height
• width: 80% of the image width
• height: 70% of the image height
• backgroundColor: null (transparent)

You can change them with plotarea() method.

• format:

  plotarea(
      array $offset = [], // [int $width, int $height]
      int $width = 0,
      int $height = 0,
      string|null $backgroundColor = null,
  )

Sample code:

$lc
    ->setData([1, 5, 10, 15, 20])
    ->setClassRange(5)
    ->grid(1, '#ffcccc')
    ->plotarea(
        offset: [80, 50],
        width: 280,
        height: 200,
        backgroundColor: '#eeeeee',
    )
    ->create('img/SetPlotareaAttrs.png');

This code results in as below:

5.2.5. Setting Caption and Labels

You can set the Caption and Labels with caption(), labelX() and labelY() methods.

• Format:

  caption(
      string $caption,
      int $offsetX = 0,
      int $offsetY = 0,
  )

  labelX(
      string $label,
      int $offsetX = 0,
      int $offsetY = 0,
  )

  labelY(
      string $label,
      int $offsetX = 0,
      int $offsetY = 0,
  )

Sample code:

$lc
    ->setData([1, 5, 10, 15, 20])
    ->setClassRange(5)
    ->grid(1, '#ffcccc')
    ->plotarea(offset: [60, 40])
    ->caption('CAPTION')
    ->labelX('Cumulative Relative Frequency', offsetX: 0, offsetY: 10)
    ->labelY('Cumulative Relative Subtotal')
    ->create('img/CaptionLabels.png');

This code results in as below:

5.2.6. Setting Attributes with Array

You can set attributes with the config() method passing array as an argument.

$lc
    ->setData([1, 5, 10, 15, 20])
    ->setClassRange(5)
    ->config([
        'canvasBackgroundColor' => '#3333cc',
        'showGrid' => true,
        'gridWidth' => 1,
        'gridColor' => '#0066ff',
        'axisWidth' => 3,
        'axisColor' => '#ffffff',
        'scaleWidth' => 2,
        'scaleLength' => 6,
        'scaleColor' => '#ffffff',
        'scaleFontSize' => 14,
        'scaleFontColor' => '#ffffff',
        'lorenzCurveWidth' => 1,
        'lorenzCurveColor' => '#ffff00',
        'lorenzCurveBackgroundColor' => null, // transparent
        'completeEqualityLineWidth' => 3,
        'completeEqualityLineColor' => '#ffffff',
        'completeEqualityLineDash' => [8, 8],
        'fontColor' => '#ffffff',
        'caption' => 'Config From Array',
    ])
    ->create('img/ConfigFromArray.png');

This code results in as below:

See more: Customizable Attributes

5.2.7. Setting Attributes with Neon File

You can set attributes with config() method passing the neon file path as an argument.

First, create a Neon File.

canvasBackgroundColor: '#3333cc'
showGrid: true
gridWidth: 1
gridColor: '#0066ff'
axisWidth: 3
axisColor: '#ffffff'
scaleWidth: 2
scaleLength: 6
scaleColor: '#ffffff'
scaleFontSize: 14
scaleFontColor: '#ffffff'
lorenzCurveWidth: 1
lorenzCurveColor: '#ffff00'
lorenzCurveBackgroundColor:
completeEqualityLineWidth: 3
completeEqualityLineColor: '#ffffff'
completeEqualityLineDash: [8, 8]
fontColor: '#ffffff'
caption: 'Config From File'

Second, specify the path of the neon file as an argument of the config() method.

$lc
    ->setData([1, 5, 10, 15, 20])
    ->setClassRange(5)
    ->config('ConfigFromFile.neon')
    ->create('img/ConfigFromFile.png');

This code results in as below:

See more: Customizable Attributes

5.2.8. Customisable Attributes

5.3. Gini's Coefficient

You can get the Gini's Coefficient with getGinisCoefficient() method without generating an image.

var_dump(
    $lc
    ->setData([1, 5, 10, 15, 20])
    ->setClassRange(5)
    ->getGinisCoefficient()
);

This results in as below.

double(0.37647058823529)

6. Examples

• BasicUsage.php >> results in:

  

• DrawGrid.php >> results in:

  

• UpwardConvexCurve.php >> results in:

  

• ResizeImage.php >> results in:

  

• SetPlotareaAttrs.php >> results in:

  

• CaptionLabels.php >> results in:

  

• ConfigFromArray.php >> results in:

  

• ConfigFromFile.php with ConfigFromFile.neon >> results in:

  

• GinisCoefficient.php >> results in:

  double(0.37647058823529)

• GinisCoefficient0.php >> results in:

  

  ▼Gini's Coefficient:

  double(0)

• GinisCoefficientAlmost1.php >> results in:

  

  ▼Gini's Coefficient:

  double(0.99800399201597)

• GinisCoefficient1.php >> results in:

  

  ▼Gini's Coefficient:

  double(1)

7. LICENSE

MIT

Copyright 2024 macocci7