A Javascript implementation of the k-Nearest-Neighbor machine-learning algorithm.
npm install knearest
In this example, consider the following:
- You have real estate data you'd like stored in mongodb.
- Your data consists of stats for rooms, area (in square meters), and type.
- You have a new data point, but you don't know whether it's a house, apartment, or flat.
- You'd like to use a Node.js script to guess the type based on your existing dataset.
const Machine = require('../knearest');
const chalk = require('chalk');
// Some data to get us going. It's important that your data is well-clustered,
// because statistical noise will render this algorithm less useful.
let machine= new Machine({
k: 5, // Optional. Defaults to 1.
props: [
{
name: 'rooms',
type: Number
},
{
name: 'area',
type: Number
},
{
name: 'type',
type: String
}
], // Required. This is the schema of your dataset. All nodes will be checked against this.
nodes: [ // Required. There must be some data to seed the AI's knowledge
{ rooms: 1, area: 350, type: 'apartment' },
{ rooms: 2, area: 300, type: 'apartment' },
{ rooms: 3, area: 300, type: 'apartment' },
{ rooms: 4, area: 250, type: 'apartment' },
{ rooms: 4, area: 500, type: 'apartment' },
{ rooms: 4, area: 400, type: 'apartment' },
{ rooms: 5, area: 450, type: 'apartment' },
{ rooms: 7, area: 850, type: 'house' },
{ rooms: 7, area: 900, type: 'house' },
{ rooms: 7, area: 1200, type: 'house' },
{ rooms: 8, area: 1500, type: 'house' },
{ rooms: 9, area: 1300, type: 'house' },
{ rooms: 8, area: 1240, type: 'house' },
{ rooms: 10, area: 1700, type: 'house' },
{ rooms: 9, area: 1000, type: 'house' },
{ rooms: 1, area: 800, type: 'flat' },
{ rooms: 3, area: 900, type: 'flat' },
{ rooms: 2, area: 700, type: 'flat' },
{ rooms: 1, area: 900, type: 'flat' },
{ rooms: 2, area: 1150, type: 'flat' },
{ rooms: 1, area: 1000, type: 'flat' },
{ rooms: 2, area: 1200, type: 'flat' },
{ rooms: 1, area: 1300, type: 'flat' }
],
data: {
store: 'mongo', // Optional. Defaults to 'memory'
url: 'mongodb://localhost:27017/knearest' // Required if store = 'mongo'
},
verbose: true, // Optional. Toggle console output. Defaults to false
stringAlgorithm: 'Levenshtein' // Optional. Defaults to 'Jaro-Winkler'
});
// knearest is also an EventEmitter.
// The below line will print to terminal each time a node is added.
machine.on('node', console.log);
// Let's add a new data point, this time without a "type".
// We want to guess the value of "type".
// .guess(property, node) returns a bluebird Promise.
machine.guess('type', {rooms: 12, area: 1375 })
.then((result) => {
console.log('Value of "' + result.feature + '" is probably ' + chalk.green(result.value) + ' ('+result.elapsed+'ms)');
});
Type: Array
Required: Yes
Description: The features to be used in the algorithm. These must correspond to your dataset. Similar to a schema.
Type: Array
Required: Yes
Description: The dataset to train with. These must have a consistent structure matching the schema in props.
Type: String
Required: No
Default: ''
Description: The namespace for your data. Will be added as a prefix to your DB table names.
Type: Number
Required: No
Default: 1
Description: The value of k, i.e. how many nearest neighbors to guess with.
Type: Object
Required: No
Default: { store: 'memory' }
Description: A data configuration object for use with data adapters. Defaults to 'memory'.
If you want to use a data adapter, specify it here.
The MongoDB adapter accepts an object like this:
{
store: 'mongo',
url: 'mongodb://localhost:27017/knearest' // Required if store = 'mongo'
}Type: Boolean
Required: No
Default: false
Description: Toggle console output. Defaults to false
Type: Boolean
Required: No
Default: 'Jaro-Winkler'
Description: The String Distance Algorithm to use for calculating string similarity. Accepts either 'Jaro-Winkler', 'Levenshtein', or 'Dice'.
Create an instance using options object.
Guess the value of prop on data, based on the nodes supplied to the constructor. Depending on the size of the dataset, this may take some time.
Add a single training node. Use this to add training data outside of the nodes option in the constructor.
Add multiple training nodes. Use this to add training data outside of the nodes option in the constructor.
Accepts either:
- A String url for directly downloading from API endpoints. Note that all data will be validated against the schema in
options.props. - an Array of nodes to add to the db. Again, all data will be validated against
options.propsto enforce data integrity.
knearest is an Event Emitter, so you can use the standard .on(event, callback) method to listen for emitted data.
Machine.on('ready', () => )Fired when the library has ingested all data and is ready to guess new stuff.
Machine.on('node', ({ id: String, features: Object }) => )Fired when a node is added to the dataset.
Machine.on('guessing', ({ feature: String, k: Number }) => )Fired immediately when .guess() is called.
Machine.on('guess', ({ elapsed: Number, feature: String, value: Number }) => )Fired when a guess is complete.
knearest uses an adapter system to interface with databases. This is necessary because the 'memory' adapter (which is default) will only be able to handle what will fit in RAM, which is usually not very much. ML applications generally require a lot of data, so a database is the only serious option for production use.
See the Writing Adapters section for more info on how to build an adapter.
This is the default adapter, which will simply store all data points on the machine object in runtime, with nodes at this.nodes and arcs at this.arcs. Useful for demos and as a ML beginners' sandbox, to learn how the k-nearest-neighbors algorithm works. Not suitable for production use or large datasets.
This is the MongoDB adapter. It allows you to work with datasets as large as your MongoDB instance will hold.
- Tests are needed, will come soon.
We are accepting pull requests for the following adapters:
- PostgreSQL
- RethinkDB
- MySQL
Any suggestions or errors should be raised as an Issue on this repository.