Class: Numo::GSL::Histogram

Inherits:
Object
  • Object
show all
Defined in:
ext/numo/gsl/histogram/gsl_histogram.c

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.new(n) ⇒ Object

allocate instance of Histogram class.

This function allocates memory for a histogram with n bins, and returns a pointer to a newly created gsl_histogram struct. If insufficient memory is available a null pointer is returned and the error handler is invoked with an error code of GSL_ENOMEM. The bins and ranges are not initialized, and should be prepared using one of the range-setting functions below in order to make the histogram ready for use.

Parameters:

  • n (Integer) —

    parameter



164
165
166
167
168
169
170
171
172
173
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 164

static VALUE
histogram_s_new(VALUE self, VALUE v1)
{
    gsl_histogram *w;
    w = gsl_histogram_alloc(NUM2SIZET(v1));
    if (!w) {
        rb_raise(rb_eNoMemError,"fail to allocate struct");
    }
    return TypedData_Wrap_Struct(cHistogram, &histogram_data_type, (void*)w);
}

Instance Method Details

#accumulate(x, weight) ⇒ Histogram

This function is similar to gsl_histogram_increment but increases the value of the appropriate bin in the histogram h by the floating-point number weight.

Parameters:

  • x (DFloat)
  • weight (DFloat)

Returns:



363
364
365
366
367
368
369
370
371
372
373
374
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 363

static VALUE
histogram_accumulate(VALUE self, VALUE v1, VALUE v2)
{
    gsl_histogram *w;
    ndfunc_arg_in_t ain[2] = {{cDF,0},{cDF,0}};
    ndfunc_t ndf = {iter_histogram_accumulate, STRIDE_LOOP, 2,0, ain,0};

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    na_ndloop3(&ndf, w, 2, v1, v2);
    return self;
}

#add(h2) ⇒ Bool

This function adds the contents of the bins in histogram h2 to the corresponding bins of histogram h1, i.e. h’_1(i) = h_1(i) + h_2(i). The two histograms must have identical bin ranges.

Parameters:

Returns:

  • (Bool) 


743
744
745
746
747
748
749
750
751
752
753
754
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 743

static VALUE
histogram_add(VALUE self, VALUE v1)
{
    int stat;
    gsl_histogram *w, *w1;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);
    TypedData_Get_Struct(v1, gsl_histogram, &histogram_data_type, w1);

    stat = gsl_histogram_add(w, w1);
    return (stat) ? Qtrue: Qfalse;
}

#bin ⇒ DFloat

returns bin field in gsl_histogram struct.

Returns:

  • (DFloat) —

    narray of bin field in gsl_histogram.



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 125

static VALUE
histogram_bin(VALUE self)
{
    gsl_histogram *w;
    double *d;
    VALUE v;
    size_t n, i, shape[1];

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    
    shape[0] = n = w->n;
    

    v = rb_narray_new(cDF, 1, shape);
    d = (double*)na_get_pointer_for_write(v);
    for (i=0; i<n; i++) {
        d[i] = w->bin[i];
    }
    return v;
}

#bins ⇒ Integer

These functions return the maximum upper and minimum lower range limits and the number of bins of the histogram h. They provide a way of determining these values without accessing the gsl_histogram struct directly.

Returns:

  • (Integer) 


544
545
546
547
548
549
550
551
552
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 544

static VALUE
histogram_bins(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return SIZET2NUM(gsl_histogram_bins(w));
}

#div(h2) ⇒ Bool

This function divides the contents of the bins of histogram h1 by the contents of the corresponding bins in histogram h2, i.e. h’_1(i) = h_1(i) / h_2(i). The two histograms must have identical bin ranges.

Parameters:

Returns:

  • (Bool) 


817
818
819
820
821
822
823
824
825
826
827
828
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 817

static VALUE
histogram_div(VALUE self, VALUE v1)
{
    int stat;
    gsl_histogram *w, *w1;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);
    TypedData_Get_Struct(v1, gsl_histogram, &histogram_data_type, w1);

    stat = gsl_histogram_div(w, w1);
    return (stat) ? Qtrue: Qfalse;
}

#equal_bins_p(h2) ⇒ Bool

This function returns 1 if the all of the individual bin ranges of the two histograms are identical, and 0 otherwise.

Parameters:

Returns:

  • (Bool) 


719
720
721
722
723
724
725
726
727
728
729
730
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 719

static VALUE
histogram_equal_bins_p(VALUE self, VALUE v1)
{
    int stat;
    gsl_histogram *w, *w1;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);
    TypedData_Get_Struct(v1, gsl_histogram, &histogram_data_type, w1);

    stat = gsl_histogram_equal_bins_p(w, w1);
    return (stat) ? Qtrue: Qfalse;
}

#get(i) ⇒ Histogram

This function returns the contents of the i-th bin of the histogram h. If i lies outside the valid range of indices for the histogram then the error handler is called with an error code of GSL_EDOM and the function returns 0.

Parameters:

  • i (Int32/64)

Returns:



416
417
418
419
420
421
422
423
424
425
426
427
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 416

static VALUE
histogram_get(VALUE self, VALUE v1)
{
    gsl_histogram *w;
    ndfunc_arg_in_t ain[1] = {{cSSZ,0}};
    ndfunc_arg_out_t aout[1] = {{cDF,0}};
    ndfunc_t ndf = {iter_histogram_get, STRIDE_LOOP|NDF_EXTRACT, 1,1, ain,aout};

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return na_ndloop3(&ndf, w, 1, v1);
}

#get_range(i) ⇒ Array

This function finds the upper and lower range limits of the i-th bin of the histogram h. If the index i is valid then the corresponding range limits are stored in lower and upper. 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). The function returns 0 to indicate success. If i lies outside the valid range of indices for the histogram then the error handler is called and the function returns an error code of GSL_EDOM.

Parameters:

  • i (Int32/64) —

    Int32/64 NArray

Returns:

  • (Array) —

    array of [[DFloat] lower, [DFloat] upper]



478
479
480
481
482
483
484
485
486
487
488
489
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 478

static VALUE
histogram_get_range(VALUE self, VALUE v1)
{
    gsl_histogram *w;
    ndfunc_arg_in_t ain[1] = {{cSSZ,0}};
    ndfunc_arg_out_t aout[2] = {{cDF,0},{cDF,0}};
    ndfunc_t ndf = {iter_histogram_get_range, STRIDE_LOOP|NDF_EXTRACT, 1,2, ain,aout};

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return na_ndloop3(&ndf, w, 1, v1);
}

#increment(x) ⇒ Histogram

This function updates the histogram h by adding one (1.0) to the bin whose range contains the coordinate x.

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 returns GSL_EDOM, and none of bins are modified. Similarly, if the value of x is greater than or equal to the upper limit of the histogram then the function returns GSL_EDOM, and none of the bins are modified. The error 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.

Parameters:

  • x (DFloat)

Returns:



317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 317

static VALUE
histogram_increment(VALUE self, VALUE v1)
{
    gsl_histogram *w;
    ndfunc_arg_in_t ain[1] = {{cDF,0}};
    ndfunc_t ndf = {iter_histogram_increment, FULL_LOOP, 1,0, ain,0};

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    na_ndloop3(&ndf, w, 1, v1);
    return self;
}

#max ⇒ Float

These functions return the maximum upper and minimum lower range limits and the number of bins of the histogram h. They provide a way of determining these values without accessing the gsl_histogram struct directly.

Returns:

  • (Float) 


502
503
504
505
506
507
508
509
510
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 502

static VALUE
histogram_max(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return DBL2NUM(gsl_histogram_max(w));
}

#max_bin ⇒ Integer

This function returns the index of the bin containing the maximum value. In the case where several bins contain the same maximum value the smallest index is returned.

Returns:

  • (Integer) 


599
600
601
602
603
604
605
606
607
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 599

static VALUE
histogram_max_bin(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return SIZET2NUM(gsl_histogram_max_bin(w));
}

#max_val ⇒ Float

This function returns the maximum value contained in the histogram bins.

Returns:

  • (Float) 


579
580
581
582
583
584
585
586
587
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 579

static VALUE
histogram_max_val(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return DBL2NUM(gsl_histogram_max_val(w));
}

#mean ⇒ Float

This function returns the mean of the histogrammed variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation. The accuracy of the result is limited by the bin width.

Returns:

  • (Float) 


658
659
660
661
662
663
664
665
666
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 658

static VALUE
histogram_mean(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return DBL2NUM(gsl_histogram_mean(w));
}

#memcpy(src) ⇒ Bool

This function copies the histogram src into the pre-existing histogram dest, making dest into an exact copy of src. The two histograms must be of the same size.

Parameters:

Returns:

  • (Bool) 


257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 257

static VALUE
histogram_memcpy(VALUE self, VALUE v1)
{
    int stat;
    gsl_histogram *w, *w1;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);
    TypedData_Get_Struct(v1, gsl_histogram, &histogram_data_type, w1);

    stat = gsl_histogram_memcpy(w, w1);
    return (stat) ? Qtrue: Qfalse;
}

#min ⇒ Float

These functions return the maximum upper and minimum lower range limits and the number of bins of the histogram h. They provide a way of determining these values without accessing the gsl_histogram struct directly.

Returns:

  • (Float) 


523
524
525
526
527
528
529
530
531
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 523

static VALUE
histogram_min(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return DBL2NUM(gsl_histogram_min(w));
}

#min_bin ⇒ Integer

This function returns the index of the bin containing the minimum value. In the case where several bins contain the same maximum value the smallest index is returned.

Returns:

  • (Integer) 


637
638
639
640
641
642
643
644
645
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 637

static VALUE
histogram_min_bin(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return SIZET2NUM(gsl_histogram_min_bin(w));
}

#min_val ⇒ Float

This function returns the minimum value contained in the histogram bins.

Returns:

  • (Float) 


617
618
619
620
621
622
623
624
625
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 617

static VALUE
histogram_min_val(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return DBL2NUM(gsl_histogram_min_val(w));
}

#mul(h2) ⇒ Bool

This function multiplies the contents of the bins of histogram h1 by the contents of the corresponding bins in histogram h2, i.e. h’_1(i) = h_1(i) * h_2(i). The two histograms must have identical bin ranges.

Parameters:

Returns:

  • (Bool) 


792
793
794
795
796
797
798
799
800
801
802
803
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 792

static VALUE
histogram_mul(VALUE self, VALUE v1)
{
    int stat;
    gsl_histogram *w, *w1;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);
    TypedData_Get_Struct(v1, gsl_histogram, &histogram_data_type, w1);

    stat = gsl_histogram_mul(w, w1);
    return (stat) ? Qtrue: Qfalse;
}

#n ⇒ Integer

returns n field in gsl_histogram struct.

Returns:

  • (Integer) 


75
76
77
78
79
80
81
82
83
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 75

static VALUE
histogram_n(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return SIZET2NUM(w->n);
}

#range ⇒ DFloat

returns range field in gsl_histogram struct.

Returns:

  • (DFloat) —

    narray of range field in gsl_histogram.



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 94

static VALUE
histogram_range(VALUE self)
{
    gsl_histogram *w;
    double *d;
    VALUE v;
    size_t n, i, shape[1];

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    
    shape[0] = n = w->n+1;
    

    v = rb_narray_new(cDF, 1, shape);
    d = (double*)na_get_pointer_for_write(v);
    for (i=0; i<n; i++) {
        d[i] = w->range[i];
    }
    return v;
}

#reset ⇒ Object

This function resets all the bins in the histogram h to zero.



561
562
563
564
565
566
567
568
569
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 561

static VALUE
histogram_reset(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);
    gsl_histogram_reset(w);
    return Qnil;
}

#scale(scale) ⇒ Qnil

This function multiplies the contents of the bins of histogram h by the constant scale, i.e. $h’_1(i) = h_1(i) * \hboxscale$ h’_1(i) = h_1(i) * scale.

Parameters:

  • scale (Float)

Returns:

  • (Qnil) 


841
842
843
844
845
846
847
848
849
850
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 841

static VALUE
histogram_scale(VALUE self, VALUE v1)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    gsl_histogram_scale(w, NUM2DBL(v1));
    return Qnil;
}

#set_ranges(range[]) ⇒ Histogram

This function sets the ranges of the existing histogram h using the array range of size size. The values of the histogram bins are reset to zero. The range array should contain the desired bin limits. The ranges can be arbitrary, subject to the restriction that they are monotonically increasing.

The following example shows how to create a histogram with logarithmic bins with ranges [1,10), [10,100) and [100,1000).

gsl_histogram * h = gsl_histogram_alloc (3);

// bin[0] covers the range 1 <= x < 10 // bin[1] covers the range 10 <= x < 100 // bin[2] covers the range 100 <= x < 1000

double range[4] = [ 1.0, 10.0, 100.0, 1000.0 ];

gsl_histogram_set_ranges (h, range, 4);

Note that the size of the range array should be defined to be one element bigger than the number of bins. The additional element is required for the upper value of the final bin.

Parameters:

  • range[] (DFloat)

Returns:



205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 205

static VALUE
histogram_set_ranges(VALUE self, VALUE v1)
{
    gsl_histogram *w;
    double *p1;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    v1 = cast_1d_contiguous(v1, cDF);
    p1 = (double*)na_get_pointer_for_read(v1);
    gsl_histogram_set_ranges(w, p1, RNARRAY_SIZE(v1));
    RB_GC_GUARD(v1);
    return self;
}

#set_ranges_uniform(xmin, xmax) ⇒ Qnil

This function sets the ranges of the existing histogram h to cover the range xmin to xmax uniformly. The values of the histogram bins are reset to zero. The bin ranges are shown in the table below,

where d is the bin spacing, d = (xmax-xmin)/n.

Parameters:

  • xmin (Float)
  • xmax (Float)

Returns:

  • (Qnil) 


235
236
237
238
239
240
241
242
243
244
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 235

static VALUE
histogram_set_ranges_uniform(VALUE self, VALUE v1, VALUE v2)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    gsl_histogram_set_ranges_uniform(w, NUM2DBL(v1), NUM2DBL(v2));
    return Qnil;
}

#shift(offset) ⇒ Qnil

This function shifts the contents of the bins of histogram h by the constant offset, i.e. $h’_1(i) = h_1(i) + \hboxoffset$ h’_1(i) = h_1(i) + offset.

Parameters:

  • offset (Float)

Returns:

  • (Qnil) 


863
864
865
866
867
868
869
870
871
872
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 863

static VALUE
histogram_shift(VALUE self, VALUE v1)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    gsl_histogram_shift(w, NUM2DBL(v1));
    return Qnil;
}

#sigma ⇒ Float

This function returns the standard deviation of the histogrammed variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation. The accuracy of the result is limited by the bin width.

Returns:

  • (Float) 


679
680
681
682
683
684
685
686
687
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 679

static VALUE
histogram_sigma(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return DBL2NUM(gsl_histogram_sigma(w));
}

#sub(h2) ⇒ Bool

This function subtracts the contents of the bins in histogram h2 from the corresponding bins of histogram h1, i.e. h’_1(i) = h_1(i) - h_2(i). The two histograms must have identical bin ranges.

Parameters:

Returns:

  • (Bool) 


767
768
769
770
771
772
773
774
775
776
777
778
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 767

static VALUE
histogram_sub(VALUE self, VALUE v1)
{
    int stat;
    gsl_histogram *w, *w1;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);
    TypedData_Get_Struct(v1, gsl_histogram, &histogram_data_type, w1);

    stat = gsl_histogram_sub(w, w1);
    return (stat) ? Qtrue: Qfalse;
}

#sum ⇒ Float

This function returns the sum of all bin values. Negative bin values are included in the sum.

Returns:

  • (Float) 


698
699
700
701
702
703
704
705
706
 
# File 'ext/numo/gsl/histogram/gsl_histogram.c', line 698

static VALUE
histogram_sum(VALUE self)
{
    gsl_histogram *w;

    TypedData_Get_Struct(self, gsl_histogram, &histogram_data_type, w);

    return DBL2NUM(gsl_histogram_sum(w));
}