Defining Metrics

Lamotivo metrics allow you to quickly gain insight on key business indicators for your application. For example, you may define a metric to display the total number of users added to your application per day, or the amount of weekly sales.

Lamotivo offers three types of built-in metrics: value, trend, and partition. We'll examine each type of metric and demonstrate their usage below.

Value Metrics

Value metrics display a single value and, if desired, its change compared to a previous time interval. For example, a value metric might display the total number of users created in the last thirty days compared with the previous thirty days.

Value metrics may be generated using the lm:metric Artisan command. By default, all new metrics will be placed in the app/Lm/Metrics directory:

php artisan lm:metric NewUsers

Once your value metric class has been generated, you're ready to customize it. Each value metric class contains a calculate method.

In this example, we are using the count helper, which will automatically perform a count query against the specified Eloquent model for the selected range, as well as automatically retrieve the count for the "previous" range:

<?php

namespace App\Lm\Metrics;

use App\User;
use Illuminate\Http\Request;
use Anyspin\Lamotivo\Metrics\Value;

class NewUsers extends Value
{
    /**
     * Calculate the value of the metric.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return mixed
     */
    public function calculate(Request $request)
    {
        return $this->count($request, User::class);
    }

    /**
     * Get the ranges available for the metric.
     *
     * @return array
     */
    public function ranges()
    {
        return [
            30 => '30 Days',
            60 => '60 Days',
            365 => '365 Days',
            'TODAY' => 'Today',
            'MTD' => 'Month To Date',
            'QTD' => 'Quarter To Date',
            'YTD' => 'Year To Date',
        ];
    }
}

Value Query Types

Value metrics don't just ship with a count helper. You may also use a variety of other aggregate functions when building your metric.

Average

The average method may be used to calculate the average of a given column compared to the previous time interval / range:

return $this->average($request, Post::class, 'word_count');

Sum

The sum method may be used to calculate the sum of a given column compared to the previous time interval / range:

return $this->sum($request, Order::class, 'price');

Max

The max method may be used to calculate the maximum of a given column compared to the previous time interval / range:

return $this->max($request, Order::class, 'total');

Min

The min method may be used to calculate the minimum of a given column compared to the previous time interval / range:

return $this->min($request, Order::class, 'total');

Value Ranges

Every value metric class contains a ranges method. This method determines the ranges that will be available in the value metric's range selection menu. The array's keys determine the number of days that should be included in the query, while the values determine the "human readable" text that will be placed in the range selection menu. You are not required to define any ranges at all:

/**
 * Get the ranges available for the metric.
 *
 * @return array
 */
public function ranges()
{
    return [
        30  => '30 days',
        60  => '60 days',
        90  => '90 days',
        180 => '180 days',
        365 => '365 days',
    ];
}

Trend Metrics

Trend metrics display values over time via a line chart. For example, a trend metric might display the number of new users created per day over the previous thirty days.

Trend metrics may be generated using the lm:metric --trend Artisan command. By default, all new metrics will be placed in the app/Lm/Metrics directory:

php artisan lm:metric UsersPerDay --trend

Once your trend metric class has been generated, you're ready to customize it. Each trend metric class contains a calculate method.

In this example, we are using the countByDays helper, which will automatically perform a count query against the specified Eloquent model for the selected range and for the selected interval unit (in this case, days):

<?php

namespace App\Lm\Metrics;

use App\User;
use Illuminate\Http\Request;
use Anyspin\Lamotivo\Metrics\Trend;

class UsersPerDay extends Trend
{
    /**
     * Calculate the value of the metric.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return mixed
     */
    public function calculate(Request $request)
    {
        return $this->countByDays($request, User::class);
    }

    /**
     * Get the ranges available for the metric.
     *
     * @return array
     */
    public function ranges()
    {
        return [
            30  => '30 days',
            60  => '60 days',
            90  => '90 days',
            180 => '180 days',
            365 => '365 days',
        ];
    }
}

Trend Query Types

Trend metrics don't just ship with a countByDays helper. You may also use a variety of other aggregate functions and time intervals when building your metric.

Count

The count methods may be used to calculate the count of a given column over time:

return $this->countByMonths($request, User::class);
return $this->countByWeeks($request, User::class);
return $this->countByDays($request, User::class);
return $this->countByHours($request, User::class);
return $this->countByMinutes($request, User::class);

Average

The average methods may be used to calculate the average of a given column over time:

return $this->averageByMonths($request, Post::class, 'word_count');
return $this->averageByWeeks($request, Post::class, 'word_count');
return $this->averageByDays($request, Post::class, 'word_count');
return $this->averageByHours($request, Post::class, 'word_count');
return $this->averageByMinutes($request, Post::class, 'word_count');

Sum

The sum methods may be used to calculate the sum of a given column over time:

return $this->sumByMonths($request, Order::class, 'price');
return $this->sumByWeeks($request, Order::class, 'price');
return $this->sumByDays($request, Order::class, 'price');
return $this->sumByHours($request, Order::class, 'price');
return $this->sumByMinutes($request, Order::class, 'price');

Max

The max methods may be used to calculate the maximum of a given column over time:

return $this->maxByMonths($request, Order::class, 'total');
return $this->maxByWeeks($request, Order::class, 'total');
return $this->maxByDays($request, Order::class, 'total');
return $this->maxByHours($request, Order::class, 'total');
return $this->maxByMinutes($request, Order::class, 'total');

Min

The min methods may be used to calculate the minimum of a given column over time:

return $this->minByMonths($request, Order::class, 'total');
return $this->minByWeeks($request, Order::class, 'total');
return $this->minByDays($request, Order::class, 'total');
return $this->minByHours($request, Order::class, 'total');
return $this->minByMinutes($request, Order::class, 'total');

Trend Ranges

Every trend metric class contains a ranges method. This method determines the ranges that will be available in the trend metric's range selection menu. The array's keys determine the number of time interval units (months, weeks, days, etc.) that should be included in the query, while the values determine the "human readable" text that will be placed in the range selection menu. You are not required to define any ranges at all:

/**
 * Get the ranges available for the metric.
 *
 * @return array
 */
public function ranges()
{
    return [
        30  => '30 days',
        60  => '60 days',
        90  => '90 days',
        180 => '180 days',
        365 => '365 days',
    ];
}

Partition Metrics

Partition metrics displays a pie chart of values. For example, a partition metric might display the total number of users for each billing plan offered by your application.

Partition metrics may be generated using the lm:metric --partition Artisan command. By default, all new metrics will be placed in the app/Lm/Metrics directory:

php artisan lm:metric UsersPerPlan --partition

Once your partition metric class has been generated, you're ready to customize it. Each partition metric class contains a calculate method.

In this example, we are using the count helper, which will automatically perform a count query against the specified Eloquent model and retrieve the number of models belonging to each distinct value of your specified "group by" column:

<?php

namespace App\Lm\Metrics;

use App\User;
use Illuminate\Http\Request;
use Anyspin\Lamotivo\Metrics\Partition;

class UsersPerPlan extends Partition
{
    /**
     * Calculate the value of the metric.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return mixed
     */
    public function calculate(Request $request)
    {
        return $this->count($request, User::class, 'stripe_plan');
    }
}

Partition Query Types

Partition metrics don't just ship with a count helper. You may also use a variety of other aggregate functions when building your metric.

Average

The average method may be used to calculate the average of a given column within distinct groups. For example, the following call to the average method will display a pie chart with the average order price for each department of the company:

return $this->average($request, Order::class, 'price', 'department');

Sum

The sum method may be used to calculate the sum of a given column within distinct groups. For example, the following call to the sum method will display a pie chart with the sum of all order prices for each department of the company:

return $this->sum($request, Order::class, 'price', 'department');

Max

The max method may be used to calculate the max of a given column within distinct groups. For example, the following call to the max method will display a pie chart with the maximum order price for each department of the company:

return $this->max($request, Order::class, 'price', 'department');

Min

The min method may be used to calculate the min of a given column within distinct groups. For example, the following call to the min method will display a pie chart with the minimum order price for each department of the company:

return $this->min($request, Order::class, 'price', 'department');

Registering Metrics

Once you have defined a metric, you are ready to attach it to a resource. Each resource contains a cards method. To attach a metric to a resource, you should simply add it to the array of metrics / cards returned by this method:

/**
 * Get the cards available for the resource.
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function cards(Request $request)
{
    return [
        new Metrics\UsersPerDay,
    ];
}

Metric Sizes

By default, metrics take up one-third of the content area. However, you are free to make them larger or smaller. To accomplish this, call the width method when registering the metric with a resource:

/**
 * Get the cards available for the request.
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function cards(Request $request)
{
    return [
        // Two-thirds of the content area...
        (new Metrics\UsersPerDay)->width('2/3'),

        // Full width...
        (new Metrics\UsersPerDay)->width('full'),
    ];
}

The following values are valid to use:

  • full or 1 - the card will take up entire width of the content area
  • 1/3 - one-third of the content area (by default)
  • 2/3 - two-thirds
  • 1/2 - a half
  • 1/4 - a quarter
© 2022 Softmedialine, LLC
Crafted in Siberia