User:ClueBot NG/Documentation

Summary

ClueBot NG is an anti-vandalism bot that tries to detect and revert vandalism quickly and automatically.

Team

Christopher Breneman — Crispy1989 (talk⧼dot-separator⧽contribs) — wrote and maintains the core detection engine and core configuration.
Cobi Carter — Cobi (talk⧼dot-separator⧽contribs) — wrote and maintains the Wikipedia interface code and review interface.

Special thanks to:

Tim — Tim1357 (talk⧼dot-separator⧽contribs) — For writing the original dataset downloader code and providing the original dataset.
Methecooldude (talk⧼dot-separator⧽contribs) — For providing server resources at ClueNet.
DamianZaremba (talk⧼dot-separator⧽contribs), SnoFox (talk⧼dot-separator⧽contribs), H3llkn0wz (talk⧼dot-separator⧽contribs) & b930913 (talk⧼dot-separator⧽contribs) — For helping with minor issues, testing, and people-handling.
Every user who has contributed to the dataset review interface.
Everyone who has made a helpful and useful suggestion.

Questions, comments, contributions, and suggestions regarding:

the core engine, algorithms, and configuration should be directed to Crispy1989 (talk⧼dot-separator⧽contribs).
the bot's interface to Wikipedia and dataset review interface should be directed to Cobi (talk⧼dot-separator⧽contribs).
the bot's original dataset should be directed to Tim1357 (talk⧼dot-separator⧽contribs).

Dataset Review Interface

For the bot to be effective, the dataset needs to be expanded. Our current dataset has some degree of bias, as well as some inaccuracies. We need volunteers to help review edits and classify them as either vandalism or constructive. We hope to eventually completely replace our current dataset with a random sampling of edits, reviewed and classified by volunteers. More thorough instructions on how to use the interface, and the interface itself, are at the ~~dataset review interface~~ (currently broken).

Extended statistics on contributors, including edit review counts and accuracy, are available here.

For those that help with and contribute to the review interface, a user box is available for you:

This user reviews dataset edits for ClueBot NG to help automatically mass revert vandalism on Wikipedia.

Use it with:

{{User:ClueBot NG/Review User Box}}

Statistics

As ClueBot NG requires a dataset to function, the dataset can also be used to give fairly accurate statistics on its accuracy and operation. Different parts of the dataset are used for training and trialing, so these statistics are not biased.

The exact statistics change and improve frequently as we update the bot. Currently:

Selecting a threshold to optimize total accuracy, the bot correctly classifies over 90% of edits.
Selecting a threshold to hold false positives at a maximal rate of 0.1% (current setting), the bot catches approximately 40% of all vandalism.
Selecting a false positive rate of 0.25% (old setting), the bot catches approximately 55% of all vandalism.

Currently, the trial dataset used to generate these statistics is a random sampling of edits, each reviewed by at least two humans, so statistics are accurate.

Note: These statistics are calculated before post-processing filters. Post-processing filters primarily reduce false positive rate (ie, the actual number of false positives will be less than stated here), but can also slightly reduce catch rate.

Frequently Asked Questions

See the FAQ.

Vandalism Detection Algorithm

ClueBot NG uses a completely different method for classifying vandalism than all previous anti-vandal bots, including the original ClueBot. Previous anti-vandal bots have used a list of simple heuristics and blacklisted words to determine if an edit is vandalism. If a certain number of heuristics matched, the edit was classified as vandalism. This method results in quite a few false positives, because many of the heuristics have legitimate uses in some contexts, and only about a 5% to 10% vandalism catch rate, because most vandalism cannot be detected by these simple heuristics.

ClueBot NG uses a combination of different detection methods which use machine learning at their core. These are described below.

Machine Learning Basics

Instead of a predefined list of rules that a human generates, ClueBot NG learns what is considered vandalism automatically by examining a large list of edits which are preclassified as either constructive or vandalism. Its concept of what is considered vandalism is learned from human vandal-fighters. This list of edits is called a corpus or dataset. The accuracy of the bot largely depends on the size and quality of the dataset. If the dataset is small, contains inaccurately classified edits, or does not contain a random sampling of edits, the bot's performance is severely hampered. The best thing you and other Wikipedians can do to help the bot is to improve the dataset. If you're interested in helping out, please see the Dataset Review Interface section.

Bayesian Classifiers

A few different Bayesian classifiers are used in ClueBot NG. The most basic one works in units of words. Essentially, for each word, the number of constructive edits that add the word, and the number of vandalism edits that add the word, are counted. This is used to form a vandalism-probability for each added word in an edit. The probabilities are combined in such a way that not only words common in vandalism are used, but also words that are uncommon in vandalism can reduce the score.

This differs from a simple list of blacklisted words in that word weights are exactly determined to be optimal, and there's also a large "whitelist" of words, also with optimal weights, that contributes.

Currently, there's also a separate Bayesian classifier that works in units of 2-word phrases. We may add even more Bayesian classifiers in the future that work in different units of words, or words in different contexts.

Scores from the Bayesian classifiers alone are not used. Instead, they're fed into the neural network as simple inputs. This allows the neural network to reduce false positives due to simple blacklisted words, and to catch vandalism that adds unknown words.

Artificial Neural Network

The main component of the ClueBot NG vandalism detection algorithm is the neural network. An artificial neural network is a machine learning technique that can recognize patterns in a set of input data that are more complex than simply determining weights. The input to the ANN used in ClueBot NG is composed of a number of different statistics calculated from the edit, which include, among many other things, the results from the Bayesian classifiers. Each statistic has to be scaled to a number between zero and one before being input to the neural network.

The output of the neural network is used as the main vandalism score for ClueBot NG. As with other machine-learning techniques, the score's accuracy depends on the training dataset size and accuracy.

Threshold Calculation

The ANN generates a vandalism score between 0 and 1, where 1 is 100% sure vandalism. To classify some edits as vandalism, and some as constructive, a threshold must be applied to the score. Scores above the threshold are classified as vandalism, and scores below the threshold are classified as constructive.

The threshold is not randomly chosen by a human, but is instead calculated to match a given false positive rate. When doing actual vandalism detection, it's important to minimize false positives to a very low level. A human selects a false positive rate, which is the percentage of constructive edits incorrectly classified as vandalism. A threshold is calculated to have a false positive rate at or below this percentage, while maximizing catch rate. False positive rate is set by a human, and the bot stays at or below that false positive rate, while catching as much vandalism as possible. The false positive rate is not fixed, but is adjustable.

To make sure the threshold and statistics are accurate and do not give inaccurate statistics or a higher false positive rate than expected, the portion of the dataset used for threshold calculations is kept separate from the training set, and is not used for training. Also, only the most accurate parts of the dataset (currently, the ones that are human-reviewed from the review interface) are used for this calculation. This ensures that all statistics given here are accurate, and that false positives will not exceed the given rate.

Post-Processing Filters

After the core makes its primary vandalism determination, the data is given to the Wikipedia interface. The Wikipedia interface contains some simple logic designed to reduce false positives. Although it also reduces vandalism catch rate a small amount, it also reduces false positive rate, and some of these are mandated by Wikipedia policy.

The first two of these rarely reduce catch rate, but both prevent a fair number of false positives. Note: The false positive rate (and catch rate) are calculated in the core, before post-processing filters. This means that actual false positive rate will be less than stated false positive, often by a significant factor.

User Whitelist — If an edit made by a user that is in a whitelist is classified as vandalism, the edit is not reverted.
Edit Count — If a user has more than a threshold number of edits, and fewer than a threshold percentage of warnings, the edit is not reverted.
1RR — The same user/page combination is not reverted more than once per day, unless the page is on the angry revert list.

Development News/Status

Core Engine

Current version is working well.
Currently writing a dedicated wiki markup parser for more accurate markup-context-specific metrics. (No existing alternative parsers are complete or fast enough)

Dataset Review Interface

Code to import edits into database is finished.
Currently changing logic that determines the end result for an edit.

Dataset Status

We found that the Python dataset downloader we used to generate the training dataset does not generate data that is identical to the live downloader. It's possible that this is greatly reducing the effectiveness of the live bot. We're working on writing shared code for live downloading and dataset generation so we can regenerate the dataset.
This has been fixed and the bot retrained. It's now working much better.
Currently getting more data from the review interface.

Languages

C / C++ — The core is written in C/C++ from scratch.
PHP — The bot shell (Wikipedia interface) is written in PHP, and shares some code with the original ClueBot.
Java — The dataset review interface is written in Java using the Google App framework.
Bash — A few scripts to make it easier to train and maintain the bot are Bash scripts.
Python — Some of the original dataset management and downloader tools were written in Python.

Source Code

The source code for the bot is public, and can be found on github. Please ask the devs for access. If you would like to run the bot for yourself on your own wiki, you should discuss with the devs all the factors involved in making it work properly. You should also be aware that it will only run on a Linux/UNIX system, and the source code can be rather difficult to compile (many dependencies) unless you're experienced with Linux/UNIX systems.

ClueBot NG IRC Feeds

ClueBot NG maintains an IRC-based feed of its data, primary intended for use by other automated tools, located at #wikipedia-en-cbngfeed on the Libera Chat network. It is essentially a copy of the Wikipedia RC feed, but with ClueBot NG's analysis data added. It includes everything the Wikipedia RC feed does, with the addition of the ClueBot NG score and whether it was reverted or not. Format is edit line \003 # score # reason # Reverted or Not reverted.

Note that edits in the feed may not necessarily be in precise order, because ClueBot NG processes them in parallel. Non-reverted edits are usually processed in under a second. Reverted edits can sometimes take up to 10 seconds or more to process due to API lag on reverting.

Information About False Positives

ClueBot NG is not a person, it is an automatic robot that tries to detect vandalism and keep Wikipedia clean. A false positive is when an edit that is not vandalism is incorrectly classified as vandalism.

The bot is not biased against you, your edit, or your viewpoint (unless your edit is vandalism). False positives are rare, but do occur. By handling false positives well without getting upset, you are helping this bot catch almost half of all vandalism on Wikipedia and keep the wiki clean for all of us.

False positives with ClueBot NG are (essentially) inevitable. For it to be effective at catching a great deal of vandalism, a few constructive (or at least, well-intentioned) edits are caught. There are very few false positives, but they do happen. If one of your edits is incorrectly identified as vandalism, simply redo your edit, remove the warning from your talk page, and if you wish, report the false positive. ClueBot NG is not (yet) sentient — it is an automated robot, and if it incorrectly reverts your edit, it does not mean that your edit is bad, or even substandard — it's just a random error in the bot's classification, just like email spam filters sometimes incorrectly classify messages as spam.

The reason false positives are necessary is due to how the bot works. It uses a complex internal algorithm called an Artificial Neural Network that generates a probability that a given edit is vandalism. The probability is usually pretty close, but can sometimes be significantly different from what it should be. Whether or not an edit is classified as vandalism is determined by applying a threshold to this probability. The higher the threshold, the fewer false positives, but also less vandalism is caught. A threshold is selected by assuming a fixed false positive rate (percentage of constructive edits incorrectly classified as vandalism) and optimizing the amount of vandalism caught based on that. This means that there will always be some false positives, and it will always be at around the same percentage of constructive edits. The current setting of the false positive rate is listed in Statistics above.

When false positives occur, they may not be poor quality edits, and there may not even be an apparent reason. If you report the false positive, the bot maintainers will examine it, try to determine why the error occurred, and if possible, improve the bot's accuracy for future similar edits. While it will not prevent false positives, it may help to reduce the number of good-quality edits that are false positives. Also, if the bot's accuracy improves so much that the false positive rate can be reduced without a significant drop in vandalism catch rate, we may be able to reduce the overall number of false positives.

If you want to help significantly improve the bot's accuracy, you can make a difference by contributing to the review interface. This should help us more accurately determine a threshold, catch more vandalism, and eventually, reduce false positives.

To report a false positive, or to see a full list of all false positives, see here.

User box

For those that help with and contribute to the false positive interface, a user box is available for you:

This user reviews false positive reports for ClueBot NG to help revert vandalism on Wikipedia.

Use it with:

{{User:ClueBot NG/Report User Box}}