Working with plugins

Citehound plugins provide a simple way to produce analytical results in different form, from the data held in Citehound.

Plugins are packaged and distributed as Python modules and can have their own dependencies that are entirely separate from the main Citehound project itself.

Once installed, plugins can be reviewed, return information about their functionality and parameters and finally be launched.

This section of the documentation will cover the usage of plugins.

A different section will be devoted on the details of developing plugins for Citehound.

Introduction

Plugins are Python programs that work together with Citehound and produce more complex outputs than a CSV file typically produced by queries.

Citehound plugins are modules, in Python packages with the prefix citehound_plugin_ in their name. For example, suppose a visualisation plugin that uses graphviz.org to visualise an emerging citation network, based on your Citehound database. A possible name for this plugin could be author_network_graphviz. In this case, the package name would be citehound_plugin_author_network_graphviz but the plugin name would be author_network_plugin.

Note

It is important to get this distinction right.

To search for a plugin over pypi / git, you would use its complete package name, here citehound_plugin_author_network_graphviz.

Once the package is installed, the plugin is then addressed within Citehound with its plugin name only.

See for example, the section on listing the installed plugins further below.

All details that apply for the installation of Python packages, apply to installing Citehound plugins as well. They can be installed via pip, sourced from a git repository or pypi.org and can be uninstalled at will.

When a Citehound plugin launches, all operations within the plugin are “wrapped around” a transaction. Therefore, if the plugin crashes for any reason, data integrity is preserved. Only after the plugin has finished succesfully the set of operations described within the transaction is committed to the database. This of course applies to WRITE type of transactions that modify the database, raher than READ operations.

The entire plugin functionality is available through he Citehound adminstration script (cadmin.py) under the command:

> cadmin.py query ...

The rest of this section outlines each subcommand of query and its parameters with illustrative examples.

Listing installed plugins

To check if a plugin is installed, you can get a listing of the installed plugins with:

> cadmin.py plugin ls

This will return a list of installed plugins under the heading Installed plugins.

Note

Plugins are listed here by their plugin name.

Inspecting installed plugins

Citehound plugins aspire to be self-documenting.

Plugins contain enough information to understand:

1. Their overall functionality

2. What their parameters are and what do they represent

3. What are valid values for those parameters.

Continuing from the above example, cadmin.py query ls returns a list of plugins and we would like to get more information about one of them, the one called basic.

All this information can be accessed via:

> cadmin.py plugin info basic

This returns something like:

Name: BasicPlugin


Short Description:
A simple plugin template for Citehound plugins.

Long Description:
This plugin contains the absolute minimal code for a user to start
developing and testing plugins.

Param.Name, Default value, Prompt, Description
alpha, 0, Alpha coefficient:, The alpha coeff of the model
mess, QUERY_COLLECTION, Query collection:, The collection to work on
option_enabled, no, Enable this option?, Whether to enable the option or not

Launching plugins

Having reviewed the installed plugins and reviewed the metadata of one (basic), we can now proceed to launch the plugin.

This is done with:

> cadmin.py plugin launch basic

Most commonly, plugins will have mandatory parameters that have to be set before the plugin can proceed with its execution and optional parameters.

If no mandatory parameters are specified on the command line, Citehound will present a series of prompts to ensure that each mandatory plugin parameter is set to a valid value.

To set parameters at the command line, you can use:

> cadmin.py plugin launch basic -p alpha=2

In fact, all parameters of a plugin can be set at the command line, in which case, Citehound will not present any interactive prompt to gather any unspecified plugin parameter.

This makes it easy to write scripts that call plugins sequentially to combine their outputs.