sample-lines

samp is a fast command-line tool to randomly sample lines from a file or standard input using reservoir sampling. It samples uniformly without replacement.

Good for:

• Downsampling large datasets
• Sampling logs for debugging
• Creating reproducible random subsets of data

You can think of samp kind of like head or tail, for example:

head -n 10 < data.txt   # outputs 10 first lines
tail -n 10 < data.txt   # outputs 10 last lines
samp -n 10 < data.txt   # outputs 10 random lines

Installation

If you have Rust installed, you can install samp with:

cargo install sample-lines

Or build it from source:

git clone https://github.com/stringertheory/sample-lines.git
cd sample-lines
cargo build --release

Usage

samp -n <NUM> [--seed <SEED>] [FILE]

Here are a few examples:

samp --help                                   # Show help
cat data.txt | samp -n 10                     # Keep 10 lines, with pipe
samp -n 10 data.txt                           # Giving filename
samp -n 10 < data.txt                         # Standard in
samp -n 10 --seed 17 < data.txt               # Reproducible sample
cat data.csv | samp -n 10 --preserve-headers  # Preserve 1 header line
samp -r 0.01 < big.log                        # Keep ~1% of lines
samp -r 0.10 --seed 17 data.csv -p            # Reproducible 10% sample

Options

One of --number or --rate is required, but you can not pass both.

Option	Description
-n, --number <NUM>	Number of lines to sample
-r, --rate <RATE>	Sampling rate: probability to include each line (e.g., 0.05)
-s, --seed <SEED>	Optional seed for reproducible sampling
-p, --preserve-headers [N]	Preserve the first N lines as headers (default: 1 if flag is used)
-h, --help	Show help message
--version	Show the version number

Testing

cargo clean
cargo build # need binary for testing stdin/stderr
cargo test

License

Licensed under the MIT License.

Contributing

Issues and pull requests welcome! If you have an idea, a feature request, or a bug report, feel free to open an issue or PR.