npm package: @fnet/relative-levels
Description: 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 c
Latest version: 0.1.18

# @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:

```bash
npm install @fnet/relative-levels
```

or

```bash
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.

   ```javascript
   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.

   ```javascript
   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.

   ```javascript
   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.

```javascript
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.

```javascript
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
```yaml
$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

```