Add momentum indicator ROC (#277)

# Describe Request

Add momentum indicator ROC

Fixed #57 

# Change Type

What is the type of this change.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a Rate of Change (ROC) indicator with a configurable period
(default: 9), streaming computation and an automatic warm-up (idle)
period before outputs appear.
* ROC exposes a readable string representation showing the configured
period.

* **Tests**
* Added unit tests validating ROC on simple sequences and CSV reference
data.
* Tests cover rounding/alignment, default-period fallback, and string
representation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: hwde

trend/roc.go

@@ -0,0 +1,72 @@
+// Copyright (c) 2021-2024 Onur Cinar.
+// The source code is provided under GNU AGPLv3 License.
+// https://github.com/cinar/indicator
+
+package trend
+
+import (
+	"fmt"
+
+	"github.com/cinar/indicator/v2/helper"
+)
+
+const (
+	// DefaultRocPeriod is the default ROC period.
+	DefaultRocPeriod = 9
+)
+
+// Roc represents the configuration parameters for calculating the Rate Of Change (ROC) indicator.
+//
+//	ROC = (Current Price - Price n periods ago) / Price n periods ago
+type Roc[T helper.Float] struct {
+	// Time period.
+	Period int
+}
+
+// NewRoc function initializes a new Roc instance with the default parameters.
+func NewRoc[T helper.Float]() *Roc[T] {
+	return NewRocWithPeriod[T](DefaultRocPeriod)
+}
+
+// NewRocWithPeriod function initializes a new Roc instance with the given parameters.
+func NewRocWithPeriod[T helper.Float](period int) *Roc[T] {
+	if period <= 0 {
+		period = DefaultRocPeriod
+	}
+	return &Roc[T]{
+		Period: period,
+	}
+}
+
+// Compute function takes a channel of numbers and computes the ROC and the signal line.
+func (r *Roc[T]) Compute(values <-chan T) <-chan T {
+	window := helper.NewRing[T](r.Period)
+
+	rocs := helper.Map(values, func(value T) T {
+		var result T
+
+		if window.IsFull() {
+			p, ok := window.Get()
+			if ok && p != 0 {
+				result = (value - p) / p
+			}
+		}
+		window.Put(value)
+
+		return result
+	})
+
+	rocs = helper.Skip(rocs, r.IdlePeriod())
+
+	return rocs
+}
+
+// IdlePeriod is the initial period that ROC won't yield any results.
+func (r *Roc[T]) IdlePeriod() int {
+	return r.Period
+}
+
+// String is the string representation of the ROC.
+func (r *Roc[T]) String() string {
+	return fmt.Sprintf("ROC(%d)", r.Period)
+}

trend/roc_test.go

@@ -0,0 +1,70 @@
+package trend
+
+import (
+	"testing"
+
+	"github.com/cinar/indicator/v2/helper"
+)
+
+func TestRocSimple(t *testing.T) {
+	closing := helper.SliceToChan([]float64{2, 4, 6, 8, 9, 7})
+	expected := helper.SliceToChan([]float64{0, 0, 0, (8 - 2) / 2, (9.0 - 4) / 4, (7.0 - 6) / 6})
+
+	roc := NewRoc[float64]()
+	roc.Period = 3
+
+	actual := roc.Compute(closing)
+	expected = helper.Skip(expected, roc.IdlePeriod())
+
+	err := helper.CheckEquals(actual, expected)
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRocTestdata(t *testing.T) {
+	type Data struct {
+		Close float64
+		Roc   float64
+	}
+
+	input, err := helper.ReadFromCsvFile[Data]("testdata/roc.csv", true)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	inputs := helper.Duplicate(input, 2)
+	closing := helper.Map(inputs[0], func(d *Data) float64 { return d.Close })
+	expected := helper.Map(inputs[1], func(d *Data) float64 { return d.Roc })
+
+	roc := NewRoc[float64]()
+
+	actual := roc.Compute(closing)
+	actual = helper.RoundDigits(actual, 2)
+
+	expected = helper.Skip(expected, roc.IdlePeriod())
+
+	err = helper.CheckEquals(actual, expected)
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestRocFallbackPeriod(t *testing.T) {
+	roc := NewRocWithPeriod[float64](-17)
+
+	if roc.Period != DefaultRocPeriod {
+		t.Fatal("expected period to be fallback to default value")
+	}
+}
+
+func TestRocToStringAndIdlePeriod(t *testing.T) {
+	roc := NewRocWithPeriod[float64](0)
+	if roc.IdlePeriod() != DefaultRocPeriod {
+		t.Fatalf("unexpected IdlePeriod: %d", roc.IdlePeriod())
+	}
+	roc.Period = 3
+	if s := roc.String(); s != "ROC(3)" {
+		t.Fatalf("unexpected String(): %s", s)
+	}
+}

trend/testdata/roc.csv

@@ -0,0 +1,21 @@
+Close,Roc
+11045.27,0
+11167.32,0
+11008.61,0
+11151.83,0
+10926.77,0
+10868.12,0
+10520.32,0
+10380.43,0
+10785.14,0
+10748.26,-0.03
+10896.91,-0.02
+10782.95,-0.02
+10620.16,-0.05
+10625.83,-0.03
+10510.95,-0.03
+10444.37,-0.01
+10068.01,-0.03
+10193.39,-0.05
+10066.57,-0.06
+10043.75,-0.08