# riemann.folds

Functions for combining states.

Folds usually come in two variants: a friendly version like sum, and a strict version like sum*. Strict variants will throw when one of their events is nil, missing a metric, or otherwise invalid. In typical use, however, you won’t *have* all the necessary information to pass on an event. Friendly variants will do their best to ignore these error conditions where sensible, returning partially complete events or nil instead of throwing.

Called with an empty list, folds which would return a single event return nil.

### difference

`(difference events)`

Subtracts events. Returns the first event, with its metric reduced by the metrics of all subsequent events with metrics. Returns nil if the first event is nil, or its metric is nil.

### difference*

`(difference* events)`

Subtracts events. Returns the first event, with its metric reduced by the metrics of all subsequent events.

### extremum

`(extremum comparison events)`

Returns an extreme event, by a comparison function over the metric.

### fold

`(fold f events)`

Fold with a reduction function over metrics. Ignores nil events and events with nil metrics.

If there are *no* non-nil events, returns nil.

### fold*

`(fold* f events)`

Fold with a reduction function over metrics. Throws if any event or metric is nil.

### fold-all

`(fold-all f events)`

Fold with a reduction function over metrics.

If the first event has a nil :metric, or if any remaining event is nil, or has a nil metric, returns the first event, but with :metric nil and a :description of the error.

If the first event is nil, returns nil.

### mean

`(mean events)`

Averages events together. Mean metric, merged into first of events. Ignores nil events and nil metrics.

### modes

`(modes events)`

Keep track of repeating metrics. Yields a sequence of events with the highest occuring metrics.

### non-nil-metrics

`(non-nil-metrics events)`

Given a sequence of events, returns a compact sequence of their metrics–that is, omits any events which are nil, or have nil metrics.

### product

`(product events)`

Multiplies events. Returns the first event with a metric, with its metric being the product of all events with metrics.

### product*

`(product* events)`

Multiplies events. Returns the first event, with its metric multiplied by the metrics of all other events.

### quotient

`(quotient events)`

Divides events. Returns the first event, with its metric divided by the product of the metrics of all subsequent events.

### quotient*

`(quotient* events)`

Divides events. Returns the first event, with its metric divided by the product of the metrics of all subsequent events. Like quotient, but throws when any metric is nil or a divisor is zero.

### quotient-sloppy

`(quotient-sloppy events)`

Like quotient, but considers 0/0 = 0. Useful for relative rates, when you want the ratio of two constant values to be zero.

### sorted-sample

`(sorted-sample s points)`

Sample a sequence of events at points. Returns events with service remapped to (str service " " point). For instance, (sorted-sample events 0 1) returns a 2-element seq of the smallest event and the biggest event, by metric. The first has a service which ends in " 0" and the second one ends in " 1". If the points is a map, eg (sorted-sample events {0 “.min” 1 “.max”}, the the values will be appened to the service name directly. Useful for extracting histograms and percentiles.

When s is empty, returns an empty list.

### sorted-sample-extract

`(sorted-sample-extract s points)`

Returns the events in seqable s, sorted and taken at each point p of points, where p ranges from 0 (smallest metric) to 1 (largest metric). 0.5 is the median event, 0.95 is the 95th’ percentile event, and so forth. Ignores events without a metric.

### sum

`(sum events)`

Adds events together. Sums metrics, merges into first event with a metric, ignores nil events and nil metrics.