FractalDataWorks.Calculations.Aggregations 0.6.0-rc.1

FractalDataWorks.Calculations.Aggregations

TypeCollection of aggregation functions for the FractalDataWorks calculation framework. This package provides extensible aggregation functions (Sum, Average, Min, Max, Count, etc.) that operate on collections of decimal values.

Overview

FractalDataWorks.Calculations.Aggregations implements the TypeCollection pattern to provide a discoverable, extensible set of aggregation functions. These functions are commonly used in:

• Data Analysis: Summarizing datasets for reporting
• ETL Pipelines: Transforming and aggregating data during extract/transform/load operations
• Financial Calculations: Computing totals, averages, and statistical measures
• Dashboard Metrics: Real-time aggregation of key performance indicators

Target Frameworks: .NET 10.0 Dependencies: FractalDataWorks.Calculations.Abstractions, FractalDataWorks.Collections

Two TypeCollection Systems

This package provides two parallel TypeCollection systems for aggregation:

1. AggregationFunctions - Functions with an Aggregate() method, used for direct aggregation operations
2. AggregationTypes - Types with a Calculate() method, extending CalculationTypeBase for integration with the broader calculation framework

Both follow the TypeCollection pattern for discovery and O(1) lookups.

What Are Aggregation Functions?

Aggregation functions reduce a collection of values into a single summary value:

• Input: IReadOnlyList<decimal> - A collection of decimal values
• Output: decimal - A single aggregated result
• Pure Functions: No side effects, deterministic results
• TypeCollection: Discoverable through AggregationFunctions or AggregationTypes TypeCollections

Core Components

IAggregationFunction

From IAggregationFunction.cs:6-18:

/// <summary>
/// Interface for aggregation functions.
/// Extends ITypeOption to enable TypeCollection discovery.
/// </summary>
public interface IAggregationFunction : ITypeOption<int, AggregationFunctionBase>
{
    /// <summary>
    /// Applies the aggregation function to the provided values.
    /// </summary>
    /// <param name="values">The values to aggregate.</param>
    /// <returns>The aggregated result.</returns>
    decimal Aggregate(IReadOnlyList<decimal> values);
}

AggregationFunctionBase

From AggregationFunctionBase.cs:6-26:

/// <summary>
/// Base class for all aggregation functions.
/// </summary>
public abstract class AggregationFunctionBase : TypeOptionBase<int, AggregationFunctionBase>, IAggregationFunction
{
    /// <summary>
    /// Initializes a new instance of the <see cref="AggregationFunctionBase"/> class.
    /// </summary>
    /// <param name="id">The unique identifier for the aggregation function.</param>
    /// <param name="name">The name of the aggregation function.</param>
    protected AggregationFunctionBase(int id, string name) : base(id, name)
    {
    }

    /// <summary>
    /// Applies the aggregation function to the provided values.
    /// </summary>
    /// <param name="values">The values to aggregate.</param>
    /// <returns>The aggregated result.</returns>
    public abstract decimal Aggregate(IReadOnlyList<decimal> values);
}

AggregationFunctions TypeCollection

From AggregationFunctions.cs:1-16:

/// <summary>
/// TypeCollection for aggregation functions.
/// </summary>
/// <remarks>
/// Provides compile-time discovery and O(1) lookup for aggregation functions.
/// Source generator creates static properties for each aggregation function.
/// </remarks>
[TypeCollection(typeof(AggregationFunctionBase), typeof(IAggregationFunction), typeof(AggregationFunctions))]
public sealed partial class AggregationFunctions : TypeCollectionBase<AggregationFunctionBase, IAggregationFunction>
{
}

Generated methods include:

• All() - Returns all aggregation functions
• ById(int id) - Find by unique identifier
• ByName(string name) - Find by function name
• Static properties for each function (e.g., AggregationFunctions.Sum)

AggregationTypes TypeCollection

From Types/AggregationTypes.cs:1-17:

/// <summary>
/// Collection of all aggregation types.
/// </summary>
/// <remarks>
/// This collection is populated by the source generator with all types
/// that inherit from AggregationTypeBase and implement IAggregationType.
/// Provides high-performance lookups for aggregation discovery.
/// </remarks>
[TypeCollection(typeof(AggregationTypeBase), typeof(IAggregationType), typeof(AggregationTypes))]
public abstract partial class AggregationTypes : TypeCollectionBase<AggregationTypeBase, IAggregationType>
{
}

Built-in Aggregation Functions

The AggregationFunctions TypeCollection includes five built-in functions:

Built-in Aggregation Types

The AggregationTypes TypeCollection extends CalculationTypeBase and includes additional statistical functions:

Implementation Examples

AggregationFunction Implementation

From Functions/SumAggregationFunction.cs:1-25:

using System.Collections.Generic;
using System.Linq;
using FractalDataWorks.Collections.Attributes;

namespace FractalDataWorks.Calculations.Aggregations.Functions;

/// <summary>
/// Sum aggregation function - sums all values.
/// </summary>
[TypeOption(typeof(AggregationFunctions), "Sum")]
public sealed class SumAggregationFunction : AggregationFunctionBase
{
    /// <summary>
    /// Initializes a new instance of the <see cref="SumAggregationFunction"/> class.
    /// </summary>
    public SumAggregationFunction() : base(id: 1, name: "Sum")
    {
    }

    /// <inheritdoc/>
    public override decimal Aggregate(IReadOnlyList<decimal> values)
    {
        return values.Sum();
    }
}

AggregationFunction with Empty Collection Handling

From Functions/AverageAggregationFunction.cs:1-28:

using System.Collections.Generic;
using System.Linq;
using FractalDataWorks.Collections.Attributes;

namespace FractalDataWorks.Calculations.Aggregations.Functions;

/// <summary>
/// Average aggregation function - calculates mean of all values.
/// </summary>
[TypeOption(typeof(AggregationFunctions), "Average")]
public sealed class AverageAggregationFunction : AggregationFunctionBase
{
    /// <summary>
    /// Initializes a new instance of the <see cref="AverageAggregationFunction"/> class.
    /// </summary>
    public AverageAggregationFunction() : base(id: 2, name: "Average")
    {
    }

    /// <inheritdoc/>
    public override decimal Aggregate(IReadOnlyList<decimal> values)
    {
        if (values.Count == 0)
            return 0;

        return values.Average();
    }
}

AggregationType Implementation (Median with sorting)

From Types/MedianAggregationType.cs:1-35:

using System.Collections.Generic;
using System.Linq;
using FractalDataWorks.Collections.Attributes;

namespace FractalDataWorks.Calculations.Aggregations.Types;

/// <summary>
/// Aggregation type that calculates the median (middle) value.
/// </summary>
[TypeOption(typeof(AggregationTypes), "Median")]
public sealed class MedianAggregationType : AggregationTypeBase
{
    /// <summary>
    /// Initializes a new instance of the <see cref="MedianAggregationType"/> class.
    /// </summary>
    public MedianAggregationType() : base(6, "Median")
    {
    }

    /// <inheritdoc/>
    public override decimal Calculate(IReadOnlyList<decimal> values)
    {
        var sortedValues = values.OrderBy(v => v).ToList();
        var count = sortedValues.Count;

        if (count % 2 == 0)
        {
            var mid1 = sortedValues[count / 2 - 1];
            var mid2 = sortedValues[count / 2];
            return (mid1 + mid2) / 2;
        }

        return sortedValues[count / 2];
    }
}

Statistical Function (Standard Deviation)

From Types/StandardDeviationAggregationType.cs:1-29:

using System;
using System.Collections.Generic;
using System.Linq;
using FractalDataWorks.Collections.Attributes;

namespace FractalDataWorks.Calculations.Aggregations.Types;

/// <summary>
/// Aggregation type that calculates the standard deviation of values.
/// </summary>
[TypeOption(typeof(AggregationTypes), "StandardDeviation")]
public sealed class StandardDeviationAggregationType : AggregationTypeBase
{
    public StandardDeviationAggregationType() : base(8, "StandardDeviation")
    {
    }

    /// <inheritdoc/>
    public override decimal Calculate(IReadOnlyList<decimal> values)
    {
        var average = values.Average();
        var sumOfSquares = values.Sum(v => (v - average) * (v - average));
        var variance = sumOfSquares / values.Count;
        return (decimal)Math.Sqrt((double)variance);
    }
}

TypeCollection Pattern

Auto-Discovery

Aggregation functions and types are automatically discovered through the [TypeOption] attribute. No manual registration is required - the source generator handles discovery automatically.

Creating Custom Aggregations

To add a new aggregation function:

1. Create a class that inherits AggregationFunctionBase
2. Add the [TypeOption(typeof(AggregationFunctions), "FunctionName")] attribute
3. Implement the Aggregate method
4. Rebuild the project

To add a new aggregation type (for calculation framework integration):

1. Create a class that inherits AggregationTypeBase
2. Add the [TypeOption(typeof(AggregationTypes), "TypeName")] attribute
3. Implement the Calculate method
4. Rebuild the project

The new function/type is immediately available through ByName() and All() methods.

Best Practices

1. Handle Empty Collections: Return 0 or a sensible default for empty input (see AverageAggregationFunction for example)
2. Null Safety: Check for null input and handle gracefully
3. Precision: Be aware of decimal precision limits for large datasets
4. Immutability: Never modify the input collection
5. ID Assignment: Use unique IDs (built-in: 1-99, custom: 100+)

Dependencies

• FractalDataWorks.Calculations.Abstractions: Base interfaces and types (CalculationTypeBase, ICalculationType)
• FractalDataWorks.Collections: TypeCollection infrastructure (TypeCollectionBase, TypeOptionBase, [TypeOption] attribute)
• FractalDataWorks.Collections.SourceGenerators: Source generator for TypeCollection discovery

See Also

• FractalDataWorks.Calculations.Abstractions: Core calculation interfaces
• FractalDataWorks.Collections: TypeCollection pattern documentation
• FractalDataWorks.Calculations: General calculation implementations