BigARTM command line utilityΒΆ
This document provides an overview of cpp_client, a simple command-line utility shipped with BigARTM.
To run cpp_client you need to download input data (a textual collection represented in bag-of-words format). We recommend to download vocab and docword files by links provided in Parse collection section of the tutorial. Then you can use cpp_client as follows:
cpp_client -d docword.kos.txt -v vocab.kos.txt
You may append the following options to customize the resulting topic model:
- -t or --num_topic sets the number of topics in the resulting topic model.
- -i or --num_iters sets the number of iterative scans over the collection.
- --num_inner_iters sets the number of updates of theta matrix performed on each iteration.
- --reuse_theta enables caching of Theta matrix and re-uses last Theta matrix from the previous iteration as initial approximation on the next iteration. The default alternative without --reuse_theta switch is to generate random approximation of Theta matrix on each iteration.
- --tau_phi, --tau_theta and --tau_decor allows you to specify weights of different regularizers. Currently cpp_client does not allow you to customize regularizer weights for different topics and for different iterations. This limitation is only related to cpp_client, and you can simply achieve this by using BigARTM interface (either in Python or in C++).
- --online_decay and --online_period are the parameters of online algorithm. online_period specifies time interval in milliseconds between model synchronization. Once per this time interval the topic model will be re-calculated as follows: n_wt counters in the old model are decreased according to online_decay coefficient, and increased by n_wt counters calculated by all processors since the last model synchronization. The suggested way to choose online_period is to measure single iteration time for cpp_client in offline mode (e.g. without online_period option). Then set online_period to lambda = 0.25 of the iteration time. For larger collections it may be more efficient to set online_period to lambda = 0.1 of the iteration time, but then remember to update online_decay parameter accordingly (1-lambda should be a reasonable value).
You may also apply the following optimizations that should not change the resulting model
- --reuse_batches skips parsing of docword and vocab files, and tries to use batches located in --batch_folder. You may download pre-parsed batches by links provided in Parse collection section of the tutorial.
- -p allows you to specify number of concurrent processors. The recommended value is to use the number of logical cores on your machine.
- --no_scores disables calculation and visualization of all scores. This is a clean way of measuring pure performance of BigARTM, because at the moment some scores takes unnecessary long time to calculate.
- --disk_cache_folder applies only together with --reuse_theta. This parameter allows you to specify a writable disk location where BigARTM can cache Theta matrix between iterations to avoid storing it in main memory.
>cpp_client --help
BigARTM - library for advanced topic modeling (http://bigartm.org):
Basic options:
-h [ --help ] display this help message
-d [ --docword ] arg docword file in UCI format
-v [ --vocab ] arg vocab file in UCI format
-t [ --num_topic ] arg (=16) number of topics
-p [ --num_processors ] arg (=2) number of concurrent processors
-i [ --num_iters ] arg (=10) number of outer iterations
--num_inner_iters arg (=10) number of inner iterations
--reuse_theta reuse theta between iterations
--batch_folder arg (=batches) temporary folder to store batches
--dictionary_file arg (=filename of dictionary file)
--reuse_batches reuse batches found in batch_folder
(default = false)
--items_per_batch arg (=500) number of items per batch
--tau_phi arg (=0) regularization coefficient for PHI
matrix
--tau_theta arg (=0) regularization coefficient for THETA
matrix
--tau_decor arg (=0) regularization coefficient for topics
decorrelation (use with care, since
this value heavily depends on the size
of the dataset)
--paused wait for keystroke (allows to attach a
debugger)
--no_scores disable calculation of all scores
--online_period arg (=0) period in milliseconds between model
synchronization on the online algorithm
--online_decay arg (=0.75) decay coefficient [0..1] for online
algorithm
--parsing_format arg (=0) parsing format (0 - UCI, 1 - matrix
market)
--disk_cache_folder arg disk cache folder
Networking options (experimental):
--nodes arg endpoints of the remote nodes (enables network
modus operandi)
--localhost arg (=localhost) DNS name or the IP address of the localhost
--port arg (=5550) port to use for master node
--proxy arg proxy endpoint
--timeout arg (=1000) network communication timeout in milliseconds
Examples:
cpp_client -d docword.kos.txt -v vocab.kos.txt
set GLOG_logtostderr=1 & cpp_client -d docword.kos.txt -v vocab.kos.txt
For further details please refer to the source code of cpp_client.