# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved.
=== ProEssentials Data Handling (knowledge rev 4.1) Patterns ===

DATA LOADING PATTERNS (choose based on data source and performance needs):

PATTERN 1 -- DIRECT INDEXING (simple, small datasets)
  Set Subsets and Points, then assign Y[subset, point] = value in loops.
  For Pesgo, also assign X[subset, point]. For Pe3do, also Z.
  Best for: <10,000 points, static data, demos.

PATTERN 2 -- FASTCOPY (medium datasets, bulk load)
  Build a float[,] array in your code, then call Y.FastCopyFrom(array).
  Avoids per-element interop overhead. Overloads exist for 1D arrays and
  jagged arrays. Use: pe_query.py methods "PeData.Y" to see all signatures.
  Best for: <250K points.

PATTERN 3 -- USEDATAATLOCATION (large/real-time, zero-copy)
  Points your managed array directly to the native DLL -- no copy at all.
  Call Y.UseDataAtLocation(array, bufferSize). Data stays in your memory.
  CRITICAL: You must keep the array pinned/alive while chart uses it.
  Best for: >250K points, real-time where data changes externally, or when
  multiple charts share the same data array (two charts can point to one array).

PATTERN 4 -- APPENDDATA (streaming/real-time)
  Call Y.AppendData(newValues, amountPerSubset) to push new data.
  Automatically shifts existing data left. Combine with CircularBuffers
  for better performance on large buffers.

PATTERN 5 -- BINDDATA (database/DataReader)
  Call Y.BindData(dataReader, startSubset, startPoint) to load directly
  from ADO.NET DataReader or DataView. Convenient but slower than FastCopy.

PATTERN 6 -- JAGGED DATA (subsets with different point counts)
  When subsets have different point counts, enable JaggedData mode.
  REQUIREMENT: JaggedData requires RenderEngine = Direct2D. Direct3D does
  not support JaggedData.
  
  Setup pattern:
    PeData.JaggedData = true;
    PeData.Subsets = N;
    PeData.Points = 1;  // Recommended practice. On ReinitializeResetImage(),
    // Points auto-adjusts to maximum across all subsets. Setting 1 is safe
    // in case JaggedData gets changed or reset unexpectedly.
  
  Three methods to pass jagged data (same thresholds as Patterns 1-3):
  
  6a -- DIRECT INDEXING (spoon-fed, <10K points per subset):
    PeData.X[subset, point] = value;  // auto-expands per-subset storage
    PeData.Y[subset, point] = value;
    Pre-allocation options to avoid incremental reallocation:
    - Set last element first: PeData.X[0, 11999] = 0; forces allocation
    - Use SetJaggedPointsX(subset, size) / SetJaggedPointsY(subset, size)
    See Example 142.
  
  6b -- COPYFROMJAGGED (block copy, <250K points per subset):
    PeData.X.CopyFromJagged(sourceArray, subsetIndex);
      -- copies full sourceArray.Length into that subset
    PeData.X.CopyFromJagged(sourceArray, subsetIndex, nElements);
      -- copies only nElements from sourceArray (use when array is oversized
        or being reused across subsets with different counts)
    Also: FastCopyFromJagged(source, subset) -- similar, sets subset size
    from source array length.
    See Example 143.
  
  6c -- USEJAGGERDDATAATLOCATION (zero-copy pointer, >250K or shared data):
    PeData.Y.UseJaggedDataAtLocation(localArray, subsetIndex);
    Data stays in your memory -- no copy. Must keep array alive.
    NOTE: Different signature from non-jagged UseDataAtLocation(array, bufferSize).
    The second parameter is subsetIndex, NOT bufferSize.
    See Example 144.

DUPLICATEDATA -- SHARED X/Y/Z ARRAYS ACROSS SUBSETS:
  When all subsets share identical X data (common in Pesgo, Pepso, Pe3do),
  avoid redundant data with:
    PeData.DuplicateDataX = DuplicateData.PointIncrement;
  Then provide X data for only ONE subset (subset 0). The chart reuses it
  for all subsets. Enum values:
    None (0) -- unique data per subset (default)
    PointIncrement (1) -- one array shared across all subsets
    SubsetIncrement (2) -- one array shared across all points
  Also applies to DuplicateDataY and DuplicateDataZ.
  Works with both jagged and non-jagged data modes.
  Supported by: Pesgo, Pepso, Pe3do (not Pego -- Pego has no X data array).

DATA ORGANIZATION:
  SubsetByPoint (default true): Y[subset, point] -- standard layout.
  SubsetByPoint = false: Y[point, subset] -- transposed, sometimes easier
  for row-oriented data sources.

NULL DATA HANDLING:
  See dedicated pe-nulldata knowledge file for full coverage.
  Key points: Default NullDataValue=0 (zeros are null by default),
  NullDataGaps=false by default (lines bridge over nulls),
  use Filter2D.Disable when data has scattered nulls.

PEGO VS PESGO X-AXIS DATA:
  Pego: No X data array. X-axis is sequential integers. Category labels via
  PeString.PointLabels[i]. Date mode: set DateTimeMode + DeltaX for uniform
  time steps, or DeltasX[] for variable steps.
  Pesgo: Requires PeData.X[subset, point] with actual numeric values.
  Supports irregular spacing, multiple X arrays per subset, true XY scatter.

REFRESHING AFTER DATA CHANGES:
  PeFunction.ReinitializeResetImage() -- call after data changes.
  For real-time, this is called in the timer tick after AppendData.
  For one-time load, call once after all data is set.