README for icb  -- inverse cumulative binomial distribution

(c) Mark Johnson, 5th September 2000
    Brown University
    Email: Mark_Johnson@Brown.edu
    Web: http://www.cog.brown.edu/~mj

The program(s) distributed with this file are made available freely
for research purposes only.  Please contact me if you are interested
in commercial application.  I request acknowledgement if results from
this program or a program derived from this code appears in a
publication.

                                NO WARRANTY

BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT
WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO
LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED
OF THE POSSIBILITY OF SUCH DAMAGES.


Routines from the CEPHES library:
================================

The files incbi.c incbet.c gamma.c polevl.c const.c mtherr.c ndtri.c
are part of the freely distributed CEPHES library.


Compilation:
===========

The programs here are written in ANSI C, and should compile with any
standard C compiler.  It should only be necessary to run "make".


Usage:
=====

	icb alpha

Alpha, the significance level, should be a real number greater than
zero and less than one.  A typical value is 0.025.

The program reads lines from standard input and writes an equal number
of lines to standard output.  Each input line should begin with a
ratio of positive integers r/n.  It must be the case that n>=r>=0 and
n>=1.  The program copies each input line to the output, prepending a
real number p to the line, which satisfies:

	alpha = sum_{i=k}^n binomial(n,i) p^i (1-p)^(n-i) 

It does this by computing the inverse incomplete Beta function I_p,
which is related to the cumulative binomial via the equation

	I_p(k,n-k+1) = sum_{i=k}^n binomial(n,i) p^i (1-p)^(n-i) 


Example:
=======

Suppose the input file sample.dat contains:

	5/10 sample1
	40/100 sample2
	300/1000 sample3

Then running

	icb 0.1 < in.dat

produces as output
	
	0.267318        5/10     sample1
	0.334237        40/100   sample2
	0.281234        300/1000 sample3

The number on the left is a ``discounted probability'' of success.
This score is higher for sample2, even though the maximum likelihood
probability for sample1 is higher.

As alpha becomes smaller, the score becomes more conservative.  Thus

	icb 0.001 < sample.dat

produces

	0.089813        5/10     sample1
	0.254536        40/100   sample2
	0.256185        300/1000 sample3

The Unix sort command can be used to sort the output of the icb program
so that the highest scoring samples come first.

	icb 0.001 < sample.dat | sort -k1,1 -nr

produces

	0.256185        300/1000 sample3
	0.254536        40/100   sample2
	0.089813        5/10     sample1
