Scoville

Scoville is a module which calculates the “hotness” of your site’s content. The hotness score is calculated from the number of “hits” (accesses or “reads”) a node has received, but the score “cools down” (decreases) over time if it receives fewer hits, so nodes which are newer but have fewer reads will be “hotter” than nodes which have more reads but are far older. You can use Scoville to create blocks or pages which list recently popular or “hot” content on your site.

Scoville is sponsored by PINGV, Inc. Thanks!

Scoville vs Radioactivity

The functionality that Scoville provides is nearly identical to that provided by the older Radioactivity module. Indeed, Scoville originally came about after a failed attempt at getting Radioactivity to work on a client’s site. Unfortunately, the configuration procedure for the Drupal 7 version of Radioactivity is quite complex, and, as of this writing, nearly completely undocumented. Eventually, we determined that creating a simpler, better documented module to provide this functionality could likely be done faster and with less stress than trying to figure out how to get Radioactivity to work properly, not only for us but for other site builders and developers, and thus, Scoville was born.

It may be that Radioactivity will, in the future, greatly simplify its configuration procedure and/or greatly improve its documentation, and Scoville will be made redundant. Until then, Scoville will serve as a simpler, lighter-weight, more thoroughly documented alternative to Radioactivity.

See this issue in Scoville’s issue queue for more information on how Scoville came about and justification for its co-existence with Radioactivity.

Configuration

Initial configuration

1. Scoville uses the core Statistics module to determine how many hits a node has received, so this module must be enabled if it isn’t already.
2. The Statistics module actually doesn’t do much by default. To have the module start collecting statistics on node accesses, go to Administration > Configuration > System > Statistics and check the “Count content views” box, if it isn’t checked already.
3. By default, Scoville recalculates node hotness on cron runs. If possible, you should configure your server to run cron jobs regularly; ideally using Drush. The calculations that Scoville does can be somewhat intensive, particularly if your site has many active nodes, so relying on Drupal core’s unfortunate “feature” of running cron tasks triggered by web visitors (“poor man’s cron”) is not advised for permformance reasons. Additionally, Scoville’s scoring may be erratic if the amount of time between cron runs is itself erratic; if the time between cron runs will be constant, such every two hours, or every half hour, Scoville’s calculations will seem more predictable.

Scoville configuration

1. Download, install and enable Scoville as you would any other module.
2. Scoville determines which nodes to calculate scores for on a per-content-type basis, for performance (as you may only care about the hotness of news article nodes and not static page nodes, for example). Thus, the first step is to go to the content type list at Administration > Structure > Content types. Find a content type whose nodes Scoville should calculate hotness for and click its corresponding “edit” link. On the content type editing form, find the “Track hotness statistics” checkbox and check it. (As of the time of this writing, this checkbox is in the “Publishing options” fieldset, but it may be moved to somewhere more logical as soon as I can figure out where would be more logical.) Save the form. Repeat this for any other content types you wish Scoville to deal with.
3. Scoville can be more finely configured at Administration > Configuration > System > Statistics > Scoville. The values on this page affect how Scoville calculates hotness for nodes. Each field is fairly well described, but you may wish to see the “How Scoville calculates hotness” section of this documentation below to get a bigger picture of how the numbers affect things. The default values for these fields will probably only be appropriate for a small range of sites, so you will likely want to adjust the values in the future.

Views integration

The intended way to deal with the data that Scoville creates is to create a View which sorts your content by “Hotness,” descending. A block and/or page display for this View can be used as needed. Scoville currently doesn’t feature any pre-built Views, but if you are familiar with building Views, it should be trivial for you to take it from here. Note that Scoville’s “Hotness” field is found in the “Content statistics” group alongside the core Statistics module’s fields.

I suggest that besides creating a View display which sorts by, but doesn't necessarily show, the Hotness field, you create another display, accessible to site administrators only, which displays the Hotness fields as well as the other “Total views” field so you can see how the two relate. It may come in handy when tuning Scoville’s configuration.

You may also want to consider adding a second sort criterion to your View after Hotness to sort by “Total views” or “Views today” so that your View still shows somewhat correct information in the case that Hotness scores are tied — the most likely case being when all your nodes have a score of zero. Speaking of that…

About early scores (or, “Why does all my content have a hotness score of zero?”)

Scoville’s hotness scores will become more accurate over time. When you first enable Scoville (or tell Scoville to calculate hotness for a content type it wasn’t previously working with), Scoville has no idea how hot the content it needs to track is, but it will make a record of the number of hits each node currently has so that it can calculate how many new hits it received as of the next time Scoville calculates hotness. Thus, you will never see hotness scores other than zero until after Scoville’s second run, and the data may not accurately reflect reality until a few more runs after that, when Scoville accumulates more data to work with.

If it’s been a while and it still appears that all of your nodes have a hotness score of zero, check the following:

• Ensure that “Track hotness statistics” is checked on the content type editing form for the relevant content types. See the Scoville configuration section above.
• You may have the “Cold point” set too high in relation to the traffic that your site gets. If a node has a hotness score of zero and gets five hits between Scoville runs, Scoville will assign it a hotness score of five, but if you have the “Cold point” set to five or above, Scoville will consider this score to be equivalent to zero and not bother saving the new score in the database. (This is assuming the “Hit points” value is set to the default of one.)
• Sorry, but maybe your site just isn’t getting much traffic. This is where having another display on your View which shows the total views for your nodes can be useful. If your total views is not going up, then your hotness score will not go up either.
• If you are occasionally seeing content go hot, but it then cools down and drops beneath the cold point too quickly, try increasing the “Hourly cooling rate” value so that hotness scores “cool” more slowly (higher rates mean slower cooling).

How Scoville calculates hotness

The utility of Scoville will be affected by how you configure its settings, but it will be easier to configure Scoville to suit your needs if you understand how it’s working behind the scenes. What follows is a run-through of what calculations Scoville is doing and where each of its configuration settings come into play whenever it recalculates hotness scores.

1. First, Scoville “cools” all previous hotness scores by multiplying all hotness scores greater than zero by a multiplier. This multiplier is calculated by examining the “Hourly cooling rate” and taking into account how many hours, or fractions of an hour, have passed since its last run. For example, if the hourly cooling rate is .7 and one hour is passed, the multiplier will be .7. If half an hour has passed, the multiplier will be about .837, because the effect of multiplying a number by .837, then multiplying the result by .837 will be nearly equivalent to multiplying it by .7. (In mathspeak, the multiplier is determined by raising the hourly cooling rate value to the power of the fractional number of hours since the last run, so .7^.5 ≈ .837.) Note that higher cooling rate values mean that scores will be higher after they are multiplied; in other words, setting a cooling rate of .9 will mean that nodes stay hotter longer than if the rate is .7. Setting the rate to .5 will cause content to cool very quickly indeed; a rate that low probably should not be used unless it’s desirable that recently less popular content gives way to more popular content very quickly. This graph gives an example of how the cooling rate affects a hypothetical node which receives most of its hits soon after publication, on a site where hotness rates are calculated every half hour. Note that the green line, representing a rate of .5, peaks a half hour after the first hotness calculation; the yellow line, representing a rate of .7, peaks one hour later. However, the red line, representing a rate of .9, peaks a full two hours later, corresponding with the second upswing in new node hits since the last Scoville run, and stays very hot for a long time after.
2. Next, Scoville looks at the Statistics module’s data and fetches statistics for all nodes which are of content types that Scoville has been told to collect data for and have had at least one access since the last run. Scoville calculates how many new hits each of those nodes has had, multiplies that by the “Hit points” value, and adds that to the node’s current hotness score. If the node’s new score is above the “Cold point” value, Scoville saves the new score to the database. Note this means that, if Scoville is doing calculation runs frequently, the number of new hits a node may collect between runs may not be enough to propel its hotness score past the cold point and get it saved to the database if the cold point is set too high.
3. Scoville now saves the current hit count for all nodes it’s tracking data for. On its next calculation run, this hit count will be used to determine the number of new hits for the calculation in the previous step.
4. The more times Scoville runs and cools node hotness scores, the closer those scores will come to zero, particularly if the node does not get a significant number of new hits. To that end, Scoville’s final step is to find all nodes which have a hotness score which is equal to or below the “Cold point” at this point in time and set its score to flat zero. This reduces the amount of work the database has to do on the first step of its next run, since there’s not much point in working to drive already very small numbers closer and closer to zero. However, if, in the future, the node is able to receive enough new hits to propel its score beyond the cold point, Scoville will once again track its hotness score in the database (at least until it drops beneath the cold point again).
5. Finally, Scoville makes a note of the time it ran at, so that on its next run it can determine how much time has passed since its last run.

Questions? Suggestions? Need help?

Please open an issue on Scoville’s issue queue or contact the author and I’ll get back to you soon. Thanks for trying Scoville!