IRStats 2 Technical Documentation - Revision history

Th.lauke@arcor.de: categories removed

2019-08-08T16:54:09Z

categories removed

← Older revision		Revision as of 16:54, 8 August 2019
Line 1:		Line 1:
	~~[[Category:Bazaar_Package]]~~
	~~[[Category:IRStats]]~~
	~~[[Category:Plugins]]~~
	~~[[Category:Eprints3.3]]~~
	~~[[Category:Eprints3.2]]~~
	[[Category:Obsolete]]		[[Category:Obsolete]]

Kgoetz: adding categories

2018-08-30T06:53:47Z

adding categories

← Older revision		Revision as of 06:53, 30 August 2018
Line 1:		Line 1:
	[[Category:Bazaar_Package]]		[[Category:Bazaar_Package]]
			[[Category:IRStats]]
			[[Category:Plugins]]
			[[Category:Eprints3.3]]
			[[Category:Eprints3.2]]
			[[Category:Obsolete]]

	<div style="border: 2px solid red; background-color: yellow;padding:10px">IRStat2 documentation is being moved - please see [[IRStats2]]</div>		<div style="border: 2px solid red; background-color: yellow;padding:10px">IRStat2 documentation is being moved - please see [[IRStats2]]</div>
	<br />		<br />

Rwf1v07@soton.ac.uk at 10:27, 13 December 2017

2017-12-13T10:27:23Z

← Older revision		Revision as of 10:27, 13 December 2017
Line 1:		Line 1:
	[[Category:Bazaar_Package]]		[[Category:Bazaar_Package]]
	<div style="border: 2px solid red; background-color: yellow;padding:10px">IRStat2 documentation is being moved - please see [[IRStats2]]</div>		<div style="border: 2px solid red; background-color: yellow;padding:10px">IRStat2 documentation is being moved - please see [[IRStats2]]</div>
			<br />
	== Configuration ==		== Configuration ==

Rwf1v07@soton.ac.uk at 10:26, 13 December 2017

2017-12-13T10:26:51Z

← Older revision		Revision as of 10:26, 13 December 2017
Line 1:		Line 1:
	[[Category:Bazaar_Package]]		[[Category:Bazaar_Package]]
	<div style="border: 2px solid red; background-color: yellow;padding:10px">IRStat2 documentation is being moved - please see [[IRStats2]]</div>		<div style="border: 2px solid red; background-color: yellow;padding:10px">IRStat2 documentation is being moved - please see [[IRStats2]]</div>

	== Configuration ==		== Configuration ==

Rwf1v07@soton.ac.uk at 10:26, 13 December 2017

2017-12-13T10:26:43Z

← Older revision		Revision as of 10:26, 13 December 2017
Line 1:		Line 1:
	[[Category:Bazaar_Package]]		[[Category:Bazaar_Package]]
			<div style="border: 2px solid red; background-color: yellow;padding:10px">IRStat2 documentation is being moved - please see [[IRStats2]]</div>
	== Configuration ==		== Configuration ==

Martin.braendle@id.uzh.ch: /* Generalization */

2015-09-10T12:19:50Z

Generalization

@@ Line 431: / Line 431: @@
 === Generalization ===
-(will follow soon: description to create a generic scalar value tracker)
+For each citation datum, a processor module is required. We see, that these will differ only slightly,
 === Specific requirements by Scopus and Web of Science ===

Martin.braendle@id.uzh.ch: Example how to create a processor module added (not yet finished)

2015-09-04T15:47:58Z

Example how to create a processor module added (not yet finished)

← Older revision		Revision as of 15:47, 4 September 2015
Line 306:		Line 306:

	The View prefixed by "Google" means that they are rendered by the Google Chart Javascript library. Important note: no data is sent to Google!! The data is, instead, drawn by the browser client using SVG.		The View prefixed by "Google" means that they are rendered by the Google Chart Javascript library. Important note: no data is sent to Google!! The data is, instead, drawn by the browser client using SVG.

			== 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 ===

			(will follow soon: description to create a generic scalar value tracker)

			=== 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.

Af05v@ecs.soton.ac.uk at 15:22, 5 December 2014

2014-12-05T15:22:16Z

← Older revision		Revision as of 15:22, 5 December 2014
Line 1:		Line 1:
			[[Category:Bazaar_Package]]
	== Configuration ==		== Configuration ==

Af05v@ecs.soton.ac.uk: /* Data from scripts */

2014-12-05T15:21:53Z

Data from scripts

← Older revision		Revision as of 15:21, 5 December 2014
Line 151:		Line 151:

	=== Data from scripts===		=== Data from scripts===
	Main API		==== Main API ====

			<pre>
	# get the IRStats2 handler, required to query IRStats2		# get the IRStats2 handler, required to query IRStats2
	my $handler = $repo->plugin( "Stats::Handler" );		my $handler = $repo->plugin( "Stats::Handler" );
Line 180:		Line 181:
	my $export = $repo->plugin( "Stats::Export::CSV" );		my $export = $repo->plugin( "Stats::Export::CSV" );
	$data->export( { export_plugin => $export } );		$data->export( { export_plugin => $export } );
			</pre>

	Full Examples		==== Full Examples ====
	Actually those are not really full examples. They assume you can write the beginning of a PERL script and that you have already instantiated the Stats Handler (cf. above) as $handler.		Actually those are not really full examples. They assume you can write the beginning of a PERL script and that you have already instantiated the Stats Handler (cf. above) as $handler.

			<pre>
	# How many downloads in total over the entire repository		# How many downloads in total over the entire repository

	my $ctx = $handler->context( { datatype => "downloads" } );		my $ctx = $handler->context( { datatype => "downloads" } );
	printf "I got %d downloads\n", $handler->data( $ctx )->select->sum_all;		printf "I got %d downloads\n", $handler->data( $ctx )->select->sum_all;
			</pre>
			<pre>
	# How many downloads in 2013 over the entire repository		# How many downloads in 2013 over the entire repository

	my $ctx = $handler->context( { datatype => "downloads", range => "2013" } );		my $ctx = $handler->context( { datatype => "downloads", range => "2013" } );
	printf "I got %d downloads\n", $handler->data( $ctx )->select->sum_all;		printf "I got %d downloads\n", $handler->data( $ctx )->select->sum_all;
			</pre>
			<pre>
	# The top 5 EPrints over the entire repository		# The top 5 EPrints over the entire repository

Line 204:		Line 209:
	printf "EPrint %d got %d downloads\n", $_->{eprintid}, $_->{count};		printf "EPrint %d got %d downloads\n", $_->{eprintid}, $_->{count};
	}		}
			</pre>
			<pre>
	# The top 10 Subjects (let's assume LoC) for deposits (not downloads!!)		# The top 10 Subjects (let's assume LoC) for deposits (not downloads!!)

Line 216:		Line 222:
	printf "%d) %s with %d items deposited\n", $i++, $_->{set_value}, $_->{count};		printf "%d) %s with %d items deposited\n", $i++, $_->{set_value}, $_->{count};
	}		}
			</pre>
			<pre>
	# The top 5 downloaded EPrints for LoC Subject "D1"		# The top 5 downloaded EPrints for LoC Subject "D1"

Line 228:		Line 235:
	printf "%d) EPrintd %d with %d downloads\n", $i++, $_->{eprintid}, $_->{count};		printf "%d) EPrintd %d with %d downloads\n", $i++, $_->{eprintid}, $_->{count};
	}		}
			</pre>

	Embedding data		=== Embedding data ===
	This is similar to retrieving data from scripts (cf. section above) but with a few extra options:		This is similar to retrieving data from scripts (cf. section above) but with a few extra options:

	"view": the name of the Stats::View plug-in which will draw the requested stuff (a Table? a Graph? etc.)		;view: the name of the Stats::View plug-in which will draw the requested stuff (a Table? a Graph? etc.)
	"container_id": the DOM element "id", where the drawn stuff will be inserted on the page (if the Ajax callback is successful)		;container_id: the DOM element "id", where the drawn stuff will be inserted on the page (if the Ajax callback is successful)

	Then there exists a number of options proper to each View plug-in. See the provided examples below.		Then there exists a number of options proper to each View plug-in. See the provided examples below.

	Graphs		==== Graphs ====
	The typical example is to embed the global downloads graph. This is usually the first displayed item on the IRStats2 main report page (/cgi/stats/report).		The typical example is to embed the global downloads graph. This is usually the first displayed item on the IRStats2 main report page (/cgi/stats/report).

	This will basically insert the downloads graph into the "mygraph" div element. Note that it's using the supplied		This will basically insert the downloads graph into the "mygraph" div element. Note that it's using the supplied "irstats2_googlegraph" CSS class.
	"irstats2_googlegraph" CSS class.

	~~Graph options:~~
	~~- graph_type: either "column" or "area"~~
	~~- show_average: either 1 or 0 - displays the average graph~~
	~~- date_resolution: either "year", "month" or "day" - groups data by year, month or day (be careful: selecting day may genearate LOTS of data points)~~

			Graph options:
			;graph_type: either "column" or "area"
			;show_average: either 1 or 0 - displays the average graph
			;date_resolution: either "year", "month" or "day" - groups data by year, month or day (be careful: selecting day may genearate LOTS of data points)

			<pre>
	<div id="mygraph" class="irstats2_googlegraph"/>		<div id="mygraph" class="irstats2_googlegraph"/>

Line 258:		Line 266:
	});		});
	</script>		</script>
	Tables		</pre>

			==== Tables ====
	The example below displays the top 10 downloaded eprints in the repository.		The example below displays the top 10 downloaded eprints in the repository.

	This will insert the top table into the "mytable" div element. Note that it's using the supplied		This will insert the top table into the "mytable" div element. Note that it's using the supplied "irstats2_table" CSS class.
	"irstats2_table" CSS class.

	Table options:		Table options:
	- top: the top "thing" to display - similar to the "grouping" parameter when using scripts		;top: the top "thing" to display - similar to the "grouping" parameter when using scripts
	- limit: the max number of items to retrieve		;limit: the max number of items to retrieve
	- show_count: 1 or 0 - display the counts or not		;show_count: 1 or 0 - display the counts or not
	- show_order: 1 or 0 - display the ordering (1,2,3...) or not		;show_order: 1 or 0 - display the ordering (1,2,3...) or not
	- show_more: 1 or 0 - shows the "show more" options or not (to retrieve more results)		;show_more: 1 or 0 - shows the "show more" options or not (to retrieve more results)
	- human_display: 1 or 0 - separate 1000 with a comma (as done in English): 10000 becomes 10,000		;human_display: 1 or 0 - separate 1000 with a comma (as done in English): 10000 becomes 10,000

			<pre>
	<div id="mytable" class="irstats_table"/>		<div id="mytable" class="irstats_table"/>

Line 284:		Line 294:
	});		});
	</script>		</script>
			</pre>

	Misc		==== Misc ====
	Graphs and Tables are the most common displays - but there exists a few other ones which I let you explore. The javascript classes are in 90_irstats2.js and the associated PERL Class in Stats/View/		Graphs and Tables are the most common displays - but there exists a few other ones which I let you explore. The javascript classes are in 90_irstats2.js and the associated PERL Class in Stats/View/

	GoogleSpark: similar to GoogleGraph but shows a sparkline instead (which is essentially a tiny graph).		;GoogleSpark: similar to GoogleGraph but shows a sparkline instead (which is essentially a tiny graph).
	GoogleGeoChart: country map		;GoogleGeoChart: country map
	GooglePieChart: a pie chart		;GooglePieChart: a pie chart
	Counter: a simple counter (for instance to show the download count for your repository).		;Counter: a simple counter (for instance to show the download count for your repository).

	The View prefixed by "Google" means that they are rendered by the Google Chart Javascript library. Important note: no data is sent to Google!! The data is, instead, drawn by the browser client using SVG.		The View prefixed by "Google" means that they are rendered by the Google Chart Javascript library. Important note: no data is sent to Google!! The data is, instead, drawn by the browser client using SVG.

Af05v@ecs.soton.ac.uk: /* API */

2014-12-05T15:16:31Z

API

← Older revision		Revision as of 15:16, 5 December 2014
Line 102:		Line 102:
	== API ==		== API ==

	~~API~~
	This section presents a few examples on how to get data out of IRStats2 for embedding data on pages or for re-use in analysis scripts (for instance).		This section presents a few examples on how to get data out of IRStats2 for embedding data on pages or for re-use in analysis scripts (for instance).

	There are two ways to get data out:		There are two ways to get data out:
			#From a script: this is the real API, using PERL
			#From an Ajax request: this is usually to embed data on pages

	~~From a script: this is the real API, using PERL~~		=== Core concepts ===
	~~From an Ajax request: this is usually to embed data on pages~~		==== Datatype ====
	Core concepts
	Datatype
	Which data to provide: IRStats2 also the processing of any data on your repository. The typical use of IRStats2 is however for usage statistics so this is the main dataset. But data on deposits, open access, full text (etc) are also processed. Some repositories even include data from scopus (citation counts).		Which data to provide: IRStats2 also the processing of any data on your repository. The typical use of IRStats2 is however for usage statistics so this is the main dataset. But data on deposits, open access, full text (etc) are also processed. Some repositories even include data from scopus (citation counts).

	Main datatypes:		Main datatypes:

	downloads: good old download statistics - downloads of full-text documents		;downloads: good old download statistics - downloads of full-text documents
	views: number of hits on the summary page (of a publication)		;views: number of hits on the summary page (of a publication)
	deposits: number of publications deposited		;deposits: number of publications deposited
	doc_access: provides 4 metrics (full_text, no_full_text, open_access and no_open_access) used for computing percentages of Open Access and Full-Text documents in the repository		;doc_access: provides 4 metrics (full_text, no_full_text, open_access and no_open_access) used for computing percentages of Open Access and Full-Text documents in the repository
	doc_format: MIME type of full-texts		;doc_format: MIME type of full-texts
	history: analysis of the "history" dataset - this provides information on when publications were created, edited, made live, deleted etc.		;history: analysis of the "history" dataset - this provides information on when publications were created, edited, made live, deleted etc.
	referrer: information on how site visitors got to the repository (eg. from Google, internal uni pages, etc)		;referrer: information on how site visitors got to the repository (eg. from Google, internal uni pages, etc)
	search_terms: if coming from a search site (or the internal EPrints search) which words were used to get to the publicaiton		;search_terms: if coming from a search site (or the internal EPrints search) which words were used to get to the publicaiton
	browser: which browser visitors used on the repository		;browser: which browser visitors used on the repository
	Sets
			==== Sets ====
	By default, IRStats2 returns data over the entire repository ie. the entire set of eprints is assumed. You can however restrict which "set" to use: the publications of an author, of a university division, of a subject, etc.		By default, IRStats2 returns data over the entire repository ie. the entire set of eprints is assumed. You can however restrict which "set" to use: the publications of an author, of a university division, of a subject, etc.

	Dates and ranges		==== Dates and ranges ====
	You can also restrict by dates or by a range. By default, all the stats are returned without any dates restrictions.		You can also restrict by dates or by a range. By default, all the stats are returned without any dates restrictions.

Line 134:		Line 134:
	Ranges follow a %d%c format and the upper limit is "now" or "today", for instance:		Ranges follow a %d%c format and the upper limit is "now" or "today", for instance:

	6m: over the past 6 months		;6m: over the past 6 months
	12d: over the past 12 days		;12d: over the past 12 days
	3y: over the past 3 years		;3y: over the past 3 years

	Only "m" (months), "d" (days) or "y" (years) may be used. You can see that 12m is the same as 1y.		Only "m" (months), "d" (days) or "y" (years) may be used. You can see that 12m is the same as 1y.
	Groupings
			==== Groupings ====
	This tells IRStats2 how to group data and is generally only used for things like "give me the TOP eprints", "give me the TOP authors".		This tells IRStats2 how to group data and is generally only used for things like "give me the TOP eprints", "give me the TOP authors".

	So having a "grouping" set to "eprint" means the top eprints. If set to "authors", the top authors etc. The grouping must be a valid set except for when it equals to "eprint".		So having a "grouping" set to "eprint" means the top eprints. If set to "authors", the top authors etc. The grouping must be a valid set except for when it equals to "eprint".

	Misc		==== Misc ====
	It is possible to limit the amount of records being returned (for when this is relevant: if you want the top downloads, since the beginning of time, then you'd only get one data row back, which is that count). But for queries which ask for, say, the top authors, it is then interesting to be able to get only the first 10 authors. 10 here is the limit.		It is possible to limit the amount of records being returned (for when this is relevant: if you want the top downloads, since the beginning of time, then you'd only get one data row back, which is that count). But for queries which ask for, say, the top authors, it is then interesting to be able to get only the first 10 authors. 10 here is the limit.

	It is also possible to ask IRStats2 to return certain data field in queries. For top eprints, you generally want the "eprintid" field. To draw timeline graphs (eg. evolution of downloads over-time), you'd want the "datestamp" field. More examples are illustrated below.		It is also possible to ask IRStats2 to return certain data field in queries. For top eprints, you generally want the "eprintid" field. To draw timeline graphs (eg. evolution of downloads over-time), you'd want the "datestamp" field. More examples are illustrated below.

	Data from scripts		=== Data from scripts===
	Main API		Main API