XGBoost/CAPI/RAW.pm

filter: Statementstmt 77.7% 7 / 9 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 3 / 3 Podpod n/a totaltotal 83.3% 10 / 12 CC 1 SCAR 0.9
CC
1
Cov
78%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
« XGBoost.pm ↑ Summary XGBoost/CAPI.pm »
1 package AI::XGBoost::CAPI::RAW;
2 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 3 ▶use Alien::XGBoost;
Subroutine BEGIN: called CC=1 SCAR=2.6
6 use FFI::Platypus;
7  
8 my $ffi = FFI::Platypus->new;
9 $ffi->lib( Alien::XGBoost->dynamic_libs );
10  
11 our $VERSION = '0.11'; # VERSION
12  
13 # ABSTRACT: Perl wrapper for XGBoost C API https://github.com/dmlc/xgboost
14  
15 $ffi->attach( XGBGetLastError => [] => 'string' );
16  
17 $ffi->attach( XGDMatrixCreateFromFile => [qw(string int opaque*)] => 'int' );
18  
19 $ffi->attach( XGDMatrixCreateFromCSREx => [qw(size_t[] uint[] float[] size_t size_t size_t opaque*)] => 'int' );
20  
21 $ffi->attach( XGDMatrixCreateFromCSCEx => [qw(size_t[] uint[] float[] size_t size_t size_t opaque*)] => 'int' );
22  
23 $ffi->attach( XGDMatrixCreateFromMat => [qw(float[] uint64 uint64 float opaque*)] => 'int' );
24  
25 $ffi->attach( XGDMatrixCreateFromMat_omp => [qw(float[] uint64 uint64 float opaque* int)] => 'int' );
26  
27 $ffi->attach( XGDMatrixSliceDMatrix => [qw(opaque int[] uint64 opaque*)] => 'int' );
28  
29 $ffi->attach( XGDMatrixNumRow => [qw(opaque uint64*)] => 'int' );
30  
31 $ffi->attach( XGDMatrixNumCol => [qw(opaque uint64*)] => 'int' );
32  
33 $ffi->attach( XGDMatrixSaveBinary => [qw(opaque string int)] => 'int' );
34  
35 $ffi->attach( XGDMatrixSetFloatInfo => [qw(opaque string float[] uint64)] => 'int' );
36  
37 $ffi->attach( XGDMatrixSetUIntInfo => [qw(opaque string uint32* uint64)] => 'int' );
38  
39 $ffi->attach( XGDMatrixSetGroup => [qw(opaque uint32* uint64)] => 'int' );
40  
41 $ffi->attach( XGDMatrixGetFloatInfo => [qw(opaque string uint64* opaque*)] => 'int' );
42  
43 $ffi->attach( XGDMatrixGetUIntInfo => [qw(opaque string uint64* opaque*)] => 'int' );
44  
45 $ffi->attach( XGDMatrixFree => [qw(opaque)] => 'int' );
46  
47 $ffi->attach( XGBoosterCreate => [qw(opaque[] uint64 opaque*)] => 'int' );
48  
49 $ffi->attach( XGBoosterFree => [qw(opaque)] => 'int' );
50  
51 $ffi->attach( XGBoosterSetParam => [qw(opaque string string)] => 'int' );
52  
53 $ffi->attach( XGBoosterBoostOneIter => [qw(opaque opaque float[] float[] uint64)] => 'int' );
54  
55 $ffi->attach( XGBoosterUpdateOneIter => [qw(opaque int opaque)] => 'int' );
56  
57 $ffi->attach( XGBoosterEvalOneIter => [qw(opaque int opaque[] opaque[] uint64 opaque*)] => 'int' );
58  
59 $ffi->attach( XGBoosterPredict => [qw(opaque opaque int uint uint64* opaque*)] => 'int' );
60  
61 $ffi->attach( XGBoosterLoadModel => [qw(opaque string)] => 'int' );
62  
63 $ffi->attach( XGBoosterSaveModel => [qw(opaque string)] => 'int' );
64  
65 $ffi->attach( XGBoosterLoadModelFromBuffer => [qw(opaque opaque uint64)] => 'int' );
66  
67 $ffi->attach( XGBoosterGetModelRaw => [qw(opaque uint64* opaque*)] => 'int' );
68  
69 $ffi->attach( XGBoosterDumpModel => [qw(opaque string int uint64* opaque*)] => 'int' );
70  
71 $ffi->attach( XGBoosterDumpModelEx => [qw(opaque string int string uint64* opaque*)] => 'int' );
72  
73 $ffi->attach( XGBoosterDumpModelWithFeatures => [qw(opaque int opaque[] opaque[] int uint64* opaque*)] => 'int' );
74  
75 $ffi->attach(
76 XGBoosterDumpModelExWithFeatures => [qw(opaque int opaque[] opaque[] int string uint64* opaque*)] => 'int' );
77  
78 $ffi->attach( XGBoosterSetAttr => [qw(opaque string string)] => 'int' );
79  
80 $ffi->attach( XGBoosterGetAttr => [qw(opaque string opaque* int*)] => 'int' );
81  
82 $ffi->attach( XGBoosterGetAttrNames => [qw(opaque uint64* opaque*)] => 'int' );
83  
84 $ffi->attach( XGBoosterLoadRabitCheckpoint => [qw(opaque int)] => 'int' );
85  
86 $ffi->attach( XGBoosterSaveRabitCheckpoint => [qw(opaque)] => 'int' );
87  
88 1;
89  
90 __END__
91  
92 =pod
93  
94 =encoding utf-8
95  
96 =head1 NAME
97  
98 AI::XGBoost::CAPI::RAW - Perl wrapper for XGBoost C API https://github.com/dmlc/xgboost
99  
100 =head1 VERSION
101  
102 version 0.11
103  
104 =head1 SYNOPSIS
105  
106 use 5.010;
107 use AI::XGBoost::CAPI::RAW;
108 use FFI::Platypus;
109
110 my $silent = 0;
111 my ($dtrain, $dtest) = (0, 0);
112
113 AI::XGBoost::CAPI::RAW::XGDMatrixCreateFromFile('agaricus.txt.test', $silent, \$dtest);
114 AI::XGBoost::CAPI::RAW::XGDMatrixCreateFromFile('agaricus.txt.train', $silent, \$dtrain);
115
116 my ($rows, $cols) = (0, 0);
117 AI::XGBoost::CAPI::RAW::XGDMatrixNumRow($dtrain, \$rows);
118 AI::XGBoost::CAPI::RAW::XGDMatrixNumCol($dtrain, \$cols);
119 say "Dimensions: $rows, $cols";
120
121 my $booster = 0;
122
123 AI::XGBoost::CAPI::RAW::XGBoosterCreate( [$dtrain] , 1, \$booster);
124
125 for my $iter (0 .. 10) {
126 AI::XGBoost::CAPI::RAW::XGBoosterUpdateOneIter($booster, $iter, $dtrain);
127 }
128
129 my $out_len = 0;
130 my $out_result = 0;
131
132 AI::XGBoost::CAPI::RAW::XGBoosterPredict($booster, $dtest, 0, 0, \$out_len, \$out_result);
133 my $ffi = FFI::Platypus->new();
134 my $predictions = $ffi->cast(opaque => "float[$out_len]", $out_result);
135
136 #say join "\n", @$predictions;
137
138 AI::XGBoost::CAPI::RAW::XGBoosterFree($booster);
139 AI::XGBoost::CAPI::RAW::XGDMatrixFree($dtrain);
140 AI::XGBoost::CAPI::RAW::XGDMatrixFree($dtest);
141  
142 =head1 DESCRIPTION
143  
144 Wrapper for the C API.
145  
146 The doc for the methods is extracted from doxygen comments: https://github.com/dmlc/xgboost/blob/master/include/xgboost/c_api.h
147  
148 =head1 FUNCTIONS
149  
150 =head2 XGBGetLastError
151  
152 Get string message of the last error
153  
154 All functions in this file will return 0 when success
155 and -1 when an error occurred,
156 XGBGetLastError can be called to retrieve the error
157  
158 This function is thread safe and can be called by different thread
159  
160 Returns string error information
161  
162 =head2 XGDMatrixCreateFromFile
163  
164 Load a data matrix
165  
166 Parameters:
167  
168 =over 4
169  
170 =item filename
171  
172 the name of the file
173  
174 =item silent
175  
176 whether print messages during loading
177  
178 =item out
179  
180 a loaded data matrix
181  
182 =back
183  
184 =head2 XGDMatrixCreateFromCSREx
185  
186 Create a matrix content from CSR fromat
187  
188 Parameters:
189  
190 =over 4
191  
192 =item indptr
193  
194 pointer to row headers
195  
196 =item indices
197  
198 findex
199  
200 =item data
201  
202 fvalue
203  
204 =item nindptr
205  
206 number of rows in the matrix + 1
207  
208 =item nelem
209  
210 number of nonzero elements in the matrix
211  
212 =item num_col
213  
214 number of columns; when it's set to 0, then guess from data
215  
216 =item out
217  
218 created dmatrix
219  
220 =back
221  
222 =head2 XGDMatrixCreateFromCSCEx
223  
224 Create a matrix content from CSC format
225  
226 Parameters:
227  
228 =over 4
229  
230 =item col_ptr
231  
232 pointer to col headers
233  
234 =item indices
235  
236 findex
237  
238 =item data
239  
240 fvalue
241  
242 =item nindptr
243  
244 number of rows in the matrix + 1
245  
246 =item nelem
247  
248 number of nonzero elements in the matrix
249  
250 =item num_row
251  
252 number of rows; when it's set to 0, then guess from data
253  
254 =back
255  
256 =head2 XGDMatrixCreateFromMat
257  
258 Create matrix content from dense matrix
259  
260 Parameters:
261  
262 =over 4
263  
264 =item data
265  
266 pointer to the data space
267  
268 =item nrow
269  
270 number of rows
271  
272 =item ncol
273  
274 number columns
275  
276 =item missing
277  
278 which value to represent missing value
279  
280 =item out
281  
282 created dmatrix
283  
284 =back
285  
286 =head2 XGDMatrixCreateFromMat_omp
287  
288 Create matrix content from dense matrix
289  
290 Parameters:
291  
292 =over 4
293  
294 =item data
295  
296 pointer to the data space
297  
298 =item nrow
299  
300 number of rows
301  
302 =item ncol
303  
304 number columns
305  
306 =item missing
307  
308 which value to represent missing value
309  
310 =item out
311  
312 created dmatrix
313  
314 =item nthread
315  
316 number of threads (up to maximum cores available, if <=0 use all cores)
317  
318 =back
319  
320 =head2 XGDMatrixSliceDMatrix
321  
322 Create a new dmatrix from sliced content of existing matrix
323  
324 Parameters:
325  
326 =over 4
327  
328 =item handle
329  
330 instance of data matrix to be sliced
331  
332 =item idxset
333  
334 index set
335  
336 =item len
337  
338 length of index set
339  
340 =item out
341  
342 a sliced new matrix
343  
344 =back
345  
346 =head2 XGDMatrixNumRow
347  
348 Get number of rows.
349  
350 Parameters:
351  
352 =over 4
353  
354 =item handle
355  
356 the handle to the DMatrix
357  
358 =item out
359  
360 The address to hold number of rows.
361  
362 =back
363  
364 =head2 XGDMatrixNumCol
365  
366 Get number of cols.
367  
368 Parameters:
369  
370 =over 4
371  
372 =item handle
373  
374 the handle to the DMatrix
375  
376 =item out
377  
378 The address to hold number of cols.
379  
380 =back
381  
382 =head2 XGDMatrixSaveBinary
383  
384 load a data matrix into binary file
385  
386 Parameters:
387  
388 =over 4
389  
390 =item handle
391  
392 a instance of data matrix
393  
394 =item fname
395  
396 file name
397  
398 =item silent
399  
400 print statistics when saving
401  
402 =back
403  
404 =head2 XGDMatrixSetFloatInfo
405  
406 Set float vector to a content in info
407  
408 Parameters:
409  
410 =over 4
411  
412 =item handle
413  
414 a instance of data matrix
415  
416 =item field
417  
418 field name, can be label, weight
419  
420 =item array
421  
422 pointer to float vector
423  
424 =item len
425  
426 length of array
427  
428 =back
429  
430 =head2 XGDMatrixSetUIntInfo
431  
432 Set uint32 vector to a content in info
433  
434 Parameters:
435  
436 =over 4
437  
438 =item handle
439  
440 a instance of data matrix
441  
442 =item field
443  
444 field name, can be label, weight
445  
446 =item array
447  
448 pointer to unsigned int vector
449  
450 =item len
451  
452 length of array
453  
454 =back
455  
456 =head2 XGDMatrixSetGroup
457  
458 Set label of the training matrix
459  
460 Parameters:
461  
462 =over 4
463  
464 =item handle
465  
466 a instance of data matrix
467  
468 =item group
469  
470 pointer to group size
471  
472 =item len
473  
474 length of the array
475  
476 =back
477  
478 =head2 XGDMatrixGetFloatInfo
479  
480 Get float info vector from matrix
481  
482 Parameters:
483  
484 =over 4
485  
486 =item handle
487  
488 a instance of data matrix
489  
490 =item field
491  
492 field name
493  
494 =item out_len
495  
496 used to set result length
497  
498 =item out_dptr
499  
500 pointer to the result
501  
502 =back
503  
504 =head2 XGDMatrixGetUIntInfo
505  
506 Get uint32 info vector from matrix
507  
508 Parameters:
509  
510 =over 4
511  
512 =item handle
513  
514 a instance of data matrix
515  
516 =item field
517  
518 field name
519  
520 =item out_len
521  
522 The length of the field
523  
524 =item out_dptr
525  
526 pointer to the result
527  
528 =back
529  
530 =head2 XGDMatrixFree
531  
532 Free space in data matrix
533  
534 =head2 XGBoosterCreate
535  
536 Create xgboost learner
537  
538 Parameters:
539  
540 =over 4
541  
542 =item dmats
543  
544 matrices that are set to be cached
545  
546 =item len
547  
548 length of dmats
549  
550 =item out
551  
552 handle to the result booster
553  
554 =back
555  
556 =head2 XGBoosterFree
557  
558 Free obj in handle
559  
560 Parameters:
561  
562 =over 4
563  
564 =item handle
565  
566 handle to be freed
567  
568 =back
569  
570 =head2 XGBoosterSetParam
571  
572 Update the model in one round using dtrain
573  
574 Parameters:
575  
576 =over 4
577  
578 =item handle
579  
580 handle
581  
582 =item name
583  
584 parameter name
585  
586 =item value
587  
588 value of parameter
589  
590 =back
591  
592 =head2 XGBoosterBoostOneIter
593  
594 Update the modelo, by directly specify grandient and second order gradient,
595 this can be used to replace UpdateOneIter, to support customized loss function
596  
597 Parameters:
598  
599 =over 4
600  
601 =item handle
602  
603 handle
604  
605 =item dtrain
606  
607 training data
608  
609 =item grad
610  
611 gradient statistics
612  
613 =item hess
614  
615 second order gradinet statistics
616  
617 =item len
618  
619 length of grad/hess array
620  
621 =back
622  
623 =head2 XGBoosterUpdateOneIter
624  
625 Update the model in one round using dtrain
626  
627 Parameters:
628  
629 =over 4
630  
631 =item handle
632  
633 handle
634  
635 =item iter
636  
637 current iteration rounds
638  
639 =item dtrain
640  
641 training data
642  
643 =back
644  
645 =head2 XGBoosterEvalOneIter
646  
647 =head2 XGBoosterPredict
648  
649 Make prediction based on dmat
650  
651 Parameters:
652  
653 =over 4
654  
655 =item handle
656  
657 handle
658  
659 =item dmat
660  
661 data matrix
662  
663 =item option_mask
664  
665 bit-mask of options taken in prediction, possible values
666  
667 =over 4
668  
669 =item
670  
671 0: normal prediction
672  
673 =item
674  
675 1: output margin instead of transformed value
676  
677 =item
678  
679 2: output leaf index of trees instead of leaf value, note leaf index is unique per tree
680  
681 =item
682  
683 4: output feature contributions to individual predictions
684  
685 =back
686  
687 =item ntree_limit
688  
689 limit number of trees used for prediction, this is only valid for boosted trees
690 when the parameter is set to 0, we will use all the trees
691  
692 =item out_len
693  
694 used to store length of returning result
695  
696 =item out_result
697  
698 used to set a pointer to array
699  
700 =back
701  
702 =head2 XGBoosterLoadModel
703  
704 Load model form existing file
705  
706 Parameters:
707  
708 =over 4
709  
710 =item handle
711  
712 handle
713  
714 =item fname
715  
716 file name
717  
718 =back
719  
720 =head2 XGBoosterSaveModel
721  
722 Save model into existing file
723  
724 Parameters:
725  
726 =over 4
727  
728 =item handle
729  
730 handle
731  
732 =item fname
733  
734 file name
735  
736 =back
737  
738 =head2 XGBoosterLoadModelFromBuffer
739  
740 =head2 XGBoosterGetModelRaw
741  
742 =head2 XGBoosterDumpModel
743  
744 =head2 XGBoosterDumpModelEx
745  
746 =head2 XGBoosterDumpModelWithFeatures
747  
748 =head2 XGBoosterDumpModelExWithFeatures
749  
750 =head2 XGBoosterSetAttr
751  
752 =head2 XGBoosterGetAttr
753  
754 =head2 XGBoosterGetAttrNames
755  
756 =head2 XGBoosterLoadRabitCheckpoint
757  
758 =head2 XGBoosterSaveRabitCheckpoint
759  
760 =head1 AUTHOR
761  
762 Pablo Rodríguez González <pablo.rodriguez.gonzalez@gmail.com>
763  
764 =head1 COPYRIGHT AND LICENSE
765  
766 Copyright (c) 2017 by Pablo Rodríguez González.
767  
768 =cut
« XGBoost.pm ↑ Summary XGBoost/CAPI.pm »