Add usage examples for reactive operators

apidoc/Bonsai_Reactive_Append.md

@@ -0,0 +1,5 @@
+---
+uid: Bonsai.Reactive.Append
+---
+
+[!include[Append](../articles/reactive-append.md)]

apidoc/Bonsai_Reactive_AsyncSubject.md

@@ -2,4 +2,14 @@
 uid: Bonsai.Reactive.AsyncSubject
 ---
 
-[!include[AsyncSubject](~/articles/subject-async.md)]
+[!include[AsyncSubject](~/articles/subject-async.md)]
+
+### Example
+
+Use `AsyncSubject` to broadcast the last value to any subscriber.
+
+:::workflow
+![AsyncSubject Example](../workflows/reactive-asyncsubject-example.bonsai)
+:::
+
+[!include[SubjectAlternatives](../articles/reactive-subjectalternatives.md)]

apidoc/Bonsai_Reactive_AsyncSubject_1.md

@@ -2,4 +2,14 @@
 uid: Bonsai.Reactive.AsyncSubject`1
 ---
 
-[!include[AsyncSubject](~/articles/subject-async.md)]
+[!include[AsyncSubject](~/articles/subject-async.md)]
+
+### Example
+
+Use `AsyncSubject` to broadcast the last value to any subscriber.
+
+:::workflow
+![AsyncSubject Example](../workflows/reactive-asyncsubject-example.bonsai)
+:::
+
+[!include[SubjectAlternatives](../articles/reactive-subjectalternatives.md)]

apidoc/Bonsai_Reactive_BehaviorSubject.md

@@ -2,4 +2,14 @@
 uid: Bonsai.Reactive.BehaviorSubject
 ---
 
-[!include[BehaviorSubject](~/articles/subject-behavior.md)]
+[!include[BehaviorSubject](~/articles/subject-behavior.md)]
+
+### Example
+
+Use `BehaviorSubject` to broadcast the latest value to any subscriber.
+
+:::workflow
+![BehaviorSubject Example](../workflows/reactive-behaviorsubject-example.bonsai)
+:::
+
+[!include[SubjectAlternatives](../articles/reactive-subjectalternatives.md)]

apidoc/Bonsai_Reactive_BehaviorSubject_1.md

@@ -2,4 +2,14 @@
 uid: Bonsai.Reactive.BehaviorSubject`1
 ---
 
-[!include[BehaviorSubject](~/articles/subject-behavior.md)]
+[!include[BehaviorSubject](~/articles/subject-behavior.md)]
+
+### Example
+
+Use `BehaviorSubject` to broadcast the latest value to any subscriber.
+
+:::workflow
+![BehaviorSubject Example](../workflows/reactive-behaviorsubject-example.bonsai)
+:::
+
+[!include[SubjectAlternatives](../articles/reactive-subjectalternatives.md)]

apidoc/Bonsai_Reactive_CreateTimestamped.md

@@ -0,0 +1,5 @@
+---
+uid: Bonsai.Reactive.CreateTimestamped
+---
+
+[!include[CreateTimestamped](~/articles/reactive-createtimestamped.md)]

apidoc/Bonsai_Reactive_Prepend.md

@@ -0,0 +1,5 @@
+---
+uid: Bonsai.Reactive.Prepend
+---
+
+[!include[Prepend](../articles/reactive-prepend.md)]

apidoc/Bonsai_Reactive_PublishSubject.md

@@ -2,4 +2,14 @@
 uid: Bonsai.Reactive.PublishSubject
 ---
 
-[!include[PublishSubject](~/articles/subject-publish.md)]
+[!include[PublishSubject](~/articles/subject-publish.md)]
+
+### Example
+
+Use `PublishSubject` to broadcast values to any subscriber.
+
+:::workflow
+![PublishSubject Example](../workflows/reactive-publishsubject-example.bonsai)
+:::
+
+[!include[SubjectAlternatives](../articles/reactive-subjectalternatives.md)]

apidoc/Bonsai_Reactive_PublishSubject_1.md

@@ -2,4 +2,14 @@
 uid: Bonsai.Reactive.PublishSubject`1
 ---
 
-[!include[PublishSubject](~/articles/subject-publish.md)]
+[!include[PublishSubject](~/articles/subject-publish.md)]
+
+### Example
+
+Use `PublishSubject` to broadcast values to any subscriber.
+
+:::workflow
+![PublishSubject Example](../workflows/reactive-publishsubject-example.bonsai)
+:::
+
+[!include[SubjectAlternatives](../articles/reactive-subjectalternatives.md)]

apidoc/Bonsai_Reactive_ReplaySubject.md

@@ -2,4 +2,14 @@
 uid: Bonsai.Reactive.ReplaySubject
 ---
 
-[!include[ReplaySubject](~/articles/subject-replay.md)]
+[!include[ReplaySubject](~/articles/subject-replay.md)]
+
+### Example
+
+Use `ReplaySubject` to broadcast all past and future values to any subscriber.
+
+:::workflow
+![ReplaySubject Example](../workflows/reactive-replaysubject-example.bonsai)
+:::
+
+[!include[SubjectAlternatives](../articles/reactive-subjectalternatives.md)]

apidoc/Bonsai_Reactive_ReplaySubject_1.md

@@ -2,4 +2,14 @@
 uid: Bonsai.Reactive.ReplaySubject`1
 ---
 
-[!include[ReplaySubject](~/articles/subject-replay.md)]
+[!include[ReplaySubject](~/articles/subject-replay.md)]
+
+### Example
+
+Use `ReplaySubject` to broadcast all past and future values to any subscriber.
+
+:::workflow
+![ReplaySubject Example](../workflows/reactive-replaysubject-example.bonsai)
+:::
+
+[!include[SubjectAlternatives](../articles/reactive-subjectalternatives.md)]

apidoc/Bonsai_Reactive_ResourceSubject.md

@@ -2,4 +2,8 @@
 uid: Bonsai.Reactive.ResourceSubject
 ---
 
-[!include[ResourceSubject](~/articles/subject-resource.md)]
+[!include[ResourceSubject](~/articles/subject-resource.md)]
+
+### Alternative
+
+`ResourceSubject` is primarily used in niche applications involving device objects. For more typical scenarios, use [`AsyncSubject`](xref:Bonsai.Reactive.AsyncSubject) instead to broadcast the last value to subscribers.

apidoc/Bonsai_Reactive_ResourceSubject_1.md

@@ -2,4 +2,8 @@
 uid: Bonsai.Reactive.ResourceSubject`1
 ---
 
-[!include[ResourceSubject](~/articles/subject-resource.md)]
+[!include[ResourceSubject](~/articles/subject-resource.md)]
+
+### Alternative
+
+`ResourceSubject` is primarily used in niche applications involving device objects. For more typical scenarios, use [`AsyncSubject`](xref:Bonsai.Reactive.AsyncSubject) instead to broadcast the last value to subscribers.

articles/reactive-accumulate.md

@@ -6,3 +6,15 @@ title: Accumulate
 ![Marble diagram](~/images/reactive-accumulate.svg)
 
 The `Accumulate` operator returns the current value of the cumulative sum each time the source sequence emits a notification. The result sequence terminates successfully when the source sequence terminates successfully.
+
+### Example
+
+Use `Accumulate` to continuously update a value by adding up the changes over time.
+
+:::workflow
+![Accumulate Example](../workflows/reactive-accumulate-example.bonsai)
+:::
+
+### Alternative
+
+Use [`Sum`](xref:Bonsai.Reactive.Sum) instead to yield a single accumulated value at the end of a sequence.

articles/reactive-amb.md

@@ -6,3 +6,15 @@ title: Amb
 ![Marble diagram](~/images/reactive-amb.svg)
 
 The `Amb` operator sets up a winner-take-all race condition between all source sequences. The first sequence to emit a notification will gain full control of the output, and all the other sequences will have their subscriptions immediatelly cancelled. `Amb` is most commonly used to ensure only one of many outcomes being evaluated in parallel is propagated.
+
+### Example
+
+Use `Amb` to propagate the first observable sequence that emits notifications.
+
+:::workflow
+![Amb Example](../workflows/reactive-amb-example.bonsai)
+:::
+
+### Alternative
+
+Use [`Switch`](xref:Bonsai.Reactive.Switch) instead to propagate the latest observable sequence that emits notifications from a sequence of observable sequences.

articles/reactive-append.md

@@ -0,0 +1,16 @@
+---
+uid: reactive-append
+title: Append
+---
+
+### Example
+
+Use `Append` to add an element to the end of a sequence.
+
+:::workflow
+![Append Example](../workflows/reactive-append-example.bonsai)
+:::
+
+### Alternative
+
+Use [`Prepend`](xref:Bonsai.Reactive.Prepend) instead to add an element to the beginning of a sequence.

articles/reactive-average.md

@@ -6,3 +6,25 @@ title: Average
 ![Marble diagram](~/images/reactive-average.svg)
 
 The `Average` operator collects all the values from the source sequence and emits a single floating-point number representing their arithmetic mean. The single result value is emitted only when the source sequence terminates successfully.
+
+### Examples
+
+Use `Average` to report the mean value at the end of the sequence.
+
+:::workflow
+![Average Example](../workflows/reactive-average-example.bonsai)
+:::
+
+#### Signal Smoothing
+
+Use `Average` to smooth a noisy signal by grouping elements with [`WindowCount`](xref:Bonsai.Reactive.WindowCount), then applying `Average` inside a [`SelectMany`](xref:Bonsai.Reactive.SelectMany).
+
+:::workflow
+![Average Application Downsample](../workflows/reactive-average-application-downsample.bonsai)
+:::
+
+> [!NOTE]
+> This operation is equivalent to [downsampling](https://en.wikipedia.org/wiki/Downsampling_(signal_processing)) and reduces the number of elements in the sequence. To implement a [moving average](https://en.wikipedia.org/wiki/Moving_average) that preserves the number of elements, you can adjust the `Skip` property in [`WindowCount`](xref:Bonsai.Reactive.WindowCount) to create sliding windows.
+
+> [!NOTE]
+> This example requires the `Bonsai.Design.Visualizers` package to be installed.

articles/reactive-buffercount.md

@@ -8,3 +8,17 @@ title: Buffer
 `BufferCount` groups the notifications of the source sequence into chunks containing the number of elements specified in the <xref href="Bonsai.Reactive.BufferCount.Count"/> property. The overlap between the elements in each chunk can be controlled using the <xref href="Bonsai.Reactive.BufferCount.Skip"/> property.
 
 If no skip value is provided, the chunks will be strictly non-overlapping, with a new chunk beginning when the previous chunk ends. If the skip value is less than the specified number of elements, chunks will be overlapping, with a new buffer created every `Skip` notifications. Finally, if the skip value is greater than the specified number of elements, there will be a gap between each chunk where elements from the source sequence will be dropped.
+
+### Example
+
+Use `BufferCount` to group elements into zero or more buffers based on element count.
+
+:::workflow
+![BufferCount Example](../workflows/reactive-buffercount-example.bonsai)
+:::
+
+### Alternatives
+
+Use [`BufferTime`](xref:Bonsai.Reactive.BufferTime) instead to group elements into zero or more buffers based on timing information.
+
+Use [`WindowCount`](xref:Bonsai.Reactive.WindowCount) instead to create new observable sequences based on element count.

articles/reactive-buffertime.md

@@ -8,3 +8,17 @@ title: BufferTime
 The `BufferTime` operator groups the notifications of the source sequence into chunks, where each chunk contains the elements emitted during the specified <xref href="Bonsai.Reactive.BufferTime.TimeSpan"/>. The overlap between the elements in each chunk can be controlled using the <xref href="Bonsai.Reactive.BufferTime.TimeShift"/> property.
 
 If no `TimeShift` is provided, the chunks will be strictly non-overlapping, with a new chunk beginning when the previous chunk ends. If `TimeShift` is smaller than `TimeSpan`, chunks will be overlapping, with a new buffer created every `TimeShift` interval. Finally, if `TimeShift` is larger than `TimeSpan`, there will be a time gap between each chunk where elements from the source sequence may be dropped.
+
+### Example
+
+Use `BufferTime` to group elements into zero or more buffers based on timing information.
+
+:::workflow
+![BufferTime Example](../workflows/reactive-buffertime-example.bonsai)
+:::
+
+### Alternatives
+
+Use [`BufferCount`](xref:Bonsai.Reactive.BufferCount) instead to group elements into zero or more buffers based on element count.
+
+Use [`WindowTime`](xref:Bonsai.Reactive.WindowTime) instead to create new observable sequences based on timing information.

articles/reactive-buffertrigger.md

@@ -10,3 +10,15 @@ title: BufferTrigger
 If neither buffer count nor buffer time span are specified, chunks will be strictly non-overlapping, with the previous chunk being closed when a new chunk is created. In this case, and only this case, the first chunk is also created immediately at the start of the sequence.
 
 If the `Count` property or the `TimeSpan` property is specified, then a new chunk is created when the second sequence emits a notification, and it is automatically closed after either the specified number of elements is collected or the specified time span elapses. If a new chunk is created before the previous chunk is closed, then chunks will overlap, and any elements emitted during this period will be included in both buffers. If at any moment there is no open buffer, elements emitted from the source sequence will be dropped.
+
+### Example
+
+Use `BufferTrigger` to group elements into zero or more buffers based on notifications from a second sequence.
+
+:::workflow
+![BufferTrigger Example](../workflows/reactive-buffertrigger-example.bonsai)
+:::
+
+### Alternative
+
+Use [`WindowTrigger`](xref:Bonsai.Reactive.WindowTrigger) instead to group elements into zero or more observable sequences based on notifications from a second sequence.

articles/reactive-catch.md

@@ -7,4 +7,18 @@ title: Catch
 
 The `Catch` operator allows you to handle error notifications from a sequence by combining the output of multiple fallback sequences of the same type into a single sequence. `Catch` subscribes to the next sequence when the previous sequence produces an error, and emits all the values from that sequence until successful termination. If that sequence also terminates exceptionally, `Catch` then subscribes to the next sequence, and so forth. Each sequence is guaranteed to only start after the previous one terminates.
 
-The resulting sequence will terminate successfully when any of the source sequences has terminated successfully, or exceptionally when all sequences have terminated with an error.
+The resulting sequence will terminate successfully when any of the source sequences has terminated successfully, or exceptionally when all sequences have terminated with an error.
+
+### Example
+
+Use `Catch` to continue an observable sequence that terminated with an exception with the next observable sequence.
+
+:::workflow
+![Catch Example](../workflows/reactive-catch-example.bonsai)
+:::
+
+### Alternative
+
+Use [`Retry`](xref:Bonsai.Reactive.Retry) instead to repeat subscription to the observable sequence if it terminates with an exception.
+
+Use [`OnErrorResumeNext`](xref:Bonsai.Reactive.OnErrorResumeNext) instead to avoid raising an exception when all sequences have terminated with an error.

articles/reactive-combinelatest.md

@@ -7,13 +7,38 @@ title: CombineLatest
 
 `CombineLatest` combines the values from each sequence which are closest in time. Whenever any of the source sequences emits a value (as long as all source sequences have emitted at least one value), `CombineLatest` takes the most recently emitted values from all other sequences and creates the combined result. `CombineLatest` will continue to emit values as long as at least one source sequence remains active (i.e. without terminating).
 
-`CombineLatest` can be useful to temporally correlate separate sources (e.g. frames from different cameras, or the closest frame to a key press). It can also be useful when combining a sequence containing a single reference value with a possibly infinite sequence of values to be associated with the reference (e.g. subtracting a background from every frame).
+### Examples
+
+Use `CombineLatest` to combine multiple sources in time.
+
+:::workflow
+![CombineLatest Example](../workflows/reactive-combinelatest-example.bonsai)
+:::
 
 > [!Warning]
-> Because `CombineLatest` emits a combined value whenever *any* of the source sequences emits a new value, the number of values emitted by `CombineLatest` is approximately the sum of the number of values in each sequence. If you need to discard redundant values you can filter the output, e.g. using [`Sample`](xref:Bonsai.Reactive.Sample) to use one of the source sequences as a master driver.
+> As `CombineLatest` emits a combined value whenever *any* of the source sequences emits a new value, the number of values emitted by `CombineLatest` is approximately the sum of the number of values in each sequence. If you want to use only one of the source sequences as a master driver and discard redundant values, consider using [`Sample`](xref:Bonsai.Reactive.Sample).
+
+:::workflow
+![CombineLatest Example with Sample](../workflows/reactive-combinelatest-example-sample.bonsai)
+:::
+
+#### Video Synchronization
+
+Use `CombineLatest` to combine multiple sources (e.g. frames from different cameras). 
+
+:::workflow
+![CombineLatest Application Synchronize Video](../workflows/reactive-combinelatest-application-synchronizevideo.bonsai)
+:::
+
+> [!NOTE]
+> This example requires the `Bonsai.Dsp`, `Bonsai.Vision` and `Bonsai.Vision.Design` packages to be installed.
+
+### Alternative
+
+Use [`WithLatestFrom`](xref:Bonsai.Reactive.WithLatestFrom) if you only need to combine two sources and want to discard redundant values.
 
 ### Higher-order operator
 
 `CombineLatest` also works as a higher-order operator, so it can take as input a sequence of observable sequences. In this case, it will subscribe to each of the source sequences and start collecting all the latest values from each sequence. As soon as the outer sequence terminates, it will start reactively combining the latest values whenever any sequence changes, just as in the case of using `CombineLatest` with a fixed number of inputs. 
 
-![Higher order](~/images/reactive-combinelatestwindow.svg)
+![Higher order](~/images/reactive-combinelatestwindow.svg)