Editing IRStats2 (section)

== Example: Creating a processor for citation statistics ==

IRStats2 can evaluate any field or combination of fields in the above mentioned datasets. For this, new datatypes and associated Stats::Processor modules must be created.

A simple case is statistics on citation count of publications, since the datatype of the associated field is a scalar.

Citation counts can be harvested using the [http://files.eprints.org/815/  Citation count dataset and import plugins] from Queensland University of Technology. Upon following the installation procedure, the fields scopus_impact, wos_impact and gscholar_impact are created in the EPrint table.

=== Modifying an existing Processor module ===

We create now a Processor module that evaluates the scopus_impact field and provides a scopus_citations datatype. 

First, we inspect the Stats::Processor::EPrint Processor modules to find out which Processor module is best suited for adapting. A good candidate is lib/plugins/EPrints/Plugin/Stats/Processor/EPrint/DocumentAccess.pm. We copy it to archives/{repo}/cfg/plugins/EPrints/Plugin/Stats/Process/EPrint/ScopusCitations.pm and modify it as follows:

<pre>
package EPrints::Plugin::Stats::Processor::EPrint::ScopusCitations;

our @ISA = qw/ EPrints::Plugin::Stats::Processor /;

use strict;

sub new
{
	my( $class, %params ) = @_;
	my $self = $class->SUPER::new( %params );

#  provide the name of the datatype
	$self->{provides} = [ "scopus_citations" ];

	$self->{disable} = 0;

	return $self;
}


sub process_record
{
	my ($self, $eprint ) = @_;

	my $epid = $eprint->get_id;
	return unless( defined $epid );

	my $status = $eprint->get_value( "eprint_status" );
	unless( defined $status ) 
	{
##		print STDERR "IRStats2: warning - status not set for eprint=".$eprint->get_id."\n";
		return;
	}

	return unless( $status eq 'archive' );

	my $datestamp = $eprint->get_value( "datestamp" ) || $eprint->get_value( "lastmod" );

	my $date = $self->parse_datestamp( $self->{session}, $datestamp );

	my $year = $date->{year};
	my $month = $date->{month};
	my $day = $date->{day};

# get the citation count
	my $scopus_citation_count = $eprint->get_value( "scopus_impact" );

# store the citation count per eprint id
	if (defined $scopus_citation_count)
	{
		$self->{cache}->{"$year$month$day"}->{$epid}->{scopus} = $scopus_citation_count;
	}
}

1;
</pre>

Next, we need to enable the new Processor plugin in our IRStats2 configuration file. In the Bazaar config section, add the following line:

<pre>
$c->{plugins}{"Stats::Processor::EPrint::ScopusCitations"}{params}{disable} = 0;
</pre>

In the Reports section, we can add now a new citation report that uses the scopus_citations datatype:

<pre>
        citations => {
                items => [
                { plugin => 'ReportHeader' },
                {
                        plugin => 'Grid',
                        options => {
                                items => [
                                {
                                        plugin => 'Table',
                                        datatype => 'scopus_citations',
                                        options => {
                                                limit => 10,
                                                top => 'eprint',
                                                title_phrase => 'top_scopus_citations',
                                        },
                                },]
                        },
                },
                {
                        plugin => 'Grid',
                        options => {
                                items => [
                                {
                                        plugin => 'Table',
                                        datatype => 'scopus_citations',
                                        options => {
                                                limit => 10,
                                                top => 'authors',
                                                title_phrase => 'top_scopus_citations_authors'
                                        }
                                },]
                        },
                },
                ],
                category => 'advanced',
        },
</pre>

Also, the phrases in irstats2.xml must be completed accordingly.


=== Generalization ===

For each citation datum, a processor module is required. We see, that these will differ only slightly,
namely in the datatype declaration in the new() method, and in the processing of the citation datum field 
in the last part of the process_record() method. Therefore, we can generalize the processor by providing 
an abstract value tracker module. It does the following:

In the new() method, it provides an abstract value tracker datatype. Note that the plugin is disabled.
In the process_record() method, it makes reference to the field that is processed and a value_id to where the value will be stored.

<pre>
package EPrints::Plugin::Stats::Processor::EPrint::AbstractValueTracker;

our @ISA = qw/ EPrints::Plugin::Stats::Processor /;

use strict;

sub new
{
	my( $class, %params ) = @_;
	my $self = $class->SUPER::new( %params );
	
	$self->{provides} = [ "abstract_value_tracker" ];
	$self->{disable} = 1;
	
	$self->{field_id} = 'DEFINE IN SUBCLASS';
	$self->{value_id} = 'DEFINE IN SUBCLASS';
	
	return $self;
}


sub process_record
{
	my ($self, $eprint ) = @_;
	
	my $epid = $eprint->get_id;
	return unless( defined $epid );

	my $status = $eprint->get_value( "eprint_status" );
	unless( defined $status )
	{
#		print STDERR "IRStats2: warning - status not set for eprint=".$eprint->get_id."\n";
		return;
	}

	return unless( $status eq 'archive' );

	my $datestamp = $eprint->get_value( "datestamp" ) || $eprint->get_value( "lastmod" );

	my $date = $self->parse_datestamp( $self->{session}, $datestamp );

	my $year = $date->{year};
	my $month = $date->{month};
	my $day = $date->{day};

	my $value = $eprint->value($self->{field_id});

	if (defined $value)
	{
		$self->{cache}->{"$year$month$day"}->{$epid}->{$self->{value_id}} = $value;
    }
}

1;
</pre>


Now, the declaration of new scalar datatypes reduces to the task to defining a subclass for each datatype, 
and to declaring the assocation between the datatype and the field to be processed in the IRStats2 configuration:

<pre>
package EPrints::Plugin::Stats::Processor::EPrint::ScopusCitations;

use EPrints::Plugin::Stats::Processor::EPrint::AbstractValueTracker;
our @ISA = qw/ EPrints::Plugin::Stats::Processor::EPrint::AbstractValueTracker /;

use strict;

sub new
{
	my( $class, %params ) = @_;
	my $self = $class->SUPER::new( %params );
	my $repo = $self->repository;

	$self->{provides} = [ "scopus_citations" ];

	$self->{disable} = 0;
	
	$self->{field_id} = $repo->config('irstats2','scopus_citations','field_id');
	$self->{value_id} = 'scopus';

	return $self;
}

1;
</pre>

<pre>
############
# Datatypes
############
# Declare as $c->{irstats2}->{datatypename}->{field_id} = 'fieldname';

$c->{irstats2}->{scopus_citations}->{field_id} = 'scopus_impact';
</pre>

=== Specific requirements by Scopus and Web of Science ===

If you have a valid API key to the Scopus and Web of Science APIs, it is allowed by both database producers to show aggregate citation counts, given that a link back to the record in the Scopus and Web of Science database and attribution to their brand is provided. I leave that to you to figure out how this can be achieved in the Table view.

Google Scholar does not allow to harvest citation counts.