updating-accessing.lisp 5.14 KB
Newer Older
liam's avatar
liam committed
1 2
;; Updating and accessing histogram elements.
;; Liam Healy, Mon Jan  1 2007 - 14:43
Liam Healy's avatar
Liam Healy committed
3
;; Time-stamp: <2008-10-25 18:24:41EDT updating-accessing.lisp>
lhealy's avatar
lhealy committed
4
;; $Id$
liam's avatar
liam committed
5 6 7

(in-package :gsl)

Liam Healy's avatar
Liam Healy committed
8
(defmfun increment (histogram value &optional weight)
Liam Healy's avatar
Liam Healy committed
9 10 11 12 13
  ("gsl_histogram_increment" "gsl_histogram_accumulate")
  ((((mpointer histogram) :pointer) (value :double))
   (((mpointer histogram) :pointer) (value :double) (weight :double)))
  :documentation
  "Update the histogram by adding the weight
liam's avatar
liam committed
14
   (which defaults to 1.0) to the
liam's avatar
liam committed
15
   bin whose range contains the coordinate x. 
liam's avatar
liam committed
16

liam's avatar
liam committed
17 18 19 20
   If x lies in the valid range of the histogram then the function
   returns zero to indicate success.  If x is less than the lower
   limit of the histogram then the function issues a warning :EDOM, and
   none of bins are modified.  Similarly, if the value of x is greater
liam's avatar
liam committed
21
   than or equal to the upper limit of the histogram then the function
liam's avatar
liam committed
22
   issues a warning :EDOM, and none of the bins are modified.  The error
liam's avatar
liam committed
23 24 25 26
   handler is not called, however, since it is often necessary to compute
   histograms for a small range of a larger dataset, ignoring the values
   outside the range of interest.")

27
(defmfun maref ((histogram histogram) i &optional i2 element-type)
liam's avatar
liam committed
28
  "gsl_histogram_get"
Liam Healy's avatar
Liam Healy committed
29
  (((mpointer histogram) :pointer) (i sizet))
Liam Healy's avatar
Liam Healy committed
30
  :definition :method 
liam's avatar
liam committed
31
  :c-return :double
liam's avatar
liam committed
32 33 34 35
  :documentation			; FDL
  "Return the contents of the i-th bin of the histogram.
   If i lies outside the valid range of indices for the
   histogram then an error (:EDOM) is signalled.")
liam's avatar
liam committed
36

liam's avatar
liam committed
37
(defmfun range (histogram i)
liam's avatar
liam committed
38
  "gsl_histogram_get_range"
39
  (((mpointer histogram) :pointer) (i sizet)
liam's avatar
liam committed
40
   (lower :double) (upper :double))
liam's avatar
liam committed
41 42 43 44
  :documentation			; FDL
  "Find the upper and lower range limits of the i-th
   bin of the histogram.  If the index i is valid then the
   corresponding range limits are stored in lower and upper.
liam's avatar
liam committed
45 46 47 48
   The lower limit is inclusive (i.e. events with this coordinate are
   included in the bin) and the upper limit is exclusive (i.e. events with
   the coordinate of the upper limit are excluded and fall in the
   neighboring higher bin, if it exists).
liam's avatar
liam committed
49 50
   If i lies outside the valid range of indices for
   the histogram, then the error :EDOM is signalled.")
liam's avatar
liam committed
51

Liam Healy's avatar
Liam Healy committed
52
(defmfun max-range (histogram)
liam's avatar
liam committed
53
  "gsl_histogram_max"
54
  (((mpointer histogram) :pointer))
liam's avatar
liam committed
55
  :c-return :double
liam's avatar
liam committed
56
  :documentation			; FDL
liam's avatar
liam committed
57 58
  "The maximum upper range limit of the histogram.")

Liam Healy's avatar
Liam Healy committed
59
(defmfun min-range (histogram)
liam's avatar
liam committed
60
  "gsl_histogram_min"
61
  (((mpointer histogram) :pointer))
liam's avatar
liam committed
62
  :c-return :double
liam's avatar
liam committed
63
  :documentation			; FDL
liam's avatar
liam committed
64 65
  "The minimum lower range limit of the histogram.")

liam's avatar
liam committed
66
(defmfun bins (histogram)
liam's avatar
liam committed
67
  "gsl_histogram_bins"
68 69
  (((mpointer histogram) :pointer))
  :c-return sizet
liam's avatar
liam committed
70
  :documentation			; FDL
liam's avatar
liam committed
71 72
  "The number of bins in the histogram.")

liam's avatar
liam committed
73
(defmfun reset (histogram)
liam's avatar
liam committed
74
  "gsl_histogram_reset"
75
  (((mpointer histogram) :pointer))
liam's avatar
liam committed
76
  :c-return :void
liam's avatar
liam committed
77
  :documentation			; FDL
liam's avatar
liam committed
78 79
  "Reset all the bins in the histogram to zero.")

Liam Healy's avatar
Liam Healy committed
80 81 82 83 84
(defmfun histogram-find (histogram x-value &optional y-value)
  ("gsl_histogram_find" "gsl_histogram2d_find")
  ((((mpointer histogram) :pointer) (x-value :double) (bin sizet))
   (((mpointer histogram) :pointer) (x-value :double) (y-value :double)
   (xbin sizet) (ybin sizet)))
liam's avatar
liam committed
85
  :documentation			; FDL
liam's avatar
liam committed
86 87 88 89 90 91
  "Finds the bin number which covers the coordinate value in
   the histogram.  The bin is located using a binary search. The
   search includes an optimization for histograms with uniform
   range, and will return the correct bin immediately in this
   case.  If the value is found in the range of the histogram
   then the function returns the index.  If value lies outside
liam's avatar
liam committed
92
   the valid range of the histogram then the error :EDOM is
liam's avatar
liam committed
93 94
   signalled.")

Liam Healy's avatar
Liam Healy committed
95
#|
96 97 98
 (letm ((histo (histogram 10)))		; should be a gsl-warning here, how to check?
     (set-ranges-uniform histo 0.0d0 10.0d0)
     (increment histo -2.0d0))
Liam Healy's avatar
Liam Healy committed
99
|#
100
;;; Examples and unit test
liam's avatar
liam committed
101

Liam Healy's avatar
Liam Healy committed
102
(save-test histogram
103 104 105
   ;; The first one gives a warning while compiling in SBCL,
   ;; should only give a warning while runnin.
 (letm ((histo (histogram 10)))
106
     (set-ranges-uniform histo 0.0d0 10.0d0)
liam's avatar
liam committed
107 108 109 110 111
     (increment histo -2.0d0))
 (letm ((histo (histogram 10)))
   (set-ranges-uniform histo 0.0d0 10.0d0)
   (increment histo 2.7d0)
   (increment histo 6.9d0 2.0d0)
112
   (maref histo 1))
liam's avatar
liam committed
113 114 115 116
 (letm ((histo (histogram 10)))
   (set-ranges-uniform histo 0.0d0 10.0d0)
   (increment histo 2.7d0)
   (increment histo 6.9d0 2.0d0)
117
   (maref histo 2))
liam's avatar
liam committed
118 119 120 121
 (letm ((histo (histogram 10)))
   (set-ranges-uniform histo 0.0d0 10.0d0)
   (increment histo 2.7d0)
   (increment histo 6.9d0 2.0d0)
122
   (maref histo 6))
liam's avatar
liam committed
123 124 125 126
 (letm ((histo (histogram 10)))
   (set-ranges-uniform histo 0.0d0 10.0d0)
   (increment histo 2.7d0)
   (increment histo 6.9d0 2.0d0)
127
   (maref histo 16))
liam's avatar
liam committed
128 129 130 131
 (letm ((histo (histogram 10)))
   (set-ranges-uniform histo 0.0d0 10.0d0)
   (increment histo 2.7d0)
   (increment histo 6.9d0 2.0d0)
Liam Healy's avatar
Liam Healy committed
132
   (values (min-range histo) (max-range histo)))
liam's avatar
liam committed
133 134 135 136 137 138 139 140 141 142
 (letm ((histo (histogram 10)))
   (set-ranges-uniform histo 0.0d0 10.0d0)
   (increment histo 2.7d0)
   (increment histo 6.9d0 2.0d0)
   (bins histo))
 (letm ((histo (histogram 10)))
   (set-ranges-uniform histo 0.0d0 10.0d0)
   (increment histo 2.7d0)
   (increment histo 6.9d0 2.0d0)
   (histogram-find histo 5.5d0)))