Add bar series timeline synchronization method

Author: Mariusz Bernacki

chartsy-core/src/main/java/one/chartsy/Candle.java

@@ -98,6 +98,10 @@ static Candle of(long time, double open, double high, double low, double close,
         return SimpleCandle.of(time, open, high, low, close, volume, count);
     }
 
+    static Candle of(LocalDateTime dateTime, double price) {
+        return of(Chronological.toEpochMicros(dateTime), price);
+    }
+
     static Candle of(LocalDateTime dateTime, double open, double high, double low, double close, double volume) {
         return of(Chronological.toEpochMicros(dateTime), open, high, low, close, volume);
     }

chartsy-core/src/main/java/one/chartsy/data/CandleSeriesSupport.java

@@ -5,9 +5,19 @@
 package one.chartsy.data;
 
 import one.chartsy.Candle;
+import one.chartsy.SymbolResource;
+import one.chartsy.data.packed.PackedCandleSeries;
+import one.chartsy.data.packed.PackedDataset;
+import one.chartsy.time.AbstractTimeline;
 import one.chartsy.time.Chronological;
+import one.chartsy.time.Timeline;
 
 import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Iterator;
+import java.util.List;
+import java.util.function.Consumer;
 
 /**
  * This class provides utility methods for working with candle series data.
@@ -55,5 +65,99 @@ public static <E extends Candle> Dataset<E> getBarsBefore(Series<? extends E> ba
 		return dataset;
 	}
 
+	/**
+	 * Computes a unified timeline of the given series.
+	 *
+	 * @param seriesCollection the collection of series
+	 * @return a unified timeline
+	 */
+	public static Timeline getUnifiedTimeline(Collection<? extends Series<? extends Chronological>> seriesCollection) {
+		var order = Chronological.Order.REVERSE_CHRONOLOGICAL;
+		var times = seriesCollection.stream()
+				.mapMulti((Series<? extends Chronological> series, Consumer<Chronological> result) -> series.forEach(result))
+				.sorted(order.comparator())
+				.distinct()
+				.toList();
+
+		return new AbstractTimeline(order) {
+			@Override public int length() { return times.size(); }
+			@Override public long getTimeAt(int x) { return times.get(x).getTime(); }
+		};
+	}
+
+	/**
+	 * Synchronizes the timelines of multiple candle series to a common timeline. Missing
+	 * data points in the original series are filled with candles having the previous
+	 * candle's closing price and zero volume.
+	 *
+	 * @param seriesCollection a collection of candle series to synchronize
+	 * @return a new collection of candle series with synchronized timelines
+	 */
+	public static <E extends Candle> List<Series<Candle>> synchronizeTimelines(Collection<? extends Series<? extends E>> seriesCollection) {
+		Timeline timeline = getUnifiedTimeline(seriesCollection);
+
+		return seriesCollection.stream()
+				.map(series -> synchronizeTimeline(series, timeline))
+				.toList();
+	}
+
+	/**
+	 * Synchronizes the timeline of a given candle series with a provided desired timeline.
+	 * If no candle exists for a particular timestamp in the unified timeline, a new candle
+	 * is created with the previous candle's closing price and zero volume.
+	 *
+	 * @param series    the candle series to synchronize
+	 * @param timeline  the timeline to synchronize the series with
+	 * @return a new candle series with the desired timeline
+	 * @throws AssertionError if the series cannot be aligned, for example if it contains
+	 * timestamps which doesn't exist in the {@code timeline}
+	 */
+	public static Series<Candle> synchronizeTimeline(Series<? extends Candle> series, Timeline timeline) {
+		Iterator<? extends Candle> iter = series.iterator();
+		if (iter.hasNext()) {
+			Candle curr = iter.next(), prev = null;
+			int timeIndex = timeline.getTimeLocation(curr.getTime());
+			if (timeIndex < 0) {
+				timeIndex = -timeIndex - 1;
+			}
+			List<Candle> bars = new ArrayList<>(timeIndex + 1);
+
+			// Iterate through the timeline
+			for (; timeIndex >= 0; timeIndex--) {
+				long time = timeline.getTimeAt(timeIndex);
+
+				if (curr.getTime() > time && prev != null) {
+					bars.add(Candle.of(time, prev.close()));
+				}
+				else if (curr.getTime() == time) {
+					bars.add(curr);
+					if (iter.hasNext()) {
+						prev = curr;
+						curr = iter.next();
+					} else if (curr != MAX) {
+						prev = curr;
+						curr = MAX;
+					}
+				}
+				else
+					throw new AssertionError("Cannot synchronize with this Timeline");
+			}
+			return createSeries(series, bars, timeline);
+		}
+		return createSeries(series, List.of(), timeline);
+	}
+
+	@SuppressWarnings("unchecked")
+	private static PackedCandleSeries createSeries(Series<? extends Candle> series, List<Candle> bars, Timeline timeline) {
+		return new PackedCandleSeries((SymbolResource<Candle>) series.getResource(), PackedDataset.of(bars, true)) {
+			@Override
+			public Timeline getTimeline() {
+				return timeline;
+			}
+		};
+	}
+
+	private static final Candle MAX = Candle.of(Long.MAX_VALUE, 0);
+
 	private CandleSeriesSupport() {} // cannot instantiate
 }

chartsy-core/src/main/java/one/chartsy/data/ChronologicalDatasetTimeline.java

@@ -8,16 +8,10 @@
 public class ChronologicalDatasetTimeline extends AbstractTimeline {
 
     private final ChronologicalDataset data;
-    private final Chronological.Order order;
 
     public ChronologicalDatasetTimeline(ChronologicalDataset data, Chronological.Order order) {
+        super(order);
         this.data = data;
-        this.order = order;
-    }
-
-    @Override
-    public final Chronological.Order getOrder() {
-        return order;
     }
 
     @Override

chartsy-core/src/main/java/one/chartsy/data/packed/PackedSeries.java

@@ -77,7 +77,7 @@ public E next() {
     }
 
     @Override
-    public final Timeline getTimeline() {
+    public Timeline getTimeline() {
         return this;
     }
 

chartsy-core/src/main/java/one/chartsy/time/AbstractTimeline.java

@@ -6,6 +6,18 @@
 
 public abstract class AbstractTimeline implements Timeline {
 
+    private final Chronological.Order order;
+
+    protected AbstractTimeline(Chronological.Order order) {
+        this.order = order;
+    }
+
+
+    @Override
+    public final Chronological.Order getOrder() {
+        return order;
+    }
+
     @Override
     public int getTimeLocation(long time) {
         if (getOrder().isReversed())

chartsy-core/src/test/java/one/chartsy/data/CandleSeriesSupportTest.java

@@ -0,0 +1,64 @@
+package one.chartsy.data;
+
+import one.chartsy.Candle;
+import one.chartsy.SymbolResource;
+import one.chartsy.TimeFrame;
+import org.junit.jupiter.api.Test;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+class CandleSeriesSupportTest {
+
+	static final SymbolResource<Candle> TEST_SYMBOL = SymbolResource.of("TEST_SYMBOL", TimeFrame.Period.DAILY);
+
+	@Test
+	void synchronizeTimelines() {
+		// Create sample candle series with different timelines
+		Series<Candle> series1 = seriesOf(
+				candle(LocalDate.of(2023, 11, 1)),
+				candle(LocalDate.of(2023, 11, 2)),
+				candle(LocalDate.of(2023, 11, 4))
+		);
+		Series<Candle> series2 = seriesOf(
+				candle(LocalDate.of(2023, 11, 2)),
+				candle(LocalDate.of(2023, 11, 3))
+		);
+
+		// Synchronize the timelines
+		List<Series<Candle>> resultSeries = CandleSeriesSupport.synchronizeTimelines(List.of(series1, series2));
+
+		// Verify the results
+		assertEquals(2, resultSeries.size());
+
+		// Check series 1
+		Series<Candle> syncSeries1 = resultSeries.getFirst();
+		assertEquals(4, syncSeries1.length());
+		assertEquals(candle(LocalDate.of(2023, 11, 1)), syncSeries1.get(3));
+		assertEquals(candle(LocalDate.of(2023, 11, 2)), syncSeries1.get(2));
+		assertEquals(Candle.of(LocalDateTime.of(2023, 11, 3, 0, 0), series1.get(1).close()), syncSeries1.get(1)); // Filled candle
+		assertEquals(candle(LocalDate.of(2023, 11, 4)), syncSeries1.get(0));
+
+		// Check series 2
+		Series<Candle> syncSeries2 = resultSeries.get(1);
+		assertEquals(3, syncSeries2.length());
+		assertEquals(candle(LocalDate.of(2023, 11, 2)), syncSeries2.get(2));
+		assertEquals(candle(LocalDate.of(2023, 11, 3)), syncSeries2.get(1));
+		assertEquals(Candle.of(LocalDateTime.of(2023, 11, 4, 0, 0), series2.get(0).close()), syncSeries2.get(0)); // Filled candle
+
+		// Verify that the series share the same Timeline
+		assertSame(syncSeries1.getTimeline(), syncSeries2.getTimeline());
+	}
+
+	static Series<Candle> seriesOf(Candle... cs) {
+		return CandleSeries.of(TEST_SYMBOL, List.of(cs));
+	}
+
+	static Candle candle(LocalDate dateTime) {
+		var close = dateTime.getDayOfMonth();
+		return Candle.of(dateTime.atStartOfDay(), 10, 31, 1, close, 100);
+	}
+}