Getting started with NBDS

This page should give a short introduction into NBDS and how you could work with the system. At the beginning you need some Neuron objects. Neurons are like vertexes in a graph – just nodes that contain information. You can create neurons by call the constructor with two arguments ($name, $value). You can use a neuron very very flexible, but in this short example, the name is used as category (or group) of the value. In this case ‘rewe’ is a super_market and ‘dresden’ is a city. The underscore in ‘super_market’ was chosen by me – of course you can use a whitespace if you dont want to use underscores.

$neuron1 = new Neuron('super_market', 'rewe');
$neuron2 = new Neuron('city', 'dresden');

This is the way you can create a Neuron object. Make sure that you have the following file included:

require_once 'Space.class.php';

Of course you need an Axon object between these neurons. So let’s create an Axon object. The axon exists between neuron1 and neuron2 how the first two arguments show. The third argument shows ‘true’, which means that the axon is bi-directional (can be used in both directions). For route() and other operations it is necessary, if you want to possibly run through both directions. If you set this argument to ‘false’, the directed axon works just from – in this example neuron1 to neuron2. For this demonstration we set the name of the axon to ‘is_in’, because this points out the relation of the two neurons with this axon. If you can see here, NBDS can also emulate a relational data model. In this scenario you use the axons as connection between tables and the neuron as tables. The problem is that you first have to get the object stored in this neuron – but fundamentally it is possible.

$axon12 = new Axon($neuron1->getId(), $neuron2->getId(), true);
$axon12->setName('is_in');

Setup the Space

Alright! After these steps you can add the created components to the NBDS Space object. The Space is the manager of all axons and neurons. It handles connections between neurons, runs operations on the network and serializes your network structure.

$space = new Space();
$space->addNeuron($neuron1);
$space->addNeuron($neuron2);
$space->addAxon($axon12);

After that, you’ve got a simple NDBS network that contains information. Note that a neuron can be a container for everything. You can put a lot of things into it (use setAttribute(), setValue(), setDescription()). So let’s add another neuron and axon to the Space.

$neuron3 = new Neuron('fruit', 'banana');
$neuron3->setAttribute('keywords', array('fruit', 'yellow','long'));
$neuron3->setAttribute('valid', true);
$space->addNeuron($neuron3);
$axon13 = new Axon($neuron1->getId(), $neuron3->getId(), true);
$axon13->setName('you_can_buy');
$space->addAxon($axon13);

After doing so, you’ve got three neurons and two axons in your space. The neuron and axon added above show a relation to the first neuron ($neuron1). It means that you can buy ‘bananas’ in ‘rewe’. The neuron also contains some keywords of the banana stored in the attributes array of the neuron.

Performing operations

According to the operations document, which contains all operations that you can perform on the Space, this is the signature of the select() operation:

select($type, $attr, $cond_operator, $cond_value, $inc_used = false)

For example:

$result = $space->select(NBDS_NEURON, NBDS_NAME, NBDS_IS, 'fruit');

Okay, we are select all neurons with a name equal to ‘fruit’. Or:

$result = $space->select(NBDS_NEURON, NBDS_VALUE, NBDS_IN, array('rewe','dresden' );

This will return $neuron1 and $neuron2, because their values are in ‘rewe’ OR ‘dresden’. You can perform a lot of other operations with select. See the list of conditions below:

  • NBDS_IN … equals a list of entries
  • NBDS_IS … equals on value
  • NBDS_BETWEEN … is between two values (works just for numeric values)
  • NBDS_LIKE … works on text with ‘%’ a placeholder, that can be set before, after and before-and-after the search term (but not in between).

You can use select() for these attributes of neurons and axons:

  • NBDS_NAME
  • NBDS_ID
  • NBDS_USED
  • NBDS_DESC
  • NBDS_VALUE

The next operation is the neighbor() operation. This operation is very simple but very powerful at the same time. The arguments are the ID of the start neuron and the steps of neighborhood searches. If you choose the arguments like in the method call below, you will get all neighbors of neuron1 with the distance of one step. The result set contains all neurons in our scenario, because all of the created neurons are neighbor of neuron1.

$result = $space->neighbor($neuron1->getId(), 1);

Route() is the next relevant operation. With this operation you can route from one neuron to another and you get back the successful routes in an array. For instance, route from neuron3 to neuron2. This works just with a step over neuron1 (2<->1<->3).

$options = array(
NBDS_MAX_STEPS => int, //give an explicit max steps bound
NBDS_RECOGNIZE_RESULTS => bool, //store results in the mnemonics array

NBDS_INCREMENT_USED => <NBDS_CONSTANT> //increment the counter of all affected neurons, can be NBDS_DISTINCT or NBDS_ALL
$result = $space->route($neuron3->getId(), $neuron2->getId(), $options);

This operation returns the route from neuron3 to neuron2. The option array can also be empty (array()) – the default values were used.

Some operations are not so important, but they should be mentioned. Translate($type, $id) where $type can be NBDS_NEURON or NBDS_AXON and $id can be one ID or an array of IDs is a operation that translates IDs to object and returns these objects. The connection($from, $to, $type) is a operation that returns – unlike route() – the objects of a route(). Internally a route() operation would be performed and you get back all components on this route that you have specified in $type (can be NBDS_NEURON | NBDS_AXON | NBDS_ALL). With the lookup($type, $value, $lookup = NBDS_NAME) operation you can perform a lookup and reverse-lookup to IDs of names or names of IDs for both components NBDS_NEURON and NBDS_AXON. Use the arguments $type (NBDS_NEURON or NBDS_AXON), $value (array of known IDs or names) and the attribute you want to lookup (NBDS_NAME or NBDS_ID).

If you want to insert self-written functionality into NBDS you can use the callback() function. With callback($selection, $components, $function_name) you can apply a self-written function ($function_name as string) on a selection of IDs ($selection as array of IDs) for neurons or axons ($components as NBDS_NEURON or NBDS_AXON).

Another feature of NBDS is the aggregate() operation. Use aggregate($selection, $components, $attr, $function, $value1, $value2 = null) where $selection is again an array of IDs, $components equals NBDS_NEURON or NBDS_AXON and the attribute ($attr) should be an NBDS constant like NBDS_NAME, NBDS_ID, NBDS_USED, NBDS_DESC, NBDS_WEIGHT (just with NBDS_AXON) and NBDS_VALUE. The $function argument is quite complex. You can use:

  • ‘<‘, returns ids that match this criteria with $value1
  • ‘>’, returns ids that match this criteria with $value1
  • ‘<=’, returns ids that match this criteria with $value1
  • ‘>=’, returns ids that match this criteria with $value1
  • ‘==’, returns ids that match this criteria with $value1
  • ‘sum’, returns the sum of all objects for an attribute
  • ‘median’, returns the median of all objects for an attribute
  • ‘mean’, returns the mean of all objects for an attribute
  • ‘highest’, returns the highest value of all objects for an attribute
  • ‘lowest’, returns the lowest value of all objects for an attribute
  • ‘multi’, returns the result of multiplication of all objects for an attribute
  • ‘count’, returns the number of all objects that match this criteria (value1)
  • ‘between’, returns ids of all objects between value1 and value2 for an attribute
  • ‘concat’, returns the concatenated string value.

The two last arguments are the values to compare. The second compare value is by default null, because you just needed in special cases (e. g. if you want to use ‘between’).

After your work on the Space object was done, use the SpaceManager object to store your network.

$sm = new SpaceManager();
$sm->setSpace($space);
$sm->serialize("test.nbds");

If you want to load a NBDS space you can also use the SpaceManger object.

$sm = new SpaceManager();
$sm->unserialize("test.nbds");
$space = $sm->getSpace();

After these instructions you have loaded the Space object that you have stored before in in ‘test.nbds’. Note that ‘test.nbds’ can be every valid file name, that you’ve chosen before.

Thanks for reading the first tutorial for NBDS. I hope you enjoy using the system. Don’t hesitate to give any feedback  and contact me.

If you have questions about an operation, consult these documents: