added better docs and more tests for the samplers
added map_with_index, generally useful