MNT add sphinxcontrib-bibtex to manage citation (#638)

Author: glemaitre

.gitignore

@@ -118,4 +118,5 @@ cythonize.dat
 # build documentation
 doc/_build/
 doc/auto_examples/
-doc/generated/
+doc/generated/
+doc/bibtex/auto

build_tools/circle/build_doc.sh

@@ -100,11 +100,12 @@ conda update --yes --quiet conda
 conda create -n $CONDA_ENV_NAME --yes --quiet python=3.7
 source activate $CONDA_ENV_NAME
 
-conda install --yes pip numpy scipy joblib pillow matplotlib sphinx \
-      memory_profiler sphinx_rtd_theme pandas keras tensorflow=1
+conda install --yes pip numpy scipy joblib pillow matplotlib memory_profiler \
+        sphinx sphinx_rtd_theme \pandas keras tensorflow=1
 pip install --pre -f https://sklearn-nightly.scdn8.secure.raxcdn.com scikit-learn
 pip install -U git+https://github.com/sphinx-gallery/sphinx-gallery.git
 pip install -U git+https://github.com/numpy/numpydoc.git
+pip install -U git+https://github.com/mcmtroffaes/sphinxcontrib-bibtex.git
 
 # Build and install imbalanced-learn in dev mode
 ls -l

doc/bibtex/refs.bib

@@ -0,0 +1,195 @@
+@article{batista2004study,
+  title={A study of the behavior of several methods for balancing machine learning training data},
+  author={Batista, Gustavo EAPA and Prati, Ronaldo C and Monard, Maria Carolina},
+  journal={ACM SIGKDD explorations newsletter},
+  volume={6},
+  number={1},
+  pages={20--29},
+  year={2004},
+  publisher={ACM}
+}
+
+@inproceedings{batista2003balancing,
+  title={Balancing Training Data for Automated Annotation of Keywords: a Case Study.},
+  author={Batista, Gustavo EAPA and Bazzan, Ana LC and Monard, Maria Carolina},
+  booktitle={WOB},
+  pages={10--18},
+  year={2003}
+}
+
+@article{chen2004using,
+  title={Using random forest to learn imbalanced data},
+  author={Chen, Chao and Liaw, Andy and Breiman, Leo and others},
+  journal={University of California, Berkeley},
+  volume={110},
+  number={1-12},
+  pages={24},
+  year={2004}
+}
+
+@article{liu2008exploratory,
+  title={Exploratory undersampling for class-imbalance learning},
+  author={Liu, Xu-Ying and Wu, Jianxin and Zhou, Zhi-Hua},
+  journal={IEEE Transactions on Systems, Man, and Cybernetics, Part B (Cybernetics)},
+  volume={39},
+  number={2},
+  pages={539--550},
+  year={2008},
+  publisher={IEEE}
+}
+
+@article{seiffert2009rusboost,
+  title={RUSBoost: A hybrid approach to alleviating class imbalance},
+  author={Seiffert, Chris and Khoshgoftaar, Taghi M and Van Hulse, Jason and Napolitano, Amri},
+  journal={IEEE Transactions on Systems, Man, and Cybernetics-Part A: Systems and Humans},
+  volume={40},
+  number={1},
+  pages={185--197},
+  year={2009},
+  publisher={IEEE}
+}
+
+@inproceedings{kubat1997addressing,
+  title={Addressing the curse of imbalanced training sets: one-sided selection},
+  author={Kubat, Miroslav and Matwin, Stan and others},
+  booktitle={Icml},
+  volume={97},
+  pages={179--186},
+  year={1997},
+  organization={Nashville, USA}
+}
+
+@article{barandela2003strategies,
+  title={Strategies for learning in class imbalance problems},
+  author={Barandela, Ricardo and S{\'a}nchez, Jos{\'e} Salvador and Garca, V and Rangel, Edgar},
+  journal={Pattern Recognition},
+  volume={36},
+  number={3},
+  pages={849--851},
+  year={2003},
+  publisher={Elsevier Science Publishing Company, Inc.}
+}
+
+@article{garcia2012effectiveness,
+  title={On the effectiveness of preprocessing methods when dealing with different levels of class imbalance},
+  author={Garc{\'\i}a, Vicente and S{\'a}nchez, Jos{\'e} Salvador and Mollineda, Ram{\'o}n Alberto},
+  journal={Knowledge-Based Systems},
+  volume={25},
+  number={1},
+  pages={13--21},
+  year={2012},
+  publisher={Elsevier}
+}
+
+@inproceedings{he2008adasyn,
+  title={ADASYN: Adaptive synthetic sampling approach for imbalanced learning},
+  author={He, Haibo and Bai, Yang and Garcia, Edwardo A and Li, Shutao},
+  booktitle={2008 IEEE International Joint Conference on Neural Networks (IEEE World Congress on Computational Intelligence)},
+  pages={1322--1328},
+  year={2008},
+  organization={IEEE}
+}
+
+@article{chawla2002smote,
+  title={SMOTE: synthetic minority over-sampling technique},
+  author={Chawla, Nitesh V and Bowyer, Kevin W and Hall, Lawrence O and Kegelmeyer, W Philip},
+  journal={Journal of artificial intelligence research},
+  volume={16},
+  pages={321--357},
+  year={2002}
+}
+
+@inproceedings{han2005borderline,
+  title={Borderline-SMOTE: a new over-sampling method in imbalanced data sets learning},
+  author={Han, Hui and Wang, Wen-Yuan and Mao, Bing-Huan},
+  booktitle={International conference on intelligent computing},
+  pages={878--887},
+  year={2005},
+  organization={Springer}
+}
+
+@inproceedings{nguyen2009borderline,
+  title={Borderline over-sampling for imbalanced data classification},
+  author={Nguyen, Hien M and Cooper, Eric W and Kamei, Katsuari},
+  booktitle={Proceedings: Fifth International Workshop on Computational Intelligence \& Applications},
+  volume={2009},
+  number={1},
+  pages={24--29},
+  year={2009},
+  organization={IEEE SMC Hiroshima Chapter}
+}
+
+@article{last2017oversampling,
+  title={Oversampling for Imbalanced Learning Based on K-Means and SMOTE},
+  author={Last, Felix and Douzas, Georgios and Bacao, Fernando},
+  journal={arXiv preprint arXiv:1711.00837},
+  year={2017}
+}
+
+@inproceedings{mani2003knn,
+  title={kNN approach to unbalanced data distributions: a case study involving information extraction},
+  author={Mani, Inderjeet and Zhang, I},
+  booktitle={Proceedings of workshop on learning from imbalanced datasets},
+  volume={126},
+  year={2003}
+}
+
+@article{tomek1976two,
+  title={Two modifications of CNN},
+  author={Tomek, Ivan},
+  journal={IEEE Trans. Systems, Man and Cybernetics},
+  volume={6},
+  pages={769--772},
+  year={1976}
+}
+
+@article{wilson1972asymptotic,
+  title={Asymptotic properties of nearest neighbor rules using edited data},
+  author={Wilson, Dennis L},
+  journal={IEEE Transactions on Systems, Man, and Cybernetics},
+  number={3},
+  pages={408--421},
+  year={1972},
+  publisher={IEEE}
+}
+
+@article{tomek1976experiment,
+  title={An experiment with the edited nearest-neighbor rule},
+  author={Tomek, Ivan},
+  journal={IEEE Transactions on systems, Man, and Cybernetics},
+  volume={6},
+  number={6},
+  pages={448--452},
+  year={1976}
+}
+
+@article{hart1968condensed,
+  title={The condensed nearest neighbor rule (Corresp.)},
+  author={Hart, Peter},
+  journal={IEEE transactions on information theory},
+  volume={14},
+  number={3},
+  pages={515--516},
+  year={1968},
+  publisher={Citeseer}
+}
+
+@inproceedings{laurikkala2001improving,
+  title={Improving identification of difficult small classes by balancing class distribution},
+  author={Laurikkala, Jorma},
+  booktitle={Conference on Artificial Intelligence in Medicine in Europe},
+  pages={63--66},
+  year={2001},
+  organization={Springer}
+}
+
+@article{smith2014instance,
+  title={An instance level analysis of data complexity},
+  author={Smith, Michael R and Martinez, Tony and Giraud-Carrier, Christophe},
+  journal={Machine learning},
+  volume={95},
+  number={2},
+  pages={225--256},
+  year={2014},
+  publisher={Springer}
+}

doc/combine.rst

@@ -17,7 +17,8 @@ In this regard, Tomek's link and edited nearest-neighbours are the two cleaning
 methods that have been added to the pipeline after applying SMOTE over-sampling
 to obtain a cleaner space. The two ready-to use classes imbalanced-learn
 implements for combining over- and undersampling methods are: (i)
-:class:`SMOTETomek` [BPM2004]_ and (ii) :class:`SMOTEENN` [BBM2003]_.
+:class:`SMOTETomek` :cite:`batista2004study` and (ii) :class:`SMOTEENN`
+:cite:`batista2003balancing`.
 
 Those two classes can be used like any other sampler with parameters identical
 to their former samplers::
@@ -53,13 +54,3 @@ noisy samples than :class:`SMOTETomek`.
 .. topic:: Examples
 
   * :ref:`sphx_glr_auto_examples_combine_plot_comparison_combine.py`
-
-.. topic:: References
-
-  .. [BPM2004] G. Batista, R. C. Prati, M. C. Monard. "A study of the behavior
-               of several methods for balancing machine learning training
-               data," ACM Sigkdd Explorations Newsletter 6 (1), 20-29, 2004.
-
-  .. [BBM2003] G. Batista, B. Bazzan, M. Monard, "Balancing Training Data for
-               Automated Annotation of Keywords: a Case Study," In WOB, 10-18,
-               2003.

doc/conf.py

@@ -37,6 +37,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.linkcode',
+    'sphinxcontrib.bibtex',
     'numpydoc',
     'sphinx_issues',
     'sphinx_gallery.gen_gallery',

doc/ensemble.rst

@@ -68,7 +68,7 @@ Forest of randomized trees
 
 :class:`BalancedRandomForestClassifier` is another ensemble method in which
 each tree of the forest will be provided a balanced bootstrap sample
-[1CLB2004]_. This class provides all functionality of the
+:cite:`chen2004using`. This class provides all functionality of the
 :class:`sklearn.ensemble.RandomForestClassifier` and notably the
 `feature_importances_` attributes::
 
@@ -88,7 +88,7 @@ Boosting
 Several methods taking advantage of boosting have been designed.
 
 :class:`RUSBoostClassifier` randomly under-sample the dataset before to perform
-a boosting iteration [SKHN2010]_::
+a boosting iteration :cite:`seiffert2009rusboost`::
 
   >>> from imblearn.ensemble import RUSBoostClassifier
   >>> rusboost = RUSBoostClassifier(n_estimators=200, algorithm='SAMME.R',
@@ -101,9 +101,9 @@ a boosting iteration [SKHN2010]_::
 
 A specific method which uses ``AdaBoost`` as learners in the bagging classifier
 is called EasyEnsemble. The :class:`EasyEnsembleClassifier` allows to bag
-AdaBoost learners which are trained on balanced bootstrap samples [LWZ2009]_.
-Similarly to the :class:`BalancedBaggingClassifier` API, one can construct the
-ensemble as::
+AdaBoost learners which are trained on balanced bootstrap samples
+:cite:`liu2008exploratory`. Similarly to the :class:`BalancedBaggingClassifier`
+API, one can construct the ensemble as::
 
   >>> from imblearn.ensemble import EasyEnsembleClassifier
   >>> eec = EasyEnsembleClassifier(random_state=0)
@@ -116,19 +116,3 @@ ensemble as::
 .. topic:: Examples
 
   * :ref:`sphx_glr_auto_examples_ensemble_plot_comparison_ensemble_classifier.py`
-
-.. topic:: References
-
-  .. [1CLB2004] Chen, Chao, Andy Liaw, and Leo Breiman. "Using random forest to
-                learn imbalanced data." University of California, Berkeley 110
-                (2004): 1-12.
-
-  .. [LWZ2009] X. Y. Liu, J. Wu and Z. H. Zhou, "Exploratory Undersampling for
-               Class-Imbalance Learning," in IEEE Transactions on Systems, Man,
-               and Cybernetics, Part B (Cybernetics), vol. 39, no. 2, pp.
-               539-550, April 2009.
-
-  .. [SKHN2010] Seiffert, C., Khoshgoftaar, T. M., Van Hulse, J., &
-                Napolitano, A. "RUSBoost: A hybrid approach to alleviating
-                class imbalance." IEEE Transactions on Systems, Man, and
-                Cybernetics-Part A: Systems and Humans 40.1 (2010): 185-197.

doc/metrics.rst

@@ -36,9 +36,11 @@ use those metrics.
 Additional metrics specific to imbalanced datasets
 --------------------------------------------------
 
-The :func:`geometric_mean_score` is the root of the product of class-wise
-sensitivity. This measure tries to maximize the accuracy on each of the classes
-while keeping these accuracies balanced.
-
-The :func:`make_index_balanced_accuracy` can wrap any metric and give more
-importance to a specific class using the parameter ``alpha``.
+The :func:`geometric_mean_score`
+:cite:`barandela2003strategies,kubat1997addressing` is the root of the product
+of class-wise sensitivity. This measure tries to maximize the accuracy on each
+of the classes while keeping these accuracies balanced.
+
+The :func:`make_index_balanced_accuracy` :cite:`garcia2012effectiveness` can
+wrap any metric and give more importance to a specific class using the
+parameter ``alpha``.