function observed_successes=BTP_LoLN( num_trials, prob_succ, slow_down)
%BTP_LoLN runs a BTP num_trials times, and demonstrates the LoLN
%   variables are as follows: num_trials is the number of trials you want
%   to run the BTP, prob_success is the probability of "success" at any
%   given stage of the BTP, slow_down is a function-specific variable that
%   slows down the function to allow the user to see the experiment being
%   performed; the variable is in SECONDS and tells the computer to wait
%   that much time before performing the next stage of the BTP

%assures we have an integer. if the user is thinking, this doesn't need to
%be here.
num_trials=round(num_trials);

%intitializes a variable to hold the actual trial observations
observation=zeros(1,num_trials);

%a vector that stores the possible outcomes of the trials (0 to num_succ
%successes
possible_outcomes=0:num_trials;

%vector possible_outcomes expresses as a fraction of the total number of
%possible successes
mean_succ_fail=possible_outcomes./num_trials;

%the binomial distribution for the experiment -- b(num_trials,prob_succ,j)
distribution=binopdf(possible_outcomes,num_trials,prob_succ);


%we now perform the experiment and keep track of the number of success as
%we go along. we plot the experiment as it goes
for i=1:num_trials

    %because of some code technicalities, we have to replot the
    %distribution each time
figure(1); plot(mean_succ_fail, distribution,'r+');
hold on

%this generates an actual observation from the BTP
observation(i)=binornd(1,prob_succ);

%just prints the observation and the trial number for reference
observation(i)
trial=i

%if we stopped here, this is the fraction of success that were successes.
%NOTE WELL: if the BTP has not completed, this will DEFINITELY be too low
%because it counts all the zeros of the trials not performed yet
observed_pvalue=mean(observation);

%this is just some code to make a vector out of the above data for display.
%only coders might be interested in this. don't worry about this at all.
observed_p_value_vec=zeros(1,num_trials+1);
observed_p_value_vec(mean_succ_fail==observed_pvalue)=distribution(mean_succ_fail==observed_pvalue);
observed_p_value_vec(mean_succ_fail~=observed_pvalue)=NaN;

%plots the data that we generated at the start of the for loop (and put into a better variable for
%plotting in the above code block)
figure(1); plot(mean_succ_fail,observed_p_value_vec,'rs','MarkerEdgeColor','k',...
                'MarkerFaceColor','g','MarkerSize',12);

%coder stuff            
hold off

%trial=i

%pauses the experiment for a (hopefully) fraction of a second to let the
%figure display, and give the user a chance to watch the experiment unfold.
pause(slow_down)

end

%returns the actual number of successes in this BTP
observed_successes=sum(observation);
end

