modules/radioactivity/README.txt

$Id: README.txt,v 1.1 2008/03/31 09:24:01 skiminki Exp $

OVERVIEW
========

This module is written to provide better metrics for node ranking
based on viewing rate. The rank information may be used on views to
provide different 'most read' lists, etc.

Particularly on news sites, the node_counter.daycount isn't really
adequate. On those sites, metrics that measure hour-scale and
week-scale activity might become important additions. Furthermore, the
fact that node_counter.daycount gets zeroed once a day makes it
questionable source for 'most read' lists. Resetting the daycount
makes those lists erratic until user activity has normalized the
situation.


SUPPORTED DATABASE BACKENDS
===========================

This module is developed for:
- MySQL 5.0.XX
- PostgreSQL 8.0.XX
Older versions might also work.


ALGORITHM
=========

The node ranking is based on radioactivity model. The algorithm
behind the model is pretty simple:

* Viewing a node adds energy to it and makes it 'hotter'.

* The energy decays at a rate defined by the half-life period, making
  it 'cooler'. For example, a click is worth 1 energy unit at the time
  of clicking, 0.5 energy units after one half-life period, 0.25
  energy units after two half-life periods, and so on.

Therefore, nodes that get lots of clicks stay hotter while inactive
nodes stay cooler. Note that the model is continuous, meaning that the
click energy is not degraded only once per half-life. Actually, it may
be degraded as often as required to get better precision. Degrading
more often means less energy is reduced per iteration.


IN PRACTICE
===========

By keeping half-life period short, let's say one hour, you'll get a
metric that reflects current node view rate. Using that metric in a
view, you can create a "most viewed nodes right now" list. By keeping
longer half-life, let's say 12 hours, you can setup a view that
roughly reflects todays most read nodes. The module supports setting
up multiple different decay rates.

There's a decay granularity setting in the
'admin/settings/radioactivity' page. You might want to keep that
somewhere like 10% of the minimum half-life time of your profiles to
get reasonable precision. You might go as low as 60 seconds on a busy
site, but keep an eye on the cron run duration. This granularity value
is the minimum interval between decay calculations. The actual
interval is, however, the minimum of cron-run period and this value.


ACKNOWLEDGEMENTS
================

The development of this module was funded by Kustannusosakeyhtiö Uusi
Suomi, which runs news site www.uusisuomi.fi (in Finnish).
1	$Id: README.txt,v 1.1 2008/03/31 09:24:01 skiminki Exp $
2
3	OVERVIEW
4	========
5
6	This module is written to provide better metrics for node ranking
7	based on viewing rate. The rank information may be used on views to
8	provide different 'most read' lists, etc.
9
10	Particularly on news sites, the node_counter.daycount isn't really
11	adequate. On those sites, metrics that measure hour-scale and
12	week-scale activity might become important additions. Furthermore, the
13	fact that node_counter.daycount gets zeroed once a day makes it
14	questionable source for 'most read' lists. Resetting the daycount
15	makes those lists erratic until user activity has normalized the
16	situation.
17
18
19	SUPPORTED DATABASE BACKENDS
20	===========================
21
22	This module is developed for:
23	- MySQL 5.0.XX
24	- PostgreSQL 8.0.XX
25	Older versions might also work.
26
27
28	ALGORITHM
29	=========
30
31	The node ranking is based on radioactivity model. The algorithm
32	behind the model is pretty simple:
33
34	* Viewing a node adds energy to it and makes it 'hotter'.
35
36	* The energy decays at a rate defined by the half-life period, making
37	it 'cooler'. For example, a click is worth 1 energy unit at the time
38	of clicking, 0.5 energy units after one half-life period, 0.25
39	energy units after two half-life periods, and so on.
40
41	Therefore, nodes that get lots of clicks stay hotter while inactive
42	nodes stay cooler. Note that the model is continuous, meaning that the
43	click energy is not degraded only once per half-life. Actually, it may
44	be degraded as often as required to get better precision. Degrading
45	more often means less energy is reduced per iteration.
46
47
48	IN PRACTICE
49	===========
50
51	By keeping half-life period short, let's say one hour, you'll get a
52	metric that reflects current node view rate. Using that metric in a
53	view, you can create a "most viewed nodes right now" list. By keeping
54	longer half-life, let's say 12 hours, you can setup a view that
55	roughly reflects todays most read nodes. The module supports setting
56	up multiple different decay rates.
57
58	There's a decay granularity setting in the
59	'admin/settings/radioactivity' page. You might want to keep that
60	somewhere like 10% of the minimum half-life time of your profiles to
61	get reasonable precision. You might go as low as 60 seconds on a busy
62	site, but keep an eye on the cron run duration. This granularity value
63	is the minimum interval between decay calculations. The actual
64	interval is, however, the minimum of cron-run period and this value.
65
66
67	ACKNOWLEDGEMENTS
68	================
69
70	The development of this module was funded by Kustannusosakeyhtiö Uusi
71	Suomi, which runs news site www.uusisuomi.fi (in Finnish).