Cleanups (#47)

Various random cleanups before wider circulation.
* renamed reservoir_iterable to reservoir_sample
* Improve animation example UI
* Miscellanous minor improvements
* gitignore tweaks
* Exclude some files from being packaged

Author: daniel-vainsencher

.gitignore

@@ -3,3 +3,6 @@
 .DS_Store
 Cargo.lock
 /p3
+/visualizations
+/visualizations_python/__pycache__
+/visualizations_python/parameters_for_histogram.yaml

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Architecture
 
-This document describes the highest level architecture of the library iterative_methods_done_right_in_rust. As a tree structure, the code base looks like this:
+The high level architecture of the iterative_methods crate. As a tree structure, the code base looks like this:
 
 ```
 iterative_methods_done_right_in_rust
@@ -21,24 +21,30 @@ If you haven't already, please see the README.md document for an introduction to
 
 The remaining sections will address the contents and structure of each directory of the tree. 
 
-## src
-
-In `src` the lib.rs file contains all of the code needed to use the tools in this library. Unit tests are included. Most of the code base consists of iterator adaptors. They currently include
-- ReservoirIterable
-- StepBy	
-- Tee
-- TimedIterable
-and their associated functions and structs.
 
+## src
 
+In `src`, `lib.rs` exports iterative methods (via algorithms.rs) and
+utilities consisting of iterator adaptors. They currently include
+- take_until
+- assess
+- inspect
+- last
+- time
+- step_by
+- write_yaml_documents
+- enumerate
+- {weighted_}reservoir_sample
+and their associated implementations. Unit tests are included. 
 
 ## examples
 
-Examples demonstrating the basic functionality are provided. Currently, the examples include
-- Fibonnacci
-- Conjugate Gradient Method (CGIterable)
+Examples demonstrating different functionality. Currently:
+
+- Conjugate Gradient Method (ConjugateGradient)
 - Weighted Reservoir Sampling
+- Output to yaml, e.g., for animations
 
 ## tests
 
-Integration tests are provided.
+Some integration tests.

COPYING.md

@@ -6,6 +6,10 @@ edition = "2018"
 description = "Iterative methods and associated utilities as StreamingIterators."
 license = "MIT OR Apache-2.0"
 keywords = ["math","stream","machine-learning","algorithm","optimization"]
+repository = "https://github.com/daniel-vainsencher/iterative_methods_rs"
+readme = "README.md"
+exclude = ["/local", "/visualizations", "/p3", "/visualizations_python/__pycache__", "visualizations_python/parameters_for_histogram.yaml"]
+
 [lib]
 name = "iterative_methods"
 path = "src/lib.rs"

Cargo.toml

@@ -1,21 +1,26 @@
-This project aims to implement iterative methods and associated utilities in Rust. 
+The iterative_methods project implements iterative methods and
+associated utilities in Rust.
 
 It currently demonstrates the following techniques we find powerful:
 - Implement iterative methods as StreamingIterators.
-- Implement utilities useful to iterative methods as generic adaptors
+- Implement iterative methods utilities as generic adaptors
   of StreamingIterators.
 - Test non-trivial methods via property testing (quickcheck).
 - Generic output via streaming yaml
 
+If you're not familiar with iterative methods or what the above mean,
+[start
+here](https://daniel-vainsencher.github.io/book/iterative_methods_part_1.html).
+
 Future plans:
 - Expand/stabilize design
-- Add new iterative methods
+- Add more iterative methods
 - Add higher level utilities
 - Add simple function call interface to methods.
 
 Stability/evolution:
 - The design is actively evolving, breakage is to be expected
-  everywhere.
+  everywhere. Feedback welcome! email us or open issues on the repo.
 - Some utilities (e.g., take_until) probably belong elsewhere (e.g.,
   {Streaming}Iterator) and so might migrate entirely.
 

Plan.org

@@ -71,7 +71,7 @@ fn write_reservoir_visualizations_data_to_yaml(
     let stream = enumerate(stream);
     let stream = write_yaml_documents(stream, parameters["stream_file"].to_string())
         .expect("Create File and initialize yaml iter failed.");
-    let stream = reservoir_iterable(stream, capacity, None);
+    let stream = reservoir_sample(stream, capacity, None);
     let stream = write_yaml_documents(stream, parameters["reservoir_samples_file"].to_string())
         .expect("Create File and initialize yaml iter failed.");
 

README.md

@@ -31,7 +31,7 @@ fn reservoir_sampling_mean_convergence() -> std::io::Result<()> {
 
     // Create another copy of the stream to perform reservoir sampling and write to yaml:
     let stream = utils::generate_enumerated_step_stream(stream_size, num_of_initial_values, 0, 1);
-    let res_iter = reservoir_iterable(stream, capacity, None);
+    let res_iter = reservoir_sample(stream, capacity, None);
     let reservoir_samples_file = "./target/debug/examples/reservoirs.yaml";
     // Write data to file for visualization.
     let mut res_to_yaml = write_yaml_documents(res_iter, reservoir_samples_file.to_string())

examples/reservoir_histogram_animation.rs

@@ -5,7 +5,7 @@ use streaming_iterator::*;
 
 /// Utility function to generate a sequence of (float, int as float)
 /// values wrapped in a WeightedDatum struct that will be used in tests
-/// of ReservoirIterable.
+/// of ReservoirSample.
 fn generate_seeded_values(num_values: usize, int_range_bound: usize) -> Vec<WeightedDatum<f64>> {
     let mut prng = Pcg64::seed_from_u64(1);
     let mut seeded_values: Vec<WeightedDatum<f64>> = Vec::new();
@@ -32,7 +32,7 @@ fn wrs_demo() {
     println!("Random Numbers for Alg: \n (The values are used as the probabilities and the weights as indices.) \n {:#?} \n ", probability_and_index);
 
     let stream = convert(stream);
-    let mut stream = weighted_reservoir_iterable(stream, 2, Some(Pcg64::seed_from_u64(1)));
+    let mut stream = weighted_reservoir_sample(stream, 2, Some(Pcg64::seed_from_u64(1)));
     println!("Reservoir - initially empty: \n {:#?} \n", stream.reservoir);
     let mut _index = 0usize;
     while let Some(reservoir) = stream.next() {

examples/reservoir_sampling_mean_convergence.rs

@@ -82,7 +82,7 @@ fn write_wrs_visualizations_data_to_yaml(
         .expect("Create File and initialize yaml iter failed.");
     // Add constant weights to all items
     let stream = wd_iterable(stream, |_x| 1.0f64);
-    let stream = weighted_reservoir_iterable(stream, capacity, None);
+    let stream = weighted_reservoir_sample(stream, capacity, None);
     // remove the weights, which were only needed for applying WRS.
     let stream = stream.map(|x| {
         let x: Vec<Numbered<f64>> = x.iter().map(|wd| wd.value.clone()).collect();
@@ -172,7 +172,14 @@ fn main() -> std::io::Result<()> {
     let (visualize, stream_size, capacity) = set_visualization_parameters();
     remove_yaml_files()?;
     write_wrs_visualizations_data_to_yaml(stream_size, capacity)?;
-    println!("Data is written to yaml files.");
+    println!(
+        "Animation data files saved at:
+        ./target/debug/examples/population_for_histogram.yaml   
+        ./target/debug/examples/reservoirs_for_histogram.yaml 
+        ./target/debug/examples/reservoir_means.yaml  
+        ./target/debug/examples/stream_for_histogram.yaml 
+        "
+    );
     if visualize {
         make_visualization_in_python(
             "./visualizations_python/reservoir_histograms_initial_final.py",
@@ -186,15 +193,7 @@ fn main() -> std::io::Result<()> {
             "./visualizations_python/reservoir_histogram_animation.py",
             "Animation of reservoir and stream histograms",
         )?;
-    } else {
-        println!(
-            "The following .yaml files have been created:\n
-            ./target/debug/examples/population_for_histogram.yaml \n  
-            ./target/debug/examples/reservoirs_for_histogram.yaml \n
-            ./target/debug/examples/reservoir_means.yaml \n 
-            ./target/debug/examples/stream_for_histogram.yaml \n
-            "
-        );
+        println!("Animations saved at visualizations/*.html")
     }
     Ok(())
 }

examples/weighted_reservoir_sampling.rs

@@ -1,17 +1,17 @@
 # Intent:
 
-- [ ] Explain here what the goal is, so reviewer can read the implementation and judge whether that goal is achieved.
+<Explain the goal of the PR for the implementation to be judged
+against. Link to relevant context including issues, papers, etc>
 
 # Validation:
 
-- [ ] Are changes covered by tests so we know existing functionality is not broken?
-- [ ] Is the new functionality covered by tests?
-- [ ] For functionality that is impractical to test
-  - [ ] is there a demo?
-  - [ ] does it look like you'd expect?
+<Survey coverage by existing or new tests, create a checklist for
+uncovered changes. For changes impractical to test, list them and
+consider a demo for human checking.>
 
 # State of PR
-- [ ] Ready to merge on master
-- [ ] CI passes
-- [ ] Code is documented via rustdoc commments for readers post-landing
-- [ ] Changes that need explanation pre-landing (why make the change) have self-review comments
+<Check boxes when done>
+- [ ] Rustdoc and implementation comments?
+- [ ] Self review comments on non-obvious changes?
+- [ ] It seems to you ready to merge on master?
+