diff --git a/doc/R-package/index.md b/doc/R-package/index.md index 92df95e9f..6333d43fb 100644 --- a/doc/R-package/index.md +++ b/doc/R-package/index.md @@ -9,7 +9,7 @@ You have find XGBoost R Package! Get Started ----------- * Checkout the [Installation Guide](../build.md) contains instructions to install xgboost, and [Tutorials](#tutorials) for examples on how to use xgboost for various tasks. -* Please visit [walk through example](demo). +* Please visit [walk through example](../../R-package/demo). Tutorials --------- diff --git a/doc/cli/index.md b/doc/cli/index.md new file mode 100644 index 000000000..23611d699 --- /dev/null +++ b/doc/cli/index.md @@ -0,0 +1,3 @@ +# XGBoost Command Line version + +See [XGBoost Command Line walkthrough](https://github.com/dmlc/xgboost/blob/master/demo/binary_classification/README.md) diff --git a/doc/conf.py b/doc/conf.py index b2f82e726..65ebddccd 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -117,10 +117,11 @@ todo_include_todos = False # -- Options for HTML output ---------------------------------------------- +html_theme_path = ['_static'] # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'alabaster' -html_theme = 'sphinx_rtd_theme' +html_theme = 'xgboost-theme' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/doc/get_started/index.md b/doc/get_started/index.md new file mode 100644 index 000000000..50c960421 --- /dev/null +++ b/doc/get_started/index.md @@ -0,0 +1,80 @@ +# Get Started with XGBoost + +This is a quick started tutorial showing snippets for you to quickly try out xgboost +on the demo dataset on a binary classification task. + +## Links to Helpful Other Resources +- See [Installation Guide](../build.md) on how to install xgboost. +- See [How to pages](../how_to/index.md) on various tips on using xgboost. +- See [Tutorials](../tutorials/index.md) on tutorials on specific tasks. +- See [Learning to use XGBoost by Examples](../../demo) for more code examples. + +## Python +```python +import xgboost as xgb +# read in data +dtrain = xgb.DMatrix('demo/data/agaricus.txt.train') +dtest = xgb.DMatrix('demo/data/agaricus.txt.test') +# specify parameters via map +param = {'max_depth':2, 'eta':1, 'silent':1, 'objective':'binary:logistic' } +num_round = 2 +bst = xgb.train(param, dtrain, num_round) +# make prediction +preds = bst.predict(dtest) +``` + +## R + +```r +# load data +data(agaricus.train, package='xgboost') +data(agaricus.test, package='xgboost') +train <- agaricus.train +test <- agaricus.test +# fit model +bst <- xgboost(data = train$data, label = train$label, max.depth = 2, eta = 1, nround = 2, + nthread = 2, objective = "binary:logistic") +# predict +pred <- predict(bst, test$data) + +``` + +## Julia +```julia +using XGBoost +# read data +train_X, train_Y = readlibsvm("demo/data/agaricus.txt.train", (6513, 126)) +test_X, test_Y = readlibsvm("demo/data/agaricus.txt.test", (1611, 126)) +# fit model +num_round = 2 +bst = xgboost(train_X, num_round, label=train_Y, eta=1, max_depth=2) +# predict +pred = predict(bst, test_X) +``` + +## Scala +```scala +import ml.dmlc.xgboost4j.scala.DMatrix +import ml.dmlc.xgboost4j.scala.XGBoost + +object XGBoostScalaExample { + def main(args: Array[String]) { + // read trainining data, available at xgboost/demo/data + val trainData = + new DMatrix("/path/to/agaricus.txt.train") + // define parameters + val paramMap = List( + "eta" -> 0.1, + "max_depth" -> 2, + "objective" -> "binary:logistic").toMap + // number of iterations + val round = 2 + // train the model + val model = XGBoost.train(trainData, paramMap, round) + // run prediction + val predTrain = model.predict(trainData) + // save model to the file. + model.saveModel("/local/path/to/model") + } +} +``` diff --git a/doc/dev-guide/contribute.md b/doc/how_to/contribute.md similarity index 100% rename from doc/dev-guide/contribute.md rename to doc/how_to/contribute.md diff --git a/doc/external_memory.md b/doc/how_to/external_memory.md similarity index 100% rename from doc/external_memory.md rename to doc/how_to/external_memory.md diff --git a/doc/how_to/index.md b/doc/how_to/index.md new file mode 100644 index 000000000..afc69f777 --- /dev/null +++ b/doc/how_to/index.md @@ -0,0 +1,16 @@ +# XGBoost How To + +This page contains guidelines to use and develop mxnets. + +## Installation +- [How to Install XGBoost](../build.md) + +## Use XGBoost in Specific Ways +- [Parameter tunning guide](param_tuning.md) +- [Use out of core computation for large dataset](external_memory.md) + +## Develop and Hack XGBoost +- [Contribute to XGBoost](contribute.md) + +## Frequently Ask Questions +- [FAQ](../faq.md) diff --git a/doc/param_tuning.md b/doc/how_to/param_tuning.md similarity index 100% rename from doc/param_tuning.md rename to doc/how_to/param_tuning.md diff --git a/doc/index.md b/doc/index.md index 9d95944e6..55d90d95b 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,59 +1,15 @@ XGBoost Documentation ===================== -This is document of xgboost library. -XGBoost is short for eXtreme gradient boosting. This is a library that is designed, and optimized for boosted (tree) algorithms. -The goal of this library is to push the extreme of the computation limits of machines to provide a ***scalable***, ***portable*** and ***accurate*** -for large scale tree boosting. - This document is hosted at http://xgboost.readthedocs.org/. You can also browse most of the documents in github directly. -Package Documents ------------------ -This section contains language specific package guide. -* [XGBoost Command Line Usage Walkthrough](../demo/binary_classification/README.md) +These are used to generate the index used in search. + * [Python Package Document](python/index.md) * [R Package Document](R-package/index.md) * [Java/Scala Package Document](jvm/index.md) -* [XGBoost.jl Julia Package](https://github.com/dmlc/XGBoost.jl) - -User Guides ------------ -This section contains users guides that are general across languages. -* [Installation Guide](build.md) -* [Introduction to Boosted Trees](model.md) -* [Distributed Training Tutorial](tutorial/aws_yarn.md) -* [Frequently Asked Questions](faq.md) -* [External Memory Version](external_memory.md) -* [Learning to use XGBoost by Example](../demo) -* [Parameters](parameter.md) -* [Text input format](input_format.md) -* [Notes on Parameter Tunning](param_tuning.md) - - -Tutorials ---------- -This section contains official tutorials of XGBoost package. -See [Awesome XGBoost](https://github.com/dmlc/xgboost/tree/master/demo) for links to mores resources. -* [Introduction to XGBoost in R](R-package/xgboostPresentation.md) (R package) - - This is a general presentation about xgboost in R. -* [Discover your data with XGBoost in R](R-package/discoverYourData.md) (R package) - - This tutorial explaining feature analysis in xgboost. -* [Introduction of XGBoost in Python](python/python_intro.md) (python) - - This tutorial introduces the python package of xgboost -* [Understanding XGBoost Model on Otto Dataset](../demo/kaggle-otto/understandingXGBoostModel.Rmd) (R package) - - This tutorial teaches you how to use xgboost to compete kaggle otto challenge. - -Developer Guide ---------------- -* [Contributor Guide](dev-guide/contribute.md) - - -Indices and tables ------------------- - -```eval_rst -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` -``` +* [Julia Package Document](julia/index.md) +* [CLI Package Document](cli/index.md) +- [Howto Documents](how_to/index.md) +- [Get Started Documents](get_started/index.md) +- [Tutorials](tutorials/index.md) diff --git a/doc/julia/index.md b/doc/julia/index.md new file mode 100644 index 000000000..470e09644 --- /dev/null +++ b/doc/julia/index.md @@ -0,0 +1,3 @@ +# XGBoost.jl + +See [XGBoost.jl Project page](https://github.com/dmlc/XGBoost.jl) \ No newline at end of file diff --git a/doc/jvm/index.md b/doc/jvm/index.md index e9a16477e..11ebe8603 100644 --- a/doc/jvm/index.md +++ b/doc/jvm/index.md @@ -7,20 +7,24 @@ You have find XGBoost JVM Package! Installation ------------ -Currently, XGBoost4J only support installation from source. Building XGBoost4J using Maven requires Maven 3 or newer and Java 7+. +Currently, XGBoost4J only support installation from source. Building XGBoost4J using Maven requires Maven 3 or newer and Java 7+. Before you install XGBoost4J, you need to define environment variable `JAVA_HOME` as your JDK directory to ensure that your compiler can find `jni.h` correctly, since XGBoost4J relies on JNI to implement the interaction between the JVM and native libraries. After your `JAVA_HOME` is defined correctly, it is as simple as run `mvn package` under jvm-packages directory to install XGBoost4J. -NOTE: XGBoost4J requires to run with Spark 1.6 or newer +NOTE: XGBoost4J requires to run with Spark 1.6 or newer Contents -------- * [Java Overview Tutorial](java_intro.md) + +Resources +--------- * [Code Examples](https://github.com/dmlc/xgboost/tree/master/jvm-packages/xgboost4j-example) * [Java API Docs](http://dmlc.ml/docs/javadocs/index.html) -* [Scala API Docs] + +## Scala API Docs * [XGBoost4J](http://dmlc.ml/docs/scaladocs/xgboost4j/index.html) * [XGBoost4J-Spark](http://dmlc.ml/docs/scaladocs/xgboost4j-spark/index.html) * [XGBoost4J-Flink](http://dmlc.ml/docs/scaladocs/xgboost4j-flink/index.html) \ No newline at end of file diff --git a/doc/parameter.md b/doc/parameter.md index 3ca79077b..131c6336e 100644 --- a/doc/parameter.md +++ b/doc/parameter.md @@ -72,7 +72,7 @@ Parameters for Tree Booster but consider set to lower number for more accurate enumeration. - range: (0, 1) * scale_pos_weight, [default=0] - - Control the balance of positive and negative weights, useful for unbalanced classes. A typical value to consider: sum(negative cases) / sum(positive cases) See [Parameters Tuning](param_tuning.md) for more discussion. Also see Higgs Kaggle competition demo for examples: [R](../demo/kaggle-higgs/higgs-train.R ), [py1](../demo/kaggle-higgs/higgs-numpy.py ), [py2](../demo/kaggle-higgs/higgs-cv.py ), [py3](../demo/guide-python/cross_validation.py) + - Control the balance of positive and negative weights, useful for unbalanced classes. A typical value to consider: sum(negative cases) / sum(positive cases) See [Parameters Tuning](how_to/param_tuning.md) for more discussion. Also see Higgs Kaggle competition demo for examples: [R](../demo/kaggle-higgs/higgs-train.R ), [py1](../demo/kaggle-higgs/higgs-numpy.py ), [py2](../demo/kaggle-higgs/higgs-cv.py ), [py3](../demo/guide-python/cross_validation.py) Parameters for Linear Booster ----------------------------- diff --git a/doc/tutorial/aws_yarn.md b/doc/tutorials/aws_yarn.md similarity index 100% rename from doc/tutorial/aws_yarn.md rename to doc/tutorials/aws_yarn.md diff --git a/doc/tutorials/index.md b/doc/tutorials/index.md new file mode 100644 index 000000000..a4edf51c1 --- /dev/null +++ b/doc/tutorials/index.md @@ -0,0 +1,8 @@ +# XGBoost Tutorials + +This section contains official tutorials inside XGBoost package. +See [Awesome XGBoost](https://github.com/dmlc/xgboost/tree/master/demo) for links to mores resources. + +## Contents +- [Introduction to Boosted Trees](../model.md) +- [Distributed XGBoost YARN on AWS](aws_yarn.md)