diff --git a/doc/guide/cli_quickstart.hpp b/doc/guide/cli_quickstart.hpp new file mode 100644 index 0000000000..63cb48f6bf --- /dev/null +++ b/doc/guide/cli_quickstart.hpp @@ -0,0 +1,230 @@ +/** + * @file cli_quickstart.hpp + * @author Ryan Curtin + * @brief Quickstart documentation for mlpack usage from the command line + +@page cli_quickstart mlpack command-line quickstart guide + +This page describes how you can quickly get started using mlpack from the +command-line and gives a few examples of usage, and pointers to deeper +documentation. + +This quickstart guide is also available for @ref python_quickstart "Python". + +@section cli_quickstart_install Installing mlpack + +Installing the mlpack is straightforward and can be done with your system's +package manager. + +For instance, for Ubuntu or Debian the command is simply + +@code +$ sudo apt-get install mlpack-bin +@endcode + +On Fedora or Red Hat: + +@code +$ sudo dnf install mlpack +@endcode + +If you use a different distribution, mlpack may be packaged under a different +name. And if it is not packaged, you can use a Docker image from Dockerhub: + +@code +$ docker run -it mlpack/mlpack /bin/bash +@endcode + +This Docker image has mlpack already built and installed. + +If you prefer to build mlpack from scratch, see @ref build. + +@section cli_quickstart_example Simple mlpack quickstart example + +As a really simple example of how to use mlpack from the command-line, let's do +some simple classification on a subset of the standard machine learning @c +covertype dataset. We'll first split the dataset into a training set and a +testing set, then we'll train an mlpack random forest on the training data, and +finally we'll print the accuracy of the random forest on the test dataset. + +You can copy-paste this code directly into your shell to run it. + +@code +# Get the dataset and unpack it. +wget http://www.mlpack.org/datasets/covertype-small.data.csv.gz +wget http://www.mlpack.org/datasets/covertype-small.labels.csv.gz +gunzip covertype-small.data.csv.gz covertype-small.labels.csv.gz + +# Split the dataset; 70% into a training set and 30% into a test set. +# Each of these options has a shorthand single-character option but here we type +# it all out for clarity. +mlpack_preprocess_split \ + --input_file covertype-small.data.csv \ + --input_labels_file covertype-small.labels.csv \ + --training_file covertype-small.train.csv \ + --training_labels_file covertype-small.train.labels.csv \ + --test_file covertype-small.test.csv \ + --test_labels_file covertype-small.test.labels.csv \ + --test_ratio 0.3 \ + --verbose + +# Train a random forest. +mlpack_random_forest \ + --training_file covertype-small.train.csv \ + --labels_file covertype-small.train.labels.csv \ + --num_trees 10 \ + --minimum_leaf_size 3 \ + --print_training_accuracy \ + --output_model_file rf-model.bin \ + --verbose + +# Now predict the labels of the test points and print the accuracy. +# Also, save the test set predictions to the file 'predictions.csv'. +mlpack_random_forest \ + --input_model_file rf-model.bin \ + --test_file covertype-small.test.csv \ + --test_labels_file covertype-small.test.labels.csv \ + --predictions_file predictions.csv \ + --verbose +@endcode + +We can see by looking at the output that we achieve reasonably good accuracy on +the test dataset (80%+). The file @c predictions.csv could also be used by +other tools; for instance, we can easily calculate the number of points that +were predicted incorrectly: + +@code +$ diff -U 0 predictions.csv covertype-test.labels.csv | grep '^@@' | wc -l +@endcode + +It's easy to modify the code above to do more complex things, or to use +different mlpack learners, or to interface with other machine learning toolkits. + +@section cli_quickstart_whatelse What else does mlpack implement? + +The example above has only shown a little bit of the functionality of mlpack. +Lots of other commands are available with different functionality. Below is a +list of all the mlpack functionality offered through the command-line, split +into some categories. + + - Classification techniques: @c mlpack_adaboost, @c mlpack_decision_stump, @c + mlpack_decision_tree, @c mlpack_hmm_train, @c mlpack_hmm_generate, @c +mlpack_hmm_loglik, @c mlpack_hmm_viterbi, @c mlpack_hoeffding_tree, @c +mlpack_logistic_regression, @c mlpack_nbc, @c mlpack_perceptron, @c +mlpack_random_forest, @c mlpack_softmax_regression, @c mlpack_cf + + - Distance-based problems: @c mlpack_approx_kfn, @c mlpack_emst, @c + mlpack_fastmks, @c mlpack_kfn, @c mlpack_knn, @c mlpack_krann, @c mlpack_lsh, +@c mlpack_det, @c mlpack_range_search + + - Clustering: @c mlpack_kmeans, @c mlpack_mean_shift, @c mlpack_gmm_train, @c + mlpack_gmm_generate, @c mlpack_gmm_probability, @c mlpack_dbscan + + - Transformations: @c mlpack_pca, @c mlpack_radical, @c + mlpack_local_coordinate_coding, @c mlpack_sparse_coding, @c mlpack_nca, @c +mlpack_kernel_pca + + - Regression: @c mlpack_linear_regression, @c mlpack_lars + + - Preprocessing/other: @c mlpack_preprocess_binarize, @c + mlpack_preprocess_split, @c mlpack_preprocess_describe, @c + mlpack_preprocess_imputer, @c mlpack_nmf + +For more information on what mlpack does, see http://www.mlpack.org/about.html. +Next, let's go through another example for providing movie recommendations with +mlpack. + +@section cli_quickstart_movierecs Using mlpack for movie recommendations + +In this example, we'll train a collaborative filtering model using mlpack's +@c mlpack_cf program. We'll train this on the MovieLens dataset from +https://grouplens.org/datasets/movielens/, and then we'll use the model that we +train to give recommendations. + +You can copy-paste this code directly into the command line to run it. + +@code +wget http://www.mlpack.org/datasets/ml-20m/ratings-only.csv.gz +wget http://www.mlpack.org/datasets/ml-20m/movies.csv.gz +gunzip ratings-only.csv.gz +gunzip movies.csv.gz + +# Hold out 10% of the dataset into a test set so we can evaluate performance. +mlpack_preprocess_split \ + --input_file ratings-only.csv \ + --training_file ratings-train.csv \ + --test_file ratings-test.csv \ + --test_ratio 0.1 \ + --verbose + +# Train the model. Change the rank to increase/decrease the complexity of the +# model. +mlpack_cf \ + --training_file ratings-train.csv \ + --test_file ratings-test.csv \ + --rank 10 \ + --algorithm RegSVD \ + --output_model_file cf-model.bin \ + --verbose + +# Now query the 5 top movies for user 1. +echo "1" > query.csv; +mlpack_cf \ + --input_model_file cf-model.bin \ + --query_file query.csv \ + --recommendations 10 \ + --output_file recommendations.csv \ + --verbose + +# Get the names of the movies for user 1. +echo "Recommendations for user 1:" +for i in `seq 1 10`; do + item=`cat recommendations.csv | awk -F',' '{ print $'$i' }'`; + head -n $(($item + 2)) movies.csv | tail -1 | \ + sed 's/^[^,]*,[^,]*,//' | \ + sed 's/\(.*\),.*$/\1/' | sed 's/"//g'; +done +@endcode + +Here is some example output, showing that user 1 seems to have good taste in +movies: + +@code +Recommendations for user 1: +Casablanca (1942) +Pan's Labyrinth (Laberinto del fauno, El) (2006) +Godfather, The (1972) +Answer This! (2010) +Life Is Beautiful (La Vita è bella) (1997) +Adventures of Tintin, The (2011) +Dark Knight, The (2008) +Out for Justice (1991) +Dr. Strangelove or: How I Learned to Stop Worrying and Love the Bomb (1964) +Schindler's List (1993) +@endcode + +@section cli_quickstart_nextsteps Next steps with mlpack + +Now that you have done some simple work with mlpack, you have seen how it can +easily plug into a data science production workflow for the command line. A +great thing to do next would be to look at more documentation for the mlpack +command-line programs: + + - mlpack + command-line program documentation + +Also, mlpack is much more flexible from C++ and allows much greater +functionality. So, more complicated tasks are possible if you are willing to +write C++. To get started learning about mlpack in C++, the following resources +might be helpful: + + - mlpack + C++ tutorials + - mlpack + build and installation guide + - Simple + sample C++ mlpack programs + - mlpack + Doxygen documentation homepage + + */ diff --git a/doc/guide/python_quickstart.hpp b/doc/guide/python_quickstart.hpp new file mode 100644 index 0000000000..6dfa38d6f3 --- /dev/null +++ b/doc/guide/python_quickstart.hpp @@ -0,0 +1,198 @@ +/** + * @file python_quickstart.hpp + * @author Ryan Curtin + * @brief Quickstart documentation for mlpack usage from Python + +@page python_quickstart mlpack in Python quickstart guide + +This page describes how you can quickly get started using mlpack from Python and +gives a few examples of usage, and pointers to deeper documentation. + +This quickstart guide is also available for @ref cli_quickstart "the command-line". + +@section python_quickstart_install Installing mlpack + +(This section will be simplified when mlpack is available in PyPI or conda.) + +Installing the mlpack bindings for Python is straightforward. First we have to +install the dependencies (the code below is for Ubuntu), then we can build and +install mlpack. + +@code +$ sudo apt-get install libboost-all-dev g++ cmake libarmadillo-dev python-pip wget +$ sudo pip install cython setuptools distutils numpy pandas +$ wget http://www.mlpack.org/files/mlpack-3.0.0.tar.gz +$ tar -xvzpf mlpack-3.0.0.tar.gz +$ mkdir -p mlpack-3.0.0/build/ && cd mlpack-3.0.0/build/ +$ cmake ../ && make -j4 && sudo make install +@endcode + +@section python_quickstart_example Simple mlpack quickstart example + +As a really simple example of how to use mlpack from Python, let's do some +simple classification on a subset of the standard machine learning @c covertype +dataset. We'll first split the dataset into a training set and a testing set, +then we'll train an mlpack random forest on the training data, and finally we'll +print the accuracy of the random forest on the test dataset. + +You can copy-paste this code directly into Python to run it. + +@code +import mlpack +import pandas as pd +import numpy as np + +# Load the dataset from an online URL. Replace with 'covertype.csv.gz' if you +# want to use on the full dataset. +df = pd.read_csv('http://www.mlpack.org/datasets/covertype-small.csv.gz') + +# Split the labels. +labels = df['label'] +dataset = df.drop('label', 1) + +# Split the dataset using mlpack. The output comes back as a dictionary, +# which we'll unpack for clarity of code. +output = mlpack.preprocess_split(input=dataset, + input_labels=labels, + test_ratio=0.3) +training_set = output['training'] +training_labels = output['training_labels'] +test_set = output['test'] +test_labels = output['test_labels'] + +# Train a random forest. +output = mlpack.random_forest(training=training_set, + labels=training_labels, + print_training_accuracy=True, + num_trees=10, + minimum_leaf_size=3) +random_forest = output['output_model'] + +# Predict the labels of the test points. +output = mlpack.random_forest(input_model=random_forest, + test=test_set) + +# Now print the accuracy. The 'probabilities' output could also be used +# to generate an ROC curve. +correct = np.sum(output['predictions'] == test_labels) +print(str(correct) + ' correct out of ' + str(len(test_labels)) + ' (' + + str(100 * float(correct) / float(len(test_labels))) + '%).') +@endcode + +We can see that we achieve reasonably good accuracy on the test dataset (80%+); +if we use the full @c covertype.csv.gz, the accuracy should increase +significantly (but training will take longer). + +It's easy to modify the code above to do more complex things, or to use +different mlpack learners, or to interface with other machine learning toolkits. + +@section python_quickstart_whatelse What else does mlpack implement? + +The example above has only shown a little bit of the functionality of mlpack. +Lots of other commands are available with different functionality. Below is a +list of all the mlpack functionality offered through Python, split into some +categories. + + - Classification techniques: @c adaboost(), @c decision_stump(), @c decision_tree(), @c hmm_train(), @c hmm_generate(), @c hmm_loglik(), @c hmm_viterbi(), @c hoeffding_tree(), @c logistic_regression(), @c nbc(), @c perceptron(), @c random_forest(), @c softmax_regression(), @c cf() + + - Distance-based problems: @c approx_kfn(), @c emst(), @c fastmks(), @c kfn(), @c knn(), @c krann(), @c lsh(), @c det() + + - Clustering: @c kmeans(), @c mean_shift(), @c gmm_train(), @c gmm_generate(), @c gmm_probability() + + - Transformations: @c pca(), @c radical(), @c local_coordinate_coding(), @c sparse_coding(), @c nca(), @c kernel_pca() + + - Regression: @c linear_regression(), @c lars() + + - Preprocessing/other: @c preprocess_binarize(), @c preprocess_split(), @c preprocess_describe(), @c nmf() + +For more information on what mlpack does, see http://www.mlpack.org/about.html. +Next, let's go through another example for providing movie recommendations with +mlpack. + +@section python_quickstart_movierecs Using mlpack for movie recommendations + +In this example, we'll train a collaborative filtering model using mlpack's +@c cf() method. We'll train this on the MovieLens dataset from +https://grouplens.org/datasets/movielens/, and then we'll use the model that we +train to give recommendations. + +You can copy-paste this code directly into Python to run it. + +@code +import mlpack +import pandas as pd +import numpy as np + +# First, load the MovieLens dataset. This is taken from files.grouplens.org/ +# but reposted on mlpack.org as unpacked and slightly preprocessed data. +ratings = pd.read_csv('http://www.mlpack.org/datasets/ml-20m/ratings-only.csv.gz') +movies = pd.read_csv('http://www.mlpack.org/datasets/ml-20m/movies.csv.gz') + +# Hold out 10% of the dataset into a test set so we can evaluate performance. +output = mlpack.preprocess_split(input=ratings, test_ratio=0.1, verbose=True) +ratings_train = output['training'] +ratings_test = output['test'] + +# Train the model. Change the rank to increase/decrease the complexity of the +# model. +output = mlpack.cf(training=ratings_train, + test=ratings_test, + rank=10, + verbose=True, + algorithm='RegSVD') +cf_model = output['output_model'] + +# Now query the 5 top movies for user 1. +output = mlpack.cf(input_model=cf_model, + query=[[1]], + recommendations=10, + verbose=True) + +# Get the names of the movies for user 1. +print("Recommendations for user 1:") +for i in range(10): + print(" " + str(i) + ": " + str(movies.loc[movies['movieId'] == + output['output'][0, i]].iloc[0]['title'])) +@endcode + +Here is some example output, showing that user 1 seems to have good taste in +movies: + +@code +Recommendations for user 1: + 0: Casablanca (1942) + 1: Pan's Labyrinth (Laberinto del fauno, El) (2006) + 2: Godfather, The (1972) + 3: Answer This! (2010) + 4: Life Is Beautiful (La Vita è bella) (1997) + 5: Adventures of Tintin, The (2011) + 6: Dark Knight, The (2008) + 7: Out for Justice (1991) + 8: Dr. Strangelove or: How I Learned to Stop Worrying and Love the Bomb (1964) + 9: Schindler's List (1993) +@endcode + +@section python_quickstart_nextsteps Next steps with mlpack + +Now that you have done some simple work with mlpack, you have seen how it can +easily plug into a data science workflow in Python. A great thing to do next +would be to look at more documentation for the Python mlpack bindings: + + - Python mlpack + binding documentation + +Also, mlpack is much more flexible from C++ and allows much greater +functionality. So, more complicated tasks are possible if you are willing to +write C++ (or perhaps Cython). To get started learning about mlpack in C++, the +following resources might be helpful: + + - mlpack + C++ tutorials + - mlpack + build and installation guide + - Simple + sample C++ mlpack programs + - mlpack + Doxygen documentation homepage + + */