\documentclass[11pt]{article}
\usepackage{geometry}                % See geometry.pdf to learn the layout options. There are lots.
\geometry{letterpaper}                   % ... or a4paper or a5paper or ...
%\geometry{landscape}                % Activate for for rotated page geometry
%\usepackage[parfill]{parskip}    % Activate to begin paragraphs with an empty line rather than an indent
\usepackage{graphicx}
\usepackage{amssymb}
\usepackage{epstopdf}
\usepackage{url}
\usepackage{verbatim}
\usepackage{moreverb}
\usepackage{color}
\let\verbatiminput=\verbatimtabinput
\def\verbatimtabsize{4\relax}
\DeclareGraphicsRule{.tif}{png}{.png}{`convert #1 `dirname #1`/`basename #1 .tif`.png}
\newcommand{\todo}[1]{\textcolor{red}{\huge{TODO: #1}}}

\title{10605 BigML Assignment 2:\\ Naive Bayes using GuineaPig}
\author{Due: Thursday, Sept. 29, 2016 23:59 EST via Autolab}
\iffalse
\date{Late submission with 50\% credit: Sunday, Mar. 2, 2014 23:59 EST via Autolab}
\fi
\begin{document}
\maketitle

\section*{Policy on Collaboration among Students}

These policies are the same as were used in Dr. Rosenfeld's previous version of 10601 from 2013. The purpose of student collaboration is to facilitate learning, not to circumvent it. Studying the material in groups is strongly encouraged. It is also allowed to seek help from other students in understanding the material needed to solve a particular homework problem, provided no written notes are shared, or are taken at that time, and provided learning is facilitated, not circumvented. The actual solution must be done by each student alone, and the student should be ready to reproduce their solution upon request. The presence or absence of any form of help or collaboration, whether given or received, must be explicitly stated and disclosed in full by all involved, on the first page of their assignment. Specifically, each assignment solution must start by answering the following questions in the report:

\begin{itemize}
\item Did you receive any help whatsoever from anyone in solving this assignment? Yes / No.
If you answered `yes', give full details: \underline{\hspace{3cm}} (e.g. ``Jane explained to me what is asked in Question 3.4'')
\item Did you give any help whatsoever to anyone in solving this assignment? Yes / No.
If you answered `yes', give full details: \underline{\hspace{3cm}} (e.g. ``I pointed Joe to section 2.3 to help him with Question 2''.
\end{itemize}

Collaboration without full disclosure will be handled severely, in compliance with CMU's Policy on Cheating and Plagiarism.
As a related point, some of the homework assignments used in this class may have been used in prior versions of this class, or in classes at other institutions. Avoiding the use of heavily tested assignments will detract from the main purpose of these assignments, which is to reinforce the material and stimulate thinking. Because some of these assignments may have been used before, solutions to them may be (or may have been) available online, or from other people. It is explicitly forbidden to use any such sources, or to consult people who have solved these problems before. You must solve the homework assignments completely on your own. I will mostly rely on your wisdom and honor to follow this rule, but if a violation is detected it will be dealt with harshly. Collaboration with other students who are currently taking the class is allowed, but only under the conditions stated below.

\section{Important Note}
In this assignment, {\bf you will be using Python}.\\\\
{\bf This assignment is worth 100 points}. In this assignment, you will have to create a Naive Bayes classifier that will run with GuineaPig on Python. \\\\
Lanxiao Xu (lanxiaox@andrew.cmu.edu) and Chenran Li (chenranl@andrew.cmu.edu) are the contact TAs for this assignment. Please post clarification questions to the Piazza, and the instructors can be reached at
the following email address: \textit{10605-Instructors@cs.cmu.edu}.

\section{Introduction}

In this part of the assignment, you need to implement the Naive Bayes algorithm in GuineaPig. Unlike the previous assignment, the goal is to implement a small-memory test algorithm for Naive Bayes - i.e, testing where the vocabulary and test data do not fit into memory. {\bf Note: some counts such as number of labels and vocabulary size cannot be pre-computed and used directly as parameters}

Below is a high-level sketch of the algorithm:
\begin{itemize}
    \item Generate event counts from the training data (this phase is identical to what you have already implemented)
    \item Convert the event counts to key-value pairs (k,v) where k is a word, and v is some representation of all the counts for that word.
    \item Generate requests for word counts from the test file, i.e. flatten the test documents into pairs(word,docId).
    \item Join the flattened test documents with the reorganized event counts.
    \item Group the joined result together so that you can classify the test documents.
\end{itemize}

\subsection{Introduction to GuineaPig}
GuineaPig is a lightweight Python library that is similar to Pig, but is easier to learn and debug. You are required to have some working knowledge of Python and Hadoop to be able to use GuineaPig. You will express your workflow using high level constructs (such as Join, Augment etc.) and GuineaPig spawns off MapReduce tasks behind the scenes to do the compute. GuineaPig provides for you a layer of abstraction over bare-bones Hadoop. You can find more information about GuineaPig (including a tutorial) at \url{http://curtis.ml.cmu.edu/w/courses/index.php/Guinea_Pig}. It is recommended that you read this document before proceeding with the assignment. You can directly download GuineaPig at \url{https://github.com/TeamCohen/GuineaPig/archive/master.zip} or work with source code distributed with the tutorial. \url{ http://curtis.ml.cmu.edu/w/courses/index.php/Guinea_Pig#Quick_Start}. 

\subsection{Local Execution}
In addition to providing an abstraction over Hadoop, GuineaPig programs can also be executed locally, without Hadoop. This feature makes your program much easier to debug. We recommend that you debug locally and test on Hadoop using the Stoat cluster before submitting.

\subsection{Using Hadoop on the Stoat cluster}
By now, you should all have access to Stoat, which already has an installation of Hadoop ready to use. You just need to copy GuineaPig, with your code, to the cluster:
\begin{verbatim}
scp -r /path/to/GuineaPig <username>@shell.stoat.pdl.local.cmu.edu:~
\end{verbatim}
You can SSH to Stoat from within CMU?s network:
\begin{verbatim}
ssh <username>@shell.stoat.pdl.local.cmu.edu
\end{verbatim}
In order to set up GuineaPig to execute on Hadoop, follow the instructions on the wiki: \url{http://curtis.ml.cmu.edu/w/courses/index.php/Guinea_Pig#Using_Hadoop}.


\section{The Data}
We are using the same dataset as the one in Homework 1. These are articles from DBPedia, and the label is the type of the article. There are in total 18 classes in the dataset, and they are from the first level class in DBpedia ontology. For more information about this dataset, you can refer to \url{http://wiki.dbpedia.org/Downloads2015-04}. The data is of the format:
\begin{verbatim}
<id>    <label1>,<label2>,<label3>...    w1 w2 w3 w4...
\end{verbatim}
The three columns are separated by tab, and the documents are preprocessed so that there are no tabs in the body.
You can find the data in \url{/afs/cs.cmu.edu/project/bigML/dbpedia_16fall/}.\\

\noindent
For this homework, feel free to play with the parameters, tokenizer and output to improve your Naive Bayes classifier.

\section{Deliverables}
At this point, you should be very familiar with Naive Bayes. In this assignment, you will implement Naive Bayes in GuineaPig, a library in Python that works with Hadoop and allows a scripting version of streaming algorithms.

\subsection{Autolab Implementation Details}
We have given you a starter file, nb.py, that contains some setup code. You should imple- ment Naive Bayes in this file, and it should handle both training and testing. We will test your code with the following command:
\begin{verbatim}
python nb.py --store output \\
    --params trainFile:path/to/train,testFile:path/to/test
\end{verbatim}
After running, you should store your final predictions in the ``output'' variable, which will then be stored in ``gpig\_views/output.gp'' by GuineaPig. The output file should be of the form
\begin{verbatim}
(id, prediction, probability)
(id, prediction, probability)
...
\end{verbatim}
output should be python tuples, where the first element is an id of type string, the second element is prediction of type string, and the third element is a probability of type float. You don't need to worry about the ordering of the output, as long as all the information is there.\\

\noindent
For the autograding, you don't need to worry about setting Python paths. Just assume that \verb|from guineapig import *| will work.\\

\noindent
You should look through the GuineaPig guide at\\ \url{http://curtis.ml.cmu.edu/w/courses/index.php/Guinea_Pig}. The wordcount example might be a good place to start.

\subsection{Report}
Submit your implementations via AutoLab. You should implement the algorithm by yourself instead of using any existing machine learning toolkit. You should upload your code (including all your function files) along with a \textbf{report}, which should solve the following questions:
\begin{enumerate}
\item Answer the questions in the collaboration policy on page 1.
\item (10 points) Using the Stoat cluster and the abstract.smaller dataset, run your code using parallel modes 1, 2, 4, and 8, and measure the runtime of each. Using parallel mode n, GuineaPig will use n reducers for each MapReduce task. In addition, it will use n mappers for every intermediate (uses only results from a previous MapReduce step) MapReduce step in an execution chain. The following command will run your code using parallel mode n:
\begin{verbatim}
python nb.py --store output \\
--opts target:hadoop,viewdir:/user/<username>/gpig_views,parallel:<n>
\end{verbatim}

\noindent
To measure the total runtime of your program, sum together the runtimes between each \verb|map 0% reduce 0% and map 100% reduce 100%| for each MapReduce task spawned. You may want to pipe the output to a file in order to save it.\\

(a) Plot the runtime of your experiments vs. the parallel mode used.\\
(b) A program is perfectly scalable when the runtime halves if the number of worker machines is doubled. List three reasons why your program might not achieve this ideal scalability.

\item (10 points) In this question, you will use GuineaPig to answer queries. Suppose we have a career dataset recording every position along each member's career. The format of the career dataset is as follows:

\textbf{data: (Id, [(positionId1, companyId1), (positionId2, companyId2), ...])}

where for each position the dataset stores the positionId and companyId. Note: a member can work for the same company but in different positions.

Now we have a query dataset providing a bunch of company pairs, for each pair of company, we want to know how many people have worked for both two companies. The format of the query dataset is as follows:

\textbf{query: (srcCompany, destCompany)}

where the company pairs in the query dataset are unordered and unique. \\
Please write down the GuineaPig commands needed to answer the queries. In this question, you're not allowed to write supporting functions. GuineaPig basic commands are sufficient.

\item (10 points) Consider the following sequence of GuineaPig commands:
\begin{verbatim}
def flat1(tokens):
    for w in tokens:
        if w.isalpha():
            yield w

def flat2(tokens):
    for w in tokens:
        if not w.isalpha():
            yield re.sub("[^a-zA-Z]+", "", w) #regex substitution

data = ReadLines(`data.txt') \
| Map(by = lambda line : line.strip().split(' '))
t1 = FlatMap(data, by = flat1)
t2 = FlatMap(data, by = flat2)
t3 = Join(Jin(t1), Jin(t2)) | Map(by = lambda(w1, w2) : w2)
\end{verbatim}
View t3 will contain tokens from data.txt. In one sentence, describe these tokens.
\end{enumerate}


\section{Submission}
You must submit your homework through Autolab. You submit a tar file that contains nb.py, as well as a pdf containing your answers to the report questions.
In this homework, there will be a validation link.
\begin{itemize}
    \item HW2 - validation: You will be notified by Autolab if you can successfully finish your job on the Autolab virtual machines. Note that this is \textbf{not} the place you should debug or develop your algorithm. All development should be done on your local computer or Stoat machines. There will be \textbf{NO} feedback on your \textbf{performance} in the validation. You have unlimited amount of submissions here. To avoid Autolab queues on the submission day, the validation link may be closed 24 hours prior to the official deadline. If you have received a score of 1000 with no errors, this means that you code has passed the validation.
    \item HW2 - NB with GuineaPig: This is where you should submit your tar ball. You have a total of \textbf{10 possible submissions}. Your score will be reported, and feedback will be provided immediately.
\end{itemize}


\section{Grading}
You will be graded on memory, efficiency and accuracy. You will receive 15 for memory based on your peak memory usage through your run. For efficiency, we will time your code and assign a score out of 15. For accuracy, we will be testing your implementation against a hidden training and testing set on Autolab and assigned a score out of 25. In this assignment, we do not want you to load any of the datasets into memory. All data should be streamed through GuineaPig, and high memory usage will be penalized.

\end{document}