Add documentation, test, fix some bugs

Author: galenlynch

Project.toml

@@ -1,7 +1,7 @@
 name = "SignalIndices"
 uuid = "18f53e89-494d-4131-905c-653e8ada6cd8"
 authors = ["Galen Lynch <galen@galenlynch.com>"]
-version = "0.1.1"
+version = "0.1.2"
 
 [deps]
 IterTools = "c8e1da08-722c-5040-9ed9-7db0dc04731e"

README.md

@@ -2,92 +2,33 @@
 
 Utilities for working with regularly sampled time series data, including index-time conversions, signal processing primitives, and array manipulation functions.
 
-## Overview
-
-This package provides low-level building blocks for signal processing workflows, particularly for neuroscience and electrophysiology applications where data is regularly sampled at a known frequency. The focus is on efficient, allocation-conscious implementations suitable for processing large datasets.
-
-## Features
-
-### Index/Time Conversion
-
-Convert between sample indices and time values for regularly sampled data:
+## Quick Example
 
 ```julia
 using SignalIndices
 
-fs = 30000.0  # 30 kHz sampling rate
-start_t = 0.0
-
-# Convert time to index
-idx = t_to_ndx(0.5, fs, start_t)  # First sample at or after 0.5s
-
-# Convert index to time
-t = ndx_to_t(15001, fs, start_t)  # Time of sample 15001
-
-# Duration and time intervals
-dur = duration(30001, fs)  # Duration spanned by 30001 samples
-interval = time_interval(30001, fs, start_t)  # (start_t, end_t) tuple
-```
-
-### Signal Processing Primitives
-
-```julia
-# Sliding window sum (no zero-padding)
-sums = moving_sum(signal, window_size)
+fs = 30_000.0  # 30 kHz sampling rate
 
-# Find threshold crossings (edge triggers)
-rising_edges = find_all_edge_triggers(signal, threshold)
-first_edge = find_first_edge_trigger(signal, threshold)
+# Convert between sample indices and time
+t = ndx_to_t(15001, fs)         # 0.5 s
+idx = t_to_ndx(0.5, fs)         # 15001
 
-# Find local extrema
-maxima_indices = local_extrema(signal, >)
-minima_indices = local_extrema(signal, <)
+# Detect threshold crossings in a signal
+edges = find_all_edge_triggers(signal, threshold)
 
-# Fast histogram for regularly-spaced bins
-counts = uniformhist(values, bin_edges)
+# Sliding window sum (no zero-padding) and fast histogram
+sums = moving_sum(signal, 100)
+counts = uniformhist(spike_times, 0.0:0.001:1.0)
 ```
 
-### Array Utilities
-
-```julia
-# Pairwise operations
-idxs = pairwise_idxs(n)  # All (i,j) pairs where i > j
-diffs = map_pairwise(-, sorted_times)  # Pairwise differences
-
-# Filtering and searching
-idx = find_closest(array, target)
-non_colliding = filter_no_collisions(events_a, events_b, min_gap)
-duplicates = find_not_unique(array)
+## When to Use What
 
-# Equality and comparison
-allsame([1, 1, 1])            # true — all elements equal
-allsame(length, [1,2], [3,4]) # true — all have same length
-anyeq(3, [1, 2, 3])           # true — element found in collection
-absdiff(5, 3)                 # 2 — absolute difference (unsigned-safe)
-
-# Iterator utilities
-result = sum(skipnothing([1, nothing, 2, nothing, 3]))  # 6
-```
-
-## Relation to Other Packages
-
-### vs DSP.jl
-
-[DSP.jl](https://github.com/JuliaDSP/DSP.jl) provides comprehensive digital signal processing including filters, FFTs, and spectral analysis. SignalIndices.jl is complementary, focusing on:
-- Index/time bookkeeping for sampled data
-- Simple threshold and edge detection
-- Utilities commonly needed before/after DSP operations
-
-### vs SampledSignals.jl
-
-[SampledSignals.jl](https://github.com/JuliaAudio/SampledSignals.jl) focuses on audio I/O with rich type hierarchies for audio buffers. This package has different goals:
-- No audio-specific functionality
-- Focus on index/time math and signal primitives
-- Designed for neuroscience/electrophysiology workflows
-
-### vs TimeSeries.jl
-
-[TimeSeries.jl](https://github.com/JuliaStats/TimeSeries.jl) provides `TimeArray` types for financial/irregular time series. SignalIndices.jl assumes regular sampling and works with plain arrays, computing times from indices and sampling rates rather than storing timestamps.
+| Package | Focus |
+|---------|-------|
+| **SignalIndices.jl** | Index/time math, edge detection, and array primitives for regularly sampled data |
+| [DSP.jl](https://github.com/JuliaDSP/DSP.jl) | Filters, FFTs, spectral analysis — use *with* SignalIndices for bookkeeping |
+| [SampledSignals.jl](https://github.com/JuliaAudio/SampledSignals.jl) | Audio I/O with rich buffer types — audio-specific |
+| [TimeSeries.jl](https://github.com/JuliaStats/TimeSeries.jl) | `TimeArray` types for financial/irregular time series — stores timestamps per sample |
 
 ## Installation
 
@@ -97,57 +38,9 @@ using Pkg
 Pkg.develop(path="/path/to/SignalIndices")
 ```
 
-## API Reference
-
-### Type Utilities
-- `div_type(T)` - Determine appropriate floating-point type for division
-
-### Index/Time Conversion
-- `ndx_to_t(i, fs, start_t)` - Index to time
-- `t_to_ndx(t, fs, start_t)` - Time to index (first sample at or after)
-- `t_to_last_ndx(t, fs, start_t)` - Time to index (last sample at or before)
-- `t_sup_to_ndx(t, fs, start_t)` - Time to index (last sample before)
-- `clip_ndx(idx, len)` - Clamp index to valid range
-- `n_ndx(start, stop)` - Count indices in range
-- `duration(npoints, fs)` - Time span of samples
-- `time_interval(npoints, fs, start_t)` - Start/end time tuple
-
-### Bin/Window Operations
-- `bin_bounds(binno, binsize)` - Index bounds for a bin
-- `bin_center(binno, binsize)` - Center index of a bin
-- `expand_selection(ib, ie, imax, expansion)` - Expand index range
-
-### Signal Processing
-- `moving_sum(signal, window)` / `moving_sum!(out, signal, window)` - Sliding sum
-- `find_all_edge_triggers(arr, threshold, comp)` - Find all threshold crossings
-- `find_first_edge_trigger(arr, threshold, comp)` - Find first crossing
-- `thresh_cross(arr, threshold, comp)` - Threshold crossing indices
-- `indices_above_thresh(arr, threshold)` - Contiguous regions above threshold
-- `local_extrema(signal, comp)` - Find local maxima/minima
-- `find_local_extrema(signal, start; findmax, right_on_ties)` - Hill-climb to extremum
-- `uniformhist(values, bins)` / `uniformhist!(counts, values, bins)` - Fast histogram
-- `filter_no_collisions(as, bs, radius)` - Remove elements too close to reference
-- `window_counts(times, duration)` - Count events in sliding window
+## Documentation
 
-### Array Utilities
-- `weighted_mean(values, weights)` / `weighted_mean_dim(arr, weights, dim)` - Weighted averages
-- `simple_summary_stats(arr)` - Mean, std, SEM tuple
-- `find_closest(arr, target)` - Index of nearest value
-- `find_subseq(subseq, seq)` - Find subsequence occurrences
-- `subselect(vec, index_tuples)` - Extract subvectors by index ranges
-- `pairwise_idxs(n)` - Generate all unique pairs
-- `pairwise_idx(i, j, n)` - Linear index for pair
-- `map_pairwise(f, vec)` - Apply function to all pairs
-- `imap_product(f, as, bs)` - Lazy Cartesian product map
-- `filtermap(predicate, f, xs)` - Combined filter and map
-- `find_not_unique(arr)` - Indices of duplicate elements
-- `trailing_zeros_idx(arr)` - Last non-zero index
-- `clipsize!(vec, n)` - Resize and shrink capacity
-- `rev_view(vec)` - Reversed view
-- `allsame(collection)` / `allsame(f, args...)` - Check all elements (or mapped values) are equal
-- `anyeq(element, collection)` - Check if element exists in collection
-- `absdiff(a, b)` - Absolute difference (safe for unsigned integers)
-- `skipoftype(T, itr)` / `skipnothing(itr)` - Skip elements by type
+See the [full documentation](https://galenlynch.github.io/SignalIndices.jl/dev/) for a usage guide and API reference.
 
 ## Citing
 

docs/make.jl

@@ -14,7 +14,10 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
+        "Usage Guide" => "guide.md",
+        "API Reference" => "api.md",
     ],
+    warnonly=[:missing_docs],
 )
 
 deploydocs(;

docs/src/api.md

@@ -0,0 +1,14 @@
+```@meta
+CurrentModule = SignalIndices
+```
+
+# [API Reference](@id api)
+
+```@index
+```
+
+```@autodocs
+Modules = [SignalIndices]
+Public = true
+Private = false
+```