Dataset.cs

using System.Collections.Generic;
using System.Linq;
using System.Text.Json;
using System.Text.Json.Serialization;
using JSONstat.IO;

namespace JSONstat.Models;

/// <summary>
/// A JSON-stat dataset: a multi-dimensional cube of values with dimensions,
/// optional roles, status, and metadata. Carries the Toolkit-parity read and
/// navigation surface (<c>Dimension</c>, <c>Data</c>, ...) and the non-deprecated
/// transforms (<c>Dice</c>, <c>Unflatten</c>, <c>Transform</c>).
/// Source: <c>../wiki/dataset-structure.md</c>.
/// </summary>
public sealed partial class Dataset : IJsonOnDeserialized
{
    /// <summary>JSON-stat version.</summary>
    public string? Version { get; set; } = "2.0";

    /// <summary>The response class (always <see cref="ResponseClass.Dataset"/>).</summary>
    public ResponseClass Class { get; set; } = ResponseClass.Dataset;

    /// <summary>Short descriptive text.</summary>
    public string? Label { get; set; }

    /// <summary>Source description.</summary>
    public string? Source { get; set; }

    /// <summary>Update time (ISO 8601).</summary>
    public string? Updated { get; set; }

    /// <summary>Ordered dimension ids.</summary>
    public string[]? Id { get; set; }

    /// <summary>Category counts per dimension (same order as <see cref="Id"/>).</summary>
    public int[]? Size { get; set; }

    /// <summary>Optional dimension roles.</summary>
    public Role? Role { get; set; }

    /// <summary>The dimension map (wire property <c>dimension</c>).</summary>
    [JsonPropertyName("dimension")]
    public Dictionary<string, Dimension> DimensionMap { get; set; } = new Dictionary<string, Dimension>();

    /// <summary>The data values (dense array or sparse object).</summary>
    public ValueCollection? Value { get; set; }

    /// <summary>Observation-level status (array, string, or object).</summary>
    public StatusCollection? Status { get; set; }

    /// <summary>Annotations.</summary>
    public string[]? Note { get; set; }

    /// <summary>Related resources.</summary>
    public Link? Link { get; set; }

    /// <summary>Provider-specific extension.</summary>
    public JsonElement? Extension { get; set; }

    /// <summary>Provider-specific extension properties not modelled explicitly.</summary>
    [JsonExtensionData]
    public IDictionary<string, JsonElement>? ExtensionData { get; set; }

    private long _n;
    private Dimension[] _orderedDimensions = System.Array.Empty<Dimension>();
    private bool _linked;
    private List<Datum>? _dataCache;

    /// <summary>Wires dimension ids/roles/sizes and computes <see cref="N"/>.</summary>
    internal Dataset Wire()
    {
        if (_linked) return this;
        var ids = Id ?? System.Array.Empty<string>();
        var sizes = Size ?? System.Array.Empty<int>();

        var ordered = new List<Dimension>(ids.Length);
        for (int i = 0; i < ids.Length; i++)
        {
            var id = ids[i];
            if (!DimensionMap.TryGetValue(id, out var dim))
            {
                dim = new Dimension();
                DimensionMap[id] = dim;
            }
            dim.Id = id;
            dim.Role = Role != null && Role.RoleOf(id) is { } r ? r : DimensionRole.Classification;
            dim.Wire(i < sizes.Length ? sizes[i] : 0);
            ordered.Add(dim);
        }
        _orderedDimensions = ordered.ToArray();

        long n = 1;
        foreach (var s in sizes) n *= s;
        _n = n;
        _linked = true;
        return this;
    }

    /// <inheritdoc />
    void IJsonOnDeserialized.OnDeserialized() => Wire();

    private void EnsureLinked() => Wire();

    private int[] Sizes => Size ?? System.Array.Empty<int>();

    /// <summary>Total number of cells in the cube (including missing).</summary>
    [JsonIgnore]
    public long N
    {
        get { EnsureLinked(); return _n; }
    }

    /// <summary>The dimensions in id order.</summary>
    [JsonIgnore]
    public IReadOnlyList<Dimension> Dimensions
    {
        get { EnsureLinked(); return _orderedDimensions; }
    }

    /// <summary>Gets the dimension at <paramref name="index"/>, or <c>null</c>.</summary>
    public Dimension? Dimension(int index)
    {
        EnsureLinked();
        return index >= 0 && index < _orderedDimensions.Length ? _orderedDimensions[index] : null;
    }

    /// <summary>Gets the dimension with id <paramref name="id"/>, or <c>null</c>.</summary>
    public Dimension? Dimension(string id)
    {
        EnsureLinked();
        return DimensionMap.TryGetValue(id, out var dim) ? dim : null;
    }

    /// <summary>Gets the first dimension with the given role, or <c>null</c>.</summary>
    public Dimension? Dimension(DimensionRole role)
    {
        EnsureLinked();
        return _orderedDimensions.FirstOrDefault(d => d.Role == role);
    }

    /// <summary>Encodes per-dimension category indices into a linear index.</summary>
    public long LinearOf(int[] indices)
    {
        EnsureLinked();
        return Cube.CubeIndex.ToLinear(Sizes, indices);
    }

    /// <summary>Resolves dimension-id/category-id pairs into category indices.</summary>
    public int[]? IndicesOf(IReadOnlyDictionary<string, string> byId)
    {
        EnsureLinked();
        var ids = Id ?? System.Array.Empty<string>();
        var indices = new int[ids.Length];
        foreach (var pair in byId)
        {
            int d = System.Array.IndexOf(ids, pair.Key);
            if (d < 0) return null;
            if (!DimensionMap.TryGetValue(pair.Key, out var dim)) return null;
            var pos = dim.CategoryInfo.PositionOf(pair.Value);
            if (!pos.HasValue) return null;
            indices[d] = pos.Value;
        }
        return indices;
    }

    /// <summary>The value at a linear index (<c>null</c> when missing). Equivalent to the
    /// Toolkit's <c>Data(id, false)</c>.</summary>
    public double? ValueAt(int linear) => (Value ?? ValueCollection.Empty()).GetValue(linear);

    /// <summary>The value at the given category indices.</summary>
    public double? ValueAt(int[] indices) => ValueAt((int)LinearOf(indices));

    /// <summary>The value resolved by dimension-id/category-id pairs.</summary>
    public double? ValueAt(IReadOnlyDictionary<string, string> byId)
    {
        var indices = IndicesOf(byId);
        return indices is null ? (double?)null : ValueAt(indices);
    }

    /// <summary>The status at a linear index, or <c>null</c>.</summary>
    public string? StatusAt(int linear) => Status?.GetStatus(linear);

    /// <summary>All observations, in linear order.</summary>
    public IReadOnlyList<Datum> Data() => _dataCache ??= EnumerateData().ToList();

    /// <summary>The observation at a linear index.</summary>
    public Datum Data(int linear) => new Datum(ValueAt(linear), StatusAt(linear));

    /// <summary>The observation at the given category indices, or <c>null</c> if invalid.</summary>
    public Datum? Data(int[] indices)
    {
        if (indices == null || indices.Length != (Id?.Length ?? 0)) return null;
        return Data((int)LinearOf(indices));
    }

    /// <summary>The observation resolved by dimension-id/category-id pairs, or <c>null</c> if invalid.</summary>
    public Datum? Data(IReadOnlyDictionary<string, string> byId)
    {
        var indices = IndicesOf(byId);
        return indices is null ? null : Data(indices);
    }

    /// <summary>Enumerates observations in linear order without materializing the whole cube.</summary>
    public IEnumerable<Datum> EnumerateData()
    {
        EnsureLinked();
        for (int i = 0; i < _n; i++) yield return new Datum(ValueAt(i), StatusAt(i));
    }
}