@fnet/relative-levels

The @fnet/relative-levels module is designed to process a list of numbers, categorizing them into distinct levels. By applying internal calculations, it groups the numbers into these levels, helping users understand the distribution of their data more clearly.

How It Works

The module takes an array of numbers and divides them into a specified number of levels. It calculates an average for each level and uses linear interpolation to predict these averages across the entire range. The levels are organized around a central average, with upper and lower levels determined based on their proximity to this average. The end result is a structured set of ranges and corresponding counts of numbers falling within each range.

Key Features

• Level Calculation: Categorizes numbers into user-defined levels, defaulting to 5.
• Average and Count Reporting: Provides averages and counts of numbers within each level.
• Flexible Input: Works with arrays of numbers or objects via a specified key.
• Error Handling: Ensures inputs are valid and levels are properly defined.
• Linear Interpolation: Predicts averages using linear interpolation for each level's range.

Conclusion

The @fnet/relative-levels module offers a straightforward way to analyze and categorize numerical data into levels. It is a useful tool for users who need to organize their data into meaningful segments, providing insights into the distribution and central tendencies in a data set.

@fnet/relative-levels Developer Guide

Overview

The @fnet/relative-levels library is designed to process arrays of numbers, calculate level averages, and fit a function to the data. It divides numbers into specified levels, provides statistical insights (like range and count) for each level, and supports the retrieval of value-specific statistics, helping developers interpret numerical data.

Installation

To use @fnet/relative-levels, you can install it via npm or yarn:

npm install @fnet/relative-levels

or

yarn add @fnet/relative-levels

Usage

Here's a simple guide to using the library to process and analyze an array of numbers.

1. Import the library:

   Start by importing the main function from the library.

   import relativeLevels from '@fnet/relative-levels';

2. Process your data:

   Use the function to calculate levels for your data. You can specify the number of levels you wish to calculate.

   const inputNumbers = [10, 20, 15, 30, 25, 35, 40];
   const levels = 5; // can be customized, must be odd and greater than 2
   
   const result = relativeLevels({
       numbers: inputNumbers,
       levels
   });
   
   console.log(result.bins); // Displays the range and count for each level

3. Retrieve statistics for a specific value:

   Use the returned object's method to get detailed statistics for a specific value.

   const numberStats = result.get(25);
      
   if (numberStats) {
       console.log(`Level: ${numberStats.level}`);
       console.log(`Position within range: ${numberStats.position}`);
   } else {
       console.log('Number 25 is not within any calculated range');
   }

Examples

Example 1: Basic Usage

Calculate levels for an array and print out the results.

import relativeLevels from '@fnet/relative-levels';

const numbers = [5, 10, 15, 20, 25, 30];
const { bins, get } = relativeLevels({ numbers, levels: 5 });

console.log(bins);
// Example output: 
// [
//   { range: [-Infinity, 10], count: 2, avg: 7.5, min: 5, max: 10 },
//   { range: [10, 20], count: 2, avg: 15, min: 10, max: 20 },
//   ...
// ]

Example 2: Retrieving Level Information for a Specific Number

After processing, find which bin a number belongs to and its relative position.

import relativeLevels from '@fnet/relative-levels';

const numbers = [2, 8, 15, 22, 28];
const data = relativeLevels({ numbers, levels: 5 });

const numberDetails = data.get(15);
if (numberDetails) {
    console.log(numberDetails);
    // Example output: { bin: {...}, level: 2, position: 0.5 }
} else {
    console.log('Number is not in any bin');
}

Acknowledgement

While this project is self-contained, we acknowledge all contributors working towards making and maintaining effective and efficient open-source programming libraries. Thank you for your work and support.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  numbers:
    type: array
    items:
      type: number
    description: The array of numbers to process.
  key:
    type: string
    description: Optional key to map numbers from objects.
  levels:
    type: integer
    description: The number of levels (must be odd and > 2).
    default: 5
    minimum: 3
    not:
      multipleOf: 2
required:
  - numbers