Understand the compression workflows, quality controls, output metrics, native library, and HTTP API.
Load a time series and choose Compress, Benchmark, Build, or Optimize. No local installation is required.
Use the Zig library directly or its C, Python, Rust, and Julia bindings.
Use the same compression operations as the browser from an application or script.
Run one lossless or lossy compression method. Inspect compressed size, compression ratio, error bound, execution time, reconstruction metrics, and the original-versus-reconstructed plot. Download the compressed payload or the reconstructed CSV.
Compare lossless compression methods by ratio and throughput, or sweep lossy compression methods over equivalent quality or size controls and compare RMSE against compression ratio. Lossless results report compression and decompression time separately.
Combine a logical compression method, a lossless indices compression method, and a coefficient compression method. Compare the complete pipeline with its logical and coefficient stages on the same input.
Search pipeline configurations asynchronously. Choose how strongly to weight reconstruction quality versus compression ratio, then inspect ranked results as they become available.
| Approach | What it changes | Use it when |
|---|---|---|
| Lossless | Serialized representation only | Every input bit must reconstruct exactly |
| Logical-level lossy | Series shape using segments, transforms, or downsampling | Controlled approximation can provide higher compression |
| Physical-level lossy | Numeric value representation or precision | You want compact raw values or model coefficients |
| Indices | Integer representation of segment positions | You are building a multi-stage pipeline |
Practical starting point: use Compress when you already know the compression method, Benchmark when you need to compare options, Build when you need direct pipeline control, and Optimize when you want TerseTS to search for the current series.
The library configuration supports absolute (abs_error_bound) and relative
(rel_error_bound) error bounds. The console presents its error bound as a
percentage of the series range and converts it to an absolute value:
absolute bound = percentage / 100 * (maximum value - minimum value)
| Compression method category | Control used by TerseTS |
|---|---|
| Most logical and physical lossy compression methods | Maximum per-point deviation |
| Bottom-up and Sliding-window | RMSE bound |
| Visvalingam-Whyatt | Area-under-curve error bound |
| DFT | Number of retained coefficients |
| LTTB | Target retained-point count |
| BitPackedBUFF and Camel | Decimal precision in digits |
| Lossless and indices compression methods | No quality parameter |
DFT and LTTB default to a size budget around 25% of the series length. The Compress and Build logical controls default to a 3% range-based bound. The Build coefficient bound defaults to 0.01% because coefficient errors can be amplified during reconstruction.
| Metric | Meaning | Direction |
|---|---|---|
| Compression ratio | Original bytes divided by compressed bytes | Higher is better |
| Absolute error bound | Configured error threshold in the original series units | Lower favors accuracy |
| MAE | Mean absolute reconstruction error in the original units | Lower is better |
| RMSE | Root mean squared reconstruction error in the original units | Lower is better |
| MAPE | Mean absolute percentage error; Compress internally uses normalized MAAPE when zero or near-zero inputs would make MAPE unstable | Lower is better |
| NRMSE | RMSE as a percentage of the original series range; unavailable when that range is zero | Lower is better |
| Reward | Alpha-weighted Optimize score combining reconstruction quality and a compression score derived from compression ratio | Higher is better |
| Execution time | Compression wall-clock time | Lower is faster |
Optimize ranks available candidates with alpha * reconstruction_quality +
(1 - alpha) * compression_score. An alpha of 0.5 weights both signals equally;
larger values favor reconstruction quality. The console displays compression ratio;
internally, error and ratio are converted to bounded scores so they can be combined
reliably.
All workflows accept up to 100,000 finite numeric points. Compress, Benchmark, and Build return their results when the requested calculation finishes. Optimize can take longer, so its ranked options appear automatically while you continue using the other tabs.
For more usage detail, read the console guide or open the API reference from the console footer.
TerseTS is implemented in Zig and exposes Zig and C APIs plus language bindings.
Compression methods are selected from the Method enum and configured with a
small JSON object.
from tersets import compress, decompress, Method
values = [1.0, 2.0, 3.0, 4.0, 5.0]
compressed = compress(values, Method.SwingFilter, {"abs_error_bound": 0.1})
restored = decompress(compressed)
const tersets = @import("path/to/tersets.zig");
var values = [_]f64{ 1.0, 2.0, 3.0, 4.0, 5.0 };
var compressed = try tersets.compress(allocator, values, .SwingFilter, "{ \"abs_error_bound\": 0.1 }");
defer compressed.deinit();
var restored = try tersets.decompress(allocator, compressed);
defer restored.deinit();
use tersets::{Method, compress, decompress};
let values = vec![1.0, 2.0, 3.0, 4.0, 5.0];
let compressed = compress(&values, Method::SwingFilter, "{\"abs_error_bound\": 0.1}")?;
let restored = decompress(&compressed)?;
C and Julia examples, compilation instructions, and linking details are available in the library README.