Rudimentary documentation

Author: mbillingr

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "openml"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Martin Billinger <flkazemakase@gmail.com>"]
 
 description = "A rust interface to [OpenML](http://openml.org/)."

src/baseline/mod.rs

@@ -1,3 +1,5 @@
+//! Implementation of simple baseline models, used for testing and demonstration.
+
 mod naive_bayes_classifier;
 
 pub use self::naive_bayes_classifier::NaiveBayesClassifier;

src/baseline/naive_bayes_classifier.rs

@@ -1,24 +1,36 @@
+//! Implementation of a Gaussian Naive Bayes Classifier
+
 use std::cmp::Ordering;
 use std::collections::HashMap;
 use std::f64;
 use std::fmt;
 use std::hash::Hash;
 use std::iter::FromIterator;
 
+/// A Gaussian Naive Bayes Classifier
+///
+/// The classifier is trained by consuming an iterator over the training data:
+/// ```
+/// let nbc: NaiveBayesClassifier<_> = data
+///     .iter()
+///     .collect();
+/// ```
 #[derive(Debug)]
 pub struct NaiveBayesClassifier<C>
 where C: Eq + Hash
 {
     class_distributions: HashMap<C, FeatureDistribution>,
 }
 
+/// Distribution of each feature column
 #[derive(Debug, Clone)]
 struct FeatureDistribution {
-    distributions: Vec<UniformNormalDistribution>
+    distributions: Vec<NormalDistribution>
 }
 
+/// Univariate Normal Distribution
 #[derive(Copy, Clone)]
-struct UniformNormalDistribution {
+struct NormalDistribution {
     sum: f64,
     sqsum: f64,
     n: usize
@@ -40,7 +52,7 @@ where
 
             for (i, &xi) in x.into_iter().enumerate() {
                 if i >= distributions.len() {
-                    distributions.resize(1 + i, UniformNormalDistribution::new());
+                    distributions.resize(1 + i, NormalDistribution::new());
                 }
 
                 distributions[i].update(xi);
@@ -56,6 +68,7 @@ where
 impl<C> NaiveBayesClassifier<C>
 where  C: Eq + Hash + Copy,
 {
+    /// predict target class for a single feature vector
     pub fn predict(&self, x: &[f64]) -> C {
         self.class_distributions
             .iter()
@@ -88,9 +101,9 @@ impl FeatureDistribution {
     }
 }
 
-impl UniformNormalDistribution {
+impl NormalDistribution {
     fn new() -> Self {
-        UniformNormalDistribution {
+        NormalDistribution {
             sum: 0.0,
             sqsum: 0.0,
             n: 0
@@ -120,7 +133,7 @@ impl UniformNormalDistribution {
     }
 }
 
-impl fmt::Debug for UniformNormalDistribution {
+impl fmt::Debug for NormalDistribution {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "N{{{}; {}}}", self.mean(), self.variance())
     }

src/dataset.rs

@@ -1,12 +1,15 @@
 use arff::dynamic::DataSet as ArffDataSet;
 
+/// An arbitrary data set
 #[derive(Debug)]
 pub(crate) struct DataSet {
     pub(crate) arff: ArffDataSet,
     pub(crate) target: Option<String>,
 }
 
 impl DataSet {
+    /// return two `ArffDataSet`s; one containing the features and the other containing the target
+    /// variable.
     pub(crate) fn clone_split(&self) -> Option<(ArffDataSet, ArffDataSet)> {
         match self.target {
             None => None,

src/lib.rs

@@ -1,5 +1,8 @@
 //! # openml-rust
 //!
+//! The openml crate provides functions to fetch tasks and data sets from https://openml.org, and
+//! run them with machine learning models.
+//!
 //! ## Example
 //!
 //! ```rust

src/measure_accumulator.rs

@@ -1,18 +1,29 @@
+//! Measure accumulators are summaries of model performance, such as classification accuracy or
+//! regression error.
+
 use std::marker::PhantomData;
 use num_traits::AsPrimitive;
 
+/// Trait implemented by performance measures
 pub trait MeasureAccumulator<T> {
+    /// initialize new measure
     fn new() -> Self;
+
+    /// update with one prediction
     fn update_one(&mut self, known: &T, pred: &T);
+
+    /// get resulting performance
     fn result(&self) -> f64;
 
+    /// update with multiple predictions
     fn update<I: Iterator<Item = T>>(&mut self, known: I, predicted: I) {
         for (k, p) in known.zip(predicted) {
             self.update_one(&k, &p)
         }
     }
 }
 
+/// Classification Accuracy: relative amount of correctly classified labels
 #[derive(Debug)]
 pub struct PredictiveAccuracy<T> {
     n_correct: usize,
@@ -45,6 +56,7 @@ where
     }
 }
 
+/// Root Mean Squared Error
 #[derive(Debug)]
 pub struct RootMeanSquaredError<T> {
     sum_of_squares: f64,

src/openml_api/api_types.rs

@@ -1,5 +1,6 @@
 use serde_json;
 
+/// Generic JSON response as returned by the OpenML API
 #[derive(Debug, Serialize, Deserialize)]
 pub struct GenericResponse(serde_json::Value);
 
@@ -10,8 +11,9 @@ impl GenericResponse {
     }
 }
 
+/// A row in a split file
 #[derive(Debug, Deserialize)]
-pub struct CrossValItem {
+pub(crate) struct CrossValItem {
     #[serde(rename = "type")]
     pub purpose: TrainTest,
 
@@ -23,14 +25,15 @@ pub struct CrossValItem {
 }
 
 #[derive(Debug, Deserialize)]
-pub enum TrainTest {
+pub(crate) enum TrainTest {
     #[serde(rename = "TRAIN")]
     Train,
 
     #[serde(rename = "TEST")]
     Test,
 }
 
+/// Cost matrix, used by some classification tasks - currently UNIMPLEMENTED
 #[derive(Debug)]
 pub(crate) enum CostMatrix {
     None,

src/openml_api/file_lock.rs

@@ -1,38 +1,46 @@
+//! file locking mechanisms
+
 use std::fs::File;
 use std::io::{self, Read, Write};
 
 use fs2::FileExt;
 
+/// A scoped exclusive lock for use by file writers
 pub struct ExclusiveLock {
     file: File,
 }
 
 impl ExclusiveLock {
+    /// acquire locked file
     pub fn new(file: File) -> io::Result<Self> {
         file.lock_exclusive()?;
         Ok(ExclusiveLock { file })
     }
 }
 
 impl Drop for ExclusiveLock {
+    /// release locked file
     fn drop(&mut self) {
         self.file.unlock().unwrap();
     }
 }
 
 impl Read for ExclusiveLock {
+    /// read from locked file
     #[inline(always)]
     fn read(&mut self, data: &mut [u8]) -> io::Result<usize> {
         self.file.read(data)
     }
 }
 
 impl Write for ExclusiveLock {
+    /// write to locked file
     #[inline(always)]
     fn write(&mut self, data: &[u8]) -> io::Result<usize> {
         self.file.write(data)
     }
 
+    /// flush buffer of locked file
     #[inline(always)]
     fn flush(&mut self) -> io::Result<()> {
         self.file.flush()
@@ -43,34 +51,26 @@ pub struct SharedLock {
     file: File,
 }
 
+/// A scoped shared lock for use by file readers
 impl SharedLock {
+    /// acquire locked file
     pub fn new(file: File) -> io::Result<Self> {
         file.lock_shared()?;
         Ok(SharedLock { file })
     }
 }
 
 impl Drop for SharedLock {
+    /// release locked file
     fn drop(&mut self) {
         self.file.unlock().unwrap();
     }
 }
 
 impl Read for SharedLock {
+    /// read from locked file
     #[inline(always)]
     fn read(&mut self, data: &mut [u8]) -> io::Result<usize> {
         self.file.read(data)
     }
 }
-
-impl Write for SharedLock {
-    #[inline(always)]
-    fn write(&mut self, data: &[u8]) -> io::Result<usize> {
-        self.file.write(data)
-    }
-
-    #[inline(always)]
-    fn flush(&mut self) -> io::Result<()> {
-        self.file.flush()
-    }
-}

src/openml_api/impls_from_json.rs

@@ -1,3 +1,4 @@
+//! implementations to convert the API's JSON responses into corresponding Rust structures
 use arff;
 use arff::dynamic::DataSet as ArffDataSet;
 use serde_json;

src/openml_api/impls_from_openml.rs

@@ -1,3 +1,4 @@
+//! implementations to load tasks from the OpenML API.
 use serde_json;
 
 use error::Result;