musa-dsl 0.30.2 → 0.41.0

data/lib/musa-dsl/datasets/p.rb

@@ -5,9 +5,113 @@ require_relative '../series'
 require_relative '../sequencer'
 
 module Musa::Datasets
+  # Point series: sequential points in time with durations.
+  #
+  # P (Point series) represents sequential points in time as arrays with alternating
+  # structure: [point, duration, point, duration, point, ...].
+  #
+  # ## Structure
+  #
+  # The array alternates between points and durations:
+  #
+  #     [point₀, duration₀, point₁, duration₁, point₂]
+  #
+  # - **Points** (odd positions): Any data (numbers, hashes, complex structures, etc.)
+  # - **Durations** (even positions): Time between points (numbers)
+  # - **Last point**: Final point has no duration (sequence end)
+  #
+  # This compact format efficiently represents timed sequences without
+  # repeating time information.
+  #
+  # ## Conversions
+  #
+  # P can be converted to two different representations:
+  #
+  # ### 1. Timed Series (to_timed_serie)
+  #
+  # Converts to series of {AbsTimed} events with absolute time and value.
+  # Each value gets a timestamp based on cumulative durations.
+  #
+  #     p = [60, 4, 64, 8, 67].extend(P)
+  #     serie = p.to_timed_serie
+  #     # Yields:
+  #     # { time: 0, value: 60 }
+  #     # { time: 1.0, value: 64 }  (4 * base_duration = 1.0)
+  #     # { time: 3.0, value: 67 }  (8 * base_duration = 2.0)
+  #
+  # ### 2. Parameter Segment Series (to_ps_serie)
+  #
+  # Converts to series of {PS} (Parameter Segment) objects representing
+  # continuous changes between consecutive points.
+  #
+  #     p = [60, 4, 64, 8, 67].extend(P)
+  #     serie = p.to_ps_serie
+  #     # Yields PS objects:
+  #     # { from: 60, to: 64, duration: 1.0, right_open: true }
+  #     # { from: 64, to: 67, duration: 2.0, right_open: false }
+  #
+  # ## Point Transformation
+  #
+  # The {#map} method transforms points while preserving durations:
+  #
+  #     p = [60, 4, 64, 8, 67].extend(P)
+  #     p2 = p.map { |point| point + 12 }
+  #     # => [72, 4, 76, 8, 79]
+  #     # Durations unchanged, points transformed
+  #
+  # @example Basic point series (MIDI pitches)
+  #   # MIDI pitches with durations in quarter notes
+  #   p = [60, 4, 64, 8, 67].extend(Musa::Datasets::P)
+  #   # 60 (C4) for 4 quarters → 64 (E4) for 8 quarters → 67 (G4)
+  #
+  # @example Hash points (complex data structures)
+  #   p = [
+  #     { pitch: 60, velocity: 64 }, 4,
+  #     { pitch: 64, velocity: 80 }, 8,
+  #     { pitch: 67, velocity: 64 }
+  #   ].extend(Musa::Datasets::P)
+  #
+  # @example Convert to timed serie
+  #   p = [60, 4, 64, 8, 67].extend(Musa::Datasets::P)
+  #   serie = p.to_timed_serie(base_duration: 1/4r)
+  #   # base_duration: quarter note = 1/4 beat
+  #
+  # @example Start at specific time
+  #   serie = p.to_timed_serie(time_start: 10)
+  #   # First event at time 10
+  #
+  # @example Start time from component
+  #   p = [{ time: 100, pitch: 60 }, 4, { time: 200, pitch: 64 }].extend(P)
+  #   serie = p.to_timed_serie(time_start_component: :time)
+  #   # First event at time 100 (from first point's :time)
+  #
+  # @example Transform points
+  #   p = [60, 4, 64, 8, 67].extend(Musa::Datasets::P)
+  #   p2 = p.map { |point| point + 12 }
+  #   # Transform each point (e.g., transpose pitches up one octave)
+  #
+  # @see PS Parameter segments
+  # @see AbsTimed Timed events
+  # @see Dataset Parent dataset module
   module P
     include Dataset
 
+    # Converts to series of parameter segments.
+    #
+    # Creates {PS} objects representing continuous changes from each point
+    # to the next. Useful for glissandi, parameter sweeps, or any continuous
+    # interpolation between points.
+    #
+    # @param base_duration [Rational] duration unit multiplier (default: 1/4r)
+    #   Durations in P are multiplied by this to get actual time
+    #
+    # @return [Musa::Series::Serie<PS>] series of parameter segments
+    #
+    # @example Create parameter segments
+    #   p = [60, 4, 64, 8, 67].extend(P)
+    #   serie = p.to_ps_serie
+    #   segment1 = serie.next_value
+    #   # => { from: 60, to: 64, duration: 1.0, right_open: true }
     def to_ps_serie(base_duration: nil)
       base_duration ||= 1/4r # TODO review incoherence between neumalang 1/4r base duration for quarter notes and general 1r size of bar
 
@@ -22,6 +126,33 @@ module Musa::Datasets
       end
     end
 
+    # Converts to series of timed events (AbsTimed).
+    #
+    # Creates series yielding {AbsTimed} events with absolute time and value.
+    # Each value is emitted at its calculated time point based on cumulative durations.
+    #
+    # @param time_start [Numeric] starting time offset (default: 0)
+    # @param time_start_component [Symbol] key in first value to use as time offset
+    #   If provided, adds first[time_start_component] to time_start
+    # @param base_duration [Rational] duration unit multiplier (default: 1/4r)
+    #
+    # @return [PtoTimedSerie] series of timed events
+    #
+    # @example Basic timed serie
+    #   p = [60, 4, 64, 8, 67].extend(P)
+    #   serie = p.to_timed_serie
+    #   serie.next_value  # => { time: 0, value: 60 }
+    #   serie.next_value  # => { time: 1.0, value: 64 }
+    #   serie.next_value  # => { time: 3.0, value: 67 }
+    #
+    # @example Custom start time
+    #   serie = p.to_timed_serie(time_start: 10)
+    #   # First event at time 10
+    #
+    # @example Start time from component
+    #   p = [{ time: 100, pitch: 60 }, 4, { pitch: 64 }].extend(P)
+    #   serie = p.to_timed_serie(time_start_component: :time)
+    #   # First event at time 100
     def to_timed_serie(time_start: nil, time_start_component: nil, base_duration: nil)
       time_start ||= 0r
       time_start += self.first[time_start_component] if time_start_component
@@ -31,11 +162,30 @@ module Musa::Datasets
       PtoTimedSerie.new(self, base_duration, time_start)
     end
 
+    # Maps over points, preserving durations.
+    #
+    # Transforms each point (odd positions) using the block while
+    # keeping durations (even positions) unchanged.
+    #
+    # @yieldparam point [Object] each point in the series
+    # @yieldreturn [Object] transformed point
+    #
+    # @return [P] new P with transformed points
+    #
+    # @example Transform points (e.g., transpose pitches)
+    #   p = [60, 4, 64, 8, 67].extend(P)
+    #   p.map { |point| point + 12 }
+    #   # => [72, 4, 76, 8, 79]
+    #
+    # @example Transform hash points
+    #   p = [{ pitch: 60 }, 4, { pitch: 64 }].extend(P)
+    #   p.map { |point| point.merge(velocity: 80) }
+    #   # Adds velocity to each point
     def map(&block)
       i = 0
       clone.map! do |element|
-        # Process with block only the values (values are the alternating elements because P
-        # structure is <value> <duration> <value> <duration> <value>)
+        # Process with block only the points (points are the alternating elements because P
+        # structure is <point> <duration> <point> <duration> <point>)
         #
         if (i += 1) % 2 == 1
           block.call(element)
@@ -45,9 +195,26 @@ module Musa::Datasets
       end
     end
 
+    # Series adapter for P to AbsTimed conversion.
+    #
+    # PtoTimedSerie is a {Musa::Series::Serie} that converts a {P} (point series)
+    # into a series of {AbsTimed} events. It reads the alternating point/duration
+    # structure and emits timed events.
+    #
+    # This class is created by {P#to_timed_serie} and should not be instantiated
+    # directly.
+    #
+    # @api private
     class PtoTimedSerie
       include Musa::Series::Serie.base
 
+      # Creates new timed serie adapter.
+      #
+      # @param origin [P] source point series
+      # @param base_duration [Rational] duration unit multiplier
+      # @param time_start [Numeric] starting time offset
+      #
+      # @api private
       def initialize(origin, base_duration, time_start)
         @origin = origin
         @base_duration = base_duration
@@ -58,8 +225,16 @@ module Musa::Datasets
         mark_as_prototype!
       end
 
+      # Source point series.
+      # @return [P]
       attr_accessor :origin
+
+      # Duration unit multiplier.
+      # @return [Rational]
       attr_accessor :base_duration
+
+      # Starting time offset.
+      # @return [Numeric]
       attr_accessor :time_start
 
       private def _init

data/lib/musa-dsl/datasets/packed-v.rb

@@ -2,9 +2,100 @@ require_relative 'e'
 require_relative 'v'
 
 module Musa::Datasets
+  # Hash-based dataset with array conversion.
+  #
+  # PackedV (Packed Value) represents datasets stored as hashes (named key-value pairs).
+  # Extends {AbsI} for absolute indexed events.
+  #
+  # ## Purpose
+  #
+  # PackedV provides named key-value storage for musical data and conversion
+  # to indexed arrays ({V}). This is useful for:
+  #
+  # - Semantic naming of values (pitch, duration, velocity)
+  # - Sparse data (only store non-default values)
+  # - Converting between hash and array representations
+  # - Serialization to readable formats
+  #
+  # ## Conversion to V
+  #
+  # The {#to_V} method converts hashes to arrays using a mapper that
+  # defines the correspondence between hash keys and array positions.
+  #
+  # ### Array Mapper
+  #
+  # Array mapper defines the order of keys in resulting array.
+  # Position i contains value for key mapper[i].
+  #
+  #     pv = { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PackedV)
+  #     v = pv.to_V([:pitch, :duration, :velocity])
+  #     # => [60, 1.0, nil]
+  #     # velocity missing, becomes nil
+  #
+  # - Missing keys become `nil` in array
+  #
+  # ### Hash Mapper
+  #
+  # Hash mapper defines both key order (keys) and default values (values).
+  # Position i contains value for key mapper.keys[i], using mapper.values[i]
+  # as default if key is missing or value is nil.
+  #
+  #     pv = { pitch: 60 }.extend(Musa::Datasets::PackedV)
+  #     v = pv.to_V({ pitch: 60, duration: 1.0, velocity: 64 })
+  #     # => [60, 1.0, 64]
+  #     # duration and velocity use defaults
+  #
+  # Defaults fill in missing or nil values.
+  #
+  # @example Basic hash to array conversion
+  #   pv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V([:pitch, :duration, :velocity])
+  #   # => [60, 1.0, 64]
+  #
+  # @example Missing keys become nil (array mapper)
+  #   pv = { a: 1, c: 3 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V([:c, :b, :a])
+  #   # => [3, nil, 1]
+  #   # b missing, becomes nil
+  #
+  # @example Hash mapper with defaults
+  #   pv = { a: 1, b: nil, c: 3 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V({ c: 100, b: 200, a: 300, d: 400 })
+  #   # => [3, 200, 1, 400]
+  #   # b nil → uses default 200
+  #   # d missing → uses default 400
+  #
+  # @example Partial mapper (fewer keys in mapper)
+  #   pv = { a: 1, b: 2, c: 3 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V([:c, :b])
+  #   # => [3, 2]
+  #   # Only c and b extracted
+  #
+  # @example Key order matters
+  #   pv = { a: 1, b: 2, c: 3 }.extend(Musa::Datasets::PackedV)
+  #   v = pv.to_V([:c, :b, :a])
+  #   # => [3, 2, 1]
+  #
+  # @see V Array-based dataset (inverse)
+  # @see AbsI Parent absolute indexed module
   module PackedV
     include AbsI
 
+    # Converts packed hash to array (V).
+    #
+    # @param mapper [Array<Symbol>, Hash{Symbol => Object}] key mapping
+    #   - Array: maps keys to indices (order matters)
+    #   - Hash: maps keys (keys) to indices with defaults (values)
+    #
+    # @return [V] array dataset
+    #
+    # @raise [ArgumentError] if mapper is not Array or Hash
+    #
+    # @example Array mapper
+    #   pv.to_V([:pitch, :duration, :velocity])
+    #
+    # @example Hash mapper with defaults
+    #   pv.to_V({ pitch: 60, duration: 1.0, velocity: 64 })
     def to_V(mapper)
       case mapper
       when Hash

data/lib/musa-dsl/datasets/pdv.rb

@@ -4,15 +4,150 @@ require_relative 'gdv'
 require_relative 'helper'
 
 module Musa::Datasets
+  # MIDI-style musical events with absolute pitches.
+  #
+  # PDV (Pitch/Duration/Velocity) represents musical events using MIDI-like
+  # absolute pitch numbers. Extends {AbsD} for duration support.
+  #
+  # ## Purpose
+  #
+  # PDV is the MIDI representation layer of the dataset framework:
+  #
+  # - Uses absolute MIDI pitch numbers (0-127)
+  # - Uses MIDI velocity values (0-127)
+  # - Direct mapping to MIDI messages
+  # - Machine-oriented (not human-readable)
+  #
+  # Contrast with {GDV} which uses score notation (scale degrees, dynamics).
+  #
+  # ## Natural Keys
+  #
+  # - **:pitch**: MIDI pitch number (0-127) or :silence for rests
+  # - **:velocity**: MIDI velocity (0-127)
+  # - **:duration**: Event duration (from {AbsD})
+  # - **:note_duration**, **:forward_duration**: Additional duration keys (from {AbsD})
+  #
+  # ## Conversions
+  #
+  # ### To GDV (Score Notation)
+  #
+  # Converts MIDI pitches to scale degrees using a scale reference:
+  #
+  #     pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(PDV)
+  #     scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #     gdv = pdv.to_gdv(scale)
+  #     # => { grade: 0, octave: 0, duration: 1.0, velocity: 0 }
+  #
+  # - **Pitch → Grade**: Finds closest scale degree
+  # - **Chromatic notes**: Represented as grade + sharps
+  # - **Velocity**: Maps MIDI 0-127 to dynamics -5 to +4 (ppp to fff)
+  #
+  # ### Velocity Mapping
+  #
+  # MIDI velocities are mapped to musical dynamics:
+  #
+  #     MIDI 1-1    → velocity -5 (ppp)
+  #     MIDI 2-8    → velocity -4 (pp)
+  #     MIDI 9-16   → velocity -3 (p)
+  #     MIDI 17-33  → velocity -2 (mp)
+  #     MIDI 34-48  → velocity -1 (mf-)
+  #     MIDI 49-64  → velocity  0 (mf)
+  #     MIDI 65-80  → velocity +1 (f)
+  #     MIDI 81-96  → velocity +2 (ff)
+  #     MIDI 97-112 → velocity +3 (fff-)
+  #     MIDI 113-127 → velocity +4 (fff)
+  #
+  # ## Base Duration
+  #
+  # The `base_duration` attribute defines the unit for duration values,
+  # typically 1/4r (quarter note).
+  #
+  # @example Basic MIDI event
+  #   pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(Musa::Datasets::PDV)
+  #   pdv.base_duration = 1/4r
+  #   # C4 (middle C) for 1 beat at mf dynamics
+  #
+  # @example Silence (rest)
+  #   pdv = { pitch: :silence, duration: 1.0 }.extend(PDV)
+  #   # Rest for 1 beat
+  #
+  # @example With articulation
+  #   pdv = {
+  #     pitch: 64,
+  #     duration: 1.0,
+  #     note_duration: 0.5,  # Staccato
+  #     velocity: 80
+  #   }.extend(PDV)
+  #
+  # @example Convert to score notation
+  #   pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(PDV)
+  #   pdv.base_duration = 1/4r
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdv = pdv.to_gdv(scale)
+  #   # => { grade: 0, octave: 0, duration: 1.0, velocity: 0 }
+  #
+  # @example Chromatic pitch
+  #   pdv = { pitch: 61, duration: 1.0, velocity: 64 }.extend(PDV)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdv = pdv.to_gdv(scale)
+  #   # => { grade: 0, octave: 0, sharps: 1, duration: 1.0, velocity: 0 }
+  #   # C# represented as C (grade 0) + 1 sharp
+  #
+  # @example Preserve additional keys
+  #   pdv = {
+  #     pitch: 60,
+  #     duration: 1.0,
+  #     velocity: 64,
+  #     custom_key: :value
+  #   }.extend(PDV)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdv = pdv.to_gdv(scale)
+  #   # custom_key copied to GDV (not a natural key)
+  #
+  # @see GDV Score-style representation
+  # @see AbsD Absolute duration events
+  # @see Helper String formatting utilities
   module PDV
     include AbsD
 
     include Helper
 
+    # Natural keys for MIDI events.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys + [:pitch, :velocity]).freeze
 
+    # Base duration for time calculations.
+    # @return [Rational]
     attr_accessor :base_duration
 
+    # Converts to GDV (score notation).
+    #
+    # Translates MIDI representation to score notation using a scale:
+    # - MIDI pitch → scale degree (grade + octave + sharps)
+    # - MIDI velocity → dynamics (-5 to +4)
+    # - Duration values copied
+    # - Additional keys preserved
+    #
+    # @param scale [Musa::Scales::Scale] reference scale for pitch conversion
+    #
+    # @return [GDV] score notation dataset
+    #
+    # @example Basic conversion
+    #   pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(PDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   gdv = pdv.to_gdv(scale)
+    #
+    # @example Chromatic note
+    #   pdv = { pitch: 61, duration: 1.0 }.extend(PDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   gdv = pdv.to_gdv(scale)
+    #   # => { grade: 0, octave: 0, sharps: 1, duration: 1.0 }
+    #
+    # @example Silence
+    #   pdv = { pitch: :silence, duration: 1.0 }.extend(PDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   gdv = pdv.to_gdv(scale)
+    #   # => { grade: :silence, duration: 1.0 }
     def to_gdv(scale)
       gdv = {}.extend GDV
       gdv.base_duration = @base_duration
@@ -39,7 +174,7 @@ module Musa::Datasets
       if self[:velocity]
         # ppp = 16 ... fff = 127
         # TODO create a customizable MIDI velocity to score dynamics bidirectional conversor
-        gdv[:velocity] = [1..1, 2..8, 9..16, 17..33, 34..49, 49..64, 65..80, 81..96, 97..112, 113..127].index { |r| r.cover? self[:velocity] } - 5
+        gdv[:velocity] = [1..1, 2..8, 9..16, 17..33, 34..48, 49..64, 65..80, 81..96, 97..112, 113..127].index { |r| r.cover? self[:velocity] } - 5
       end
 
       (keys - NaturalKeys).each { |k| gdv[k] = self[k] }

data/lib/musa-dsl/datasets/ps.rb

@@ -4,31 +4,161 @@ require_relative 'score'
 require_relative '../sequencer'
 
 module Musa::Datasets
+  # Parameter segments for continuous changes between multidimensional points.
+  #
+  # PS (Parameter Segment) represents a continuous change from one point
+  # to another over a duration. Extends {AbsD} for duration support.
+  #
+  # ## Purpose
+  #
+  # PS is used to represent:
+  #
+  # - **Glissandi**: Continuous pitch slides (portamento)
+  # - **Parameter sweeps**: Gradual changes in any sonic parameter
+  # - **Interpolations**: Smooth transitions between multidimensional states
+  #
+  # Unlike discrete events that jump from one value to another, PS represents
+  # the continuous path between values.
+  #
+  # ## Natural Keys
+  #
+  # - **:from**: Starting value (number, array, or hash)
+  # - **:to**: Ending value (must match :from type and structure)
+  # - **:right_open**: Whether endpoint is included (true = open interval)
+  # - **:duration**: Duration of the change (from {AbsD})
+  # - **:note_duration**, **:forward_duration**: Additional duration keys (from {AbsD})
+  #
+  # ## Value Types
+  #
+  # ### Single Values
+  #
+  #     { from: 60, to: 72, duration: 1.0 }
+  #     # Single value glissando
+  #
+  # ### Arrays (parallel interpolation)
+  #
+  #     { from: [60, 64], to: [72, 76], duration: 1.0 }
+  #     # Both values interpolate in parallel
+  #     # Arrays must be same size
+  #
+  # ### Hashes (named parameters)
+  #
+  #     { from: { pitch: 60, velocity: 64 },
+  #       to: { pitch: 72, velocity: 80 },
+  #       duration: 1.0 }
+  #     # Multiple parameters interpolate together
+  #     # Hashes must have same keys
+  #
+  # ## Right Open Intervals
+  #
+  # The :right_open flag determines if the ending value is reached:
+  #
+  # - **false** (closed): Interpolation reaches :to value
+  # - **true** (open): Interpolation stops just before :to value
+  #
+  # This is important for consecutive segments where you don't want
+  # discontinuities at the boundaries.
+  #
+  # @example Basic parameter segment (pitch glissando)
+  #   ps = { from: 60, to: 72, duration: 2.0 }.extend(Musa::Datasets::PS)
+  #   # Continuous slide from C4 to C5 over 2 beats
+  #
+  # @example Parallel interpolation (multidimensional)
+  #   ps = {
+  #     from: [60, 64],  # C4 and E4
+  #     to: [72, 76],    # C5 and E5
+  #     duration: 1.0
+  #   }.extend(PS)
+  #   # Both parameters move in parallel
+  #
+  # @example Multiple parameters (sonic gesture)
+  #   ps = {
+  #     from: { pitch: 60, velocity: 64, pan: -1.0 },
+  #     to: { pitch: 72, velocity: 80, pan: 1.0 },
+  #     duration: 2.0
+  #   }.extend(PS)
+  #   # Pitch, velocity, and pan all change smoothly
+  #
+  # @example Right open interval
+  #   ps1 = { from: 60, to: 64, duration: 1.0, right_open: true }.extend(PS)
+  #   ps2 = { from: 64, to: 67, duration: 1.0, right_open: false }.extend(PS)
+  #   # ps1 stops just before 64, ps2 starts at 64 - no discontinuity
+  #
+  # @example Created from P point series
+  #   p = [60, 4, 64, 8, 67].extend(P)
+  #   serie = p.to_ps_serie
+  #   ps1 = serie.next_value
+  #   # => { from: 60, to: 64, duration: 1.0, right_open: true }
+  #
+  # @see AbsD Parent absolute duration module
+  # @see P Point series (source of PS)
+  # @see Helper String formatting utilities
   module PS
     include AbsD
 
     include Helper
 
+    # Natural keys including segment endpoints.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys + [:from, :to, :right_open]).freeze
 
+    # Base duration for time calculations.
+    # @return [Rational]
     attr_accessor :base_duration
 
+    # Converts to Neuma notation string.
+    #
+    # @return [String] Neuma notation
+    # @todo Not yet implemented
     def to_neuma
-      # TODO ???????
+      raise NotImplementedError, 'PS to_neuma conversion is not yet implemented'
     end
 
+    # Converts to PDV (Pitch/Duration/Velocity).
+    #
+    # @return [PDV] PDV dataset
+    # @todo Not yet implemented
     def to_pdv
-      # TODO ??????
+      raise NotImplementedError, 'PS to_pdv conversion is not yet implemented'
     end
 
+    # Converts to GDV (Grade/Duration/Velocity).
+    #
+    # @return [GDV] GDV dataset
+    # @todo Not yet implemented
     def to_gdv
-      # TODO ?????
+      raise NotImplementedError, 'PS to_gdv conversion is not yet implemented'
     end
 
+    # Converts to absolute indexed format.
+    #
+    # @return [AbsI] indexed dataset
+    # @todo Not yet implemented
     def to_absI
-      # TODO ?????
+      raise NotImplementedError, 'PS to_absI conversion is not yet implemented'
     end
 
+    # Validates PS structure.
+    #
+    # Checks that:
+    # - :from and :to have compatible types
+    # - Arrays have same size
+    # - Hashes have same keys
+    # - Duration is positive numeric
+    #
+    # @return [Boolean] true if valid
+    #
+    # @example Valid array segment
+    #   ps = { from: [60, 64], to: [72, 76], duration: 1.0 }.extend(PS)
+    #   ps.valid?  # => true
+    #
+    # @example Invalid - mismatched array sizes
+    #   ps = { from: [60, 64], to: [72], duration: 1.0 }.extend(PS)
+    #   ps.valid?  # => false
+    #
+    # @example Invalid - mismatched hash keys
+    #   ps = { from: { a: 1 }, to: { b: 2 }, duration: 1.0 }.extend(PS)
+    #   ps.valid?  # => false
     def valid?
       case self[:from]
       when Array