analyticsLibrary.Core 2.0.0-beta.pr-9.13

analyticsLibrary

A family of focused .NET 8 packages for reading and writing CSV and fixed-width files, performing statistical operations, running sort and search algorithms, and working with Excel, Access, and Hadoop data sources.

Version 2.0.0 is a breaking-change release. The monolithic analyticsLibrary 1.x package has been split into focused packages. SQL Server, Oracle, SAS, and Sybase provider support has been removed. See the Migration Guide below.

analyticsLibrary.Excel 3.0.0 removes EPPlus (PolyForm NonCommercial) in favor of FOSS-only dependencies (NPOI Apache-2.0, ExcelDataReader MIT). This is a breaking change for callers using EPPlus-typed API surface. See From analyticsLibrary.Excel 2.x to 3.0.0 in the Migration Guide.

Table of Contents

• Package Overview
• Namespace Reference
• Installation
• Quick Starts
• Functionality
• Repository Layout
• Build and Test
• Release Process
• Contributing
• Migration Guide

Package Overview

Platform note: analyticsLibrary.Access depends on System.Data.OleDb, which is Windows-only at runtime. analyticsLibrary.Excel uses NPOI and ExcelDataReader, which are cross-platform.

Namespace Reference

Installation

Install only the packages you need for a leaner dependency graph.

# Core CSV and data helpers
dotnet add package analyticsLibrary.Core

# Sort and search algorithms
dotnet add package analyticsLibrary.Algorithms

# Statistics
dotnet add package analyticsLibrary.Statistics

# Excel file operations (cross-platform: .xlsx/.xls/.xlsb read; .xlsx/.xls write)
dotnet add package analyticsLibrary.Excel

# Access database support (Windows runtime only)
dotnet add package analyticsLibrary.Access

# Hadoop/ODBC support
dotnet add package analyticsLibrary.Hadoop

# Everything (transition metapackage)
dotnet add package analyticsLibrary

Quick Starts

Read a CSV file

using analyticsLibrary.Core;

var file = new csv("data.csv");
foreach (var row in file.data)
{
    Console.WriteLine(string.Join(", ", row.values));
}

Write a CSV file

using analyticsLibrary.Core;

var header = new[] { "Name", "Score" };
var rows = new[]
{
    new object[] { "Alice", 95 },
    new object[] { "Bob",   87 },
};
rows.writeCsv("output.csv", header, ',');

Standard deviation and normalization

using analyticsLibrary.Statistics;

double[] scores = { 70, 80, 85, 90, 95 };
double stddev = scores.standardDeviation();
double[] normalized = scores.normalize();  // maps min to 0.0, max to 1.0

Sort a list

using analyticsLibrary.Algorithms;

int[] values = { 5, 3, 8, 1, 9 };
int[] sorted = values.mergeSort();           // ascending
int[] desc   = values.quickSort(descending: true);  // descending

Parse a SAS date string

using analyticsLibrary.Core;

DateTime? date = "01JAN2020:00:00:00.000".fromSasEpochDate();

Functionality

CSV and Fixed-Width Files (analyticsLibrary.Core)

• Read CSV files with configurable delimiters and optional headers via the csv class.
• Write IEnumerable<object[]> to CSV using writeCsv extension methods.
• Parse individual CSV lines with fromCsv and serialize object arrays with toCsv.
• Read fixed-width files with fixedWidthFile and fixedWidthFileStream.
• loopDateRange iterates over a date range with configurable step intervals.

Statistics (analyticsLibrary.Statistics)

All methods are extension methods on double[] or IEnumerable<double>:

Algorithms (analyticsLibrary.Algorithms)

• mergeSort<T>() — stable recursive merge sort; supports ascending and descending order for int, double, float, decimal, and string.
• quickSort<T>() — in-place quick sort; same type support as merge sort.
• sorting.pickFunction<T>() — returns the comparison delegate for a given type; useful for supplying a custom comparator.

Core Helpers (analyticsLibrary.Core)

• dataTypeHelper.dataTypeFromString(string) — maps SQL/ODBC type name strings (e.g. "varchar", "int") to dataTypeEnum values.
• analytics — compress(), titleCase(), wordReplace() string extension methods.
• extensions.fromSasEpochDate() — parses a SAS datetime string in ddMMMyyyy:hh:mm:ss.fff format.

Excel (analyticsLibrary.Excel)

• Read and write Excel workbooks and individual worksheets as DataSet/DataTable.
• Target individual cells in an existing workbook.

Access (analyticsLibrary.Access, Windows)

• Open and query Access .mdb/.accdb database files via OleDb.

Hadoop (analyticsLibrary.Hadoop)

• Read data from Hadoop clusters via an ODBC connection string.

Repository Layout

.github/
  workflows/
    ci.yml        # PR: build, test, pack, upload beta artifacts
    release.yml   # Tag/dispatch: build, test, pack, deploy to NuGet
src/
  analyticsLibrary.Core/
  analyticsLibrary.Algorithms/
  analyticsLibrary.Statistics/
  analyticsLibrary.Excel/
  analyticsLibrary.Access/
  analyticsLibrary.Hadoop/
  analyticsLibrary/           # transition metapackage
  analyticsLibraryInstaller/
  release files/
tests/
  analyticsLibrary.Core.Tests/
  analyticsLibrary.Statistics.Tests/
  analyticsLibrary.Algorithms.Tests/
docs/
  epics/
    epic-001-remodel.plan.md
Directory.Packages.props      # centralized NuGet version management
Analytics Library.sln

Build and Test

Requirements: .NET 8 SDK or later.

# Restore dependencies
dotnet restore

# Build all projects (Release)
dotnet build -c Release

# Run all unit tests
dotnet test -c Release

# Pack NuGet packages into ./nupkgs
dotnet pack -c Release -o ./nupkgs

Release Process

Beta packages (pull requests)

Opening or updating a pull request against main triggers ci.yml. The workflow builds, tests, packs only the package projects whose src/analyticsLibrary.* paths changed (or when central/tooling paths change—see workflow filters), using beta versions read from each .csproj <Version> plus -beta.pr-<pr>.<run>. It uploads .nupkg files as workflow artifacts. Beta packages are pushed to NuGet.org only on the pull_request event when NUGET_API_KEY is set and the PR branch is from the same repository (not a fork). Merging the PR to main does not publish betas to NuGet.org.

Stable release packages

Publishing a stable release to NuGet.org is not triggered by merging a pull request alone. You must either push a SemVer tag matching v*.*.* (for example v3.0.0) at the commit you want to ship, or run release.yml manually via workflow dispatch and enter the version (for example 3.0.0).

The release.yml workflow then:

1. Builds and tests the full solution (including release-tooling tests under tests/analyticsLibrary.ReleaseTooling.Tests/).
2. Packs all seven packages at the same release version (no path-based skipping).
3. Verifies every expected .nupkg is present.
4. Pushes packages to NuGet.org. This step uses the nuget-release GitHub Environment so you can require manual approval before anything is published.
5. Deprecates previously published versions on NuGet.org: all CI beta builds whose versions contain -beta.pr- are marked with an “other” deprecation reason and a testing-only message; every older stable version below the version you just shipped is marked legacy with the message: This package is legacy and is no longer maintained. The deprecation client calls NuGet.org’s HTTP API (PUT https://www.nuget.org/api/v2/package/{packageId}/deprecations) using the same NUGET_API_KEY. The key must include permission to push and unlist (deprecation uses the unlist scope on nuget.org). If NuGet.org returns 403 for deprecation, the account may not yet have the manage-deprecation API enabled for API keys; in that case you can deprecate versions manually on nuget.org until the API is available.

Store the NuGet API key as a repository secret named NUGET_API_KEY. Never commit credentials.

CI also runs actionlint on workflow files.

Contributing

• Keep packages focused. Core must not depend on Excel, Access, Hadoop, or provider-specific packages.
• Add tests for all new public logic before submitting a PR. Tests live in tests/.
• analyticsLibrary.Excel uses NPOI (Apache-2.0) and ExcelDataReader (MIT)—no commercial license required. All Excel read/write operations are FOSS.
• System.Data.OleDb is Windows-only at runtime. Keep it isolated to analyticsLibrary.Access.
• Package versions are centrally managed in Directory.Packages.props. Add new dependencies there first.

Migration Guide

From analyticsLibrary 1.x to 2.0.0

Removed packages and namespaces

Steps to migrate

1. Remove analyticsLibrary 1.x from your project.
2. Add the focused 2.x packages you need (see Installation).
3. Update using directives to the new namespaces:
   • analyticsLibrary.library → analyticsLibrary.Core
   • analyticsLibrary.cs → analyticsLibrary.Algorithms
   • analyticsLibrary.statistics → analyticsLibrary.Statistics
   • analyticsLibrary.excelLibrary → analyticsLibrary.Excel
   • analyticsLibrary.access → analyticsLibrary.Access
   • analyticsLibrary.hadoop → analyticsLibrary.Hadoop
4. Remove any references to the deleted namespaces (sqlDb, oracle, sas, sybase) and their package references listed above.
5. If you called fromSasDate(), rename it to fromSasEpochDate().

Target framework: Projects must target net8.0 or later. netcoreapp3.1 is no longer supported.

From analyticsLibrary.Excel 2.x to 3.0.0

analyticsLibrary.Excel 3.0.0 removes EPPlus and OleDb entirely. All Excel read and write operations now use NPOI (Apache-2.0) and ExcelDataReader (MIT).

Removed public APIs

New / expanded APIs (3.0.0)

• getWorkbookSheetDatasets(string fileName) — returns DataSet[], one per worksheet; .xlsx sheets include per-table DataTable instances for Excel structured tables; all three formats supported.
• getWorkbookSheetDatasets(Stream stream, string formatHint) — stream overload for in-memory use.
• writeSheetDataXlsx(string, string, object[,], bool) — write data grid to .xlsx, optionally deleting existing file.
• writeSheetDataXlsx<T>(string, string, IEnumerable<T>) — write typed list with auto header row.
• copySheet(string, string, string) — clone a worksheet within an .xlsx file.
• deleteTable(string, string, string) — remove a named Excel structured table from a sheet.

xlsb write: Writing .xlsb files is not supported. Calls to write APIs with a .xlsb path throw NotSupportedException. Reading .xlsb is supported via ExcelDataReader.