Installation
Buhos software can be used locally or online. In the case of local use, the application deploys a web server that can only be accessed by a computer that the software is installed in. In distributed form, the application integrates with a web server such as Apache or Nginx, using Passenger.
Vagrant configurations are available for using Buhos in virtual server mode.
Windows
There is a Windows installer for local use of the application. The latest version is available in:
https://github.com/clbustos/buhos-windows-tk/tree/master/windows_installer
Debian / Ubuntu /CentOS
For Debian, Ubuntu and CentOS, packages and installation instructions are available on https://packager.io/gh/clbustos/buhos. For example, to install on Ubuntu 16.04 and configure the application as a service on port 4567,
wget -qO- https://dl.packager.io/srv/clbustos/buhos/key | sudo apt-key add -
sudo wget -O /etc/apt/sources.list.d/buhos.list \
https://dl.packager.io/srv/clbustos/buhos/master/installer/ubuntu/16.04.repo
sudo apt-get update
sudo apt-get install buhos
sudo buhos config:set PORT=4567
sudo buhos scale web=1
sudo buhos restart
Vagrant should be run
In the directories vendor/vagrant_alpine and vendor/vagrant_ubuntu_16 configurations of Vagrant can be found for Alpine and Ubuntu 16.04, respectively. They can be run using:
vagrant up
By default, the application is configured to run on port 4567.
From Source Code
As a prerequisite for installing the software, Ruby 2.4 or higher should be installed, with development libraries for MySQL and SQlite. In addition, the bundler gem must be installed to download the gems needed for the software to work.
In Ubuntu 16, the following instructions install all the required dependencies:
apt-get update
apt-get upgrade -y
apt-get install -y \
cloc \
gdal-bin \
gdebi-core \
git \
libcurl4-openssl-dev \
libgdal-dev \
libproj-dev \
libxml2-dev \
libxml2-dev \
build-essential \
libmysqlclient-dev \
libsqlite3-dev
gpg --keyserver hkp://keys.gnupg.net \
--recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -sSL https://get.rvm.io | bash -s $1
In Alpine, the instructions required to install the dependencies are:
apk update
apk upgrade
apk --update add --virtual \
build-dependencies \
ruby-dev \
build-base \
ruby \
libffi-dev \
libxml2-dev \
libxslt-dev \
mariadb-dev \
sqlite-dev \
ruby-json \
ruby-bigdecimal \
ruby-etc
Once the dependencies have been obtained, the source code must be copied from github, using:
git clone git@github.com:clbustos/buhos.git
cd buhos
The gems needed are obtained using the gem bundler.
bundler install
If you wish to use MySQL, the data base must be created beforehand. As a root user, a script similar to the following can be used:
CREATE DATABASES buhos;
CREATE USER buhos_user@localhost IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON buhos.* TO buhos_user@localhost;
FLUSH PRIVILEGES;
To run the application locally, you can deploy a web server (thin in *nix o puma in Windows), using:
ruby app.rb
The program can be accessed using any browser in the URI: http://localhost:4567
If you wish to deploy the software online, you can provide the application via Nginx or Apache, with Passenger. Instructions for integrating a Passenger application into a Linux web server are found in:
https://www.phusionpassenger.com/library/walkthroughs/deploy/ruby/ownserver/integration_mode.html
As a reference, the Buhos configuration in Nginx for a typical web server is:
server {
listen 80
root /home/<user>/<base_dir>;
passenger_enabled on;
passenger_ruby <ruby_location>
}
In this case, the application could be accessed using:
http://localhost/
Post-Install Configuration
The first time the application is run, it must be configured. There are 4 steps:
- Language selection.
- Configuration of basic features (database to be used, institutional proxy connection and Scopus use).
- Verify the connection to the database.
- Restart the application.
As a first step of the configuration the installation language must be selected.
Secondly, basic information for the operation of the system must be provided. This means selecting the use of a SQLite database for local use, or a MySQL database for distributed use. If you’re not sure what choice to make, use SQLite. If you have a Scopus development key, you can enter it; the proxy settings will be used if you must use one for your university or work.
Once the application is configured, it tries to connect to the database. If the process is successful, a confirmation message appears and a button to start populating the database is displayed. This process lasts from 30 to 60 seconds, depending on the computer.
If the process result is successful, the following screen is displayed:
At the end of the process, restart the application. By default, a user with administrator permissions will receive 'admin' as their user name and password.
To close the application in Linux, Ctrl+C can be used in the console. In Windows, close the window displaying the system logs.
Quick User Guide
For a local installation, enter the respective URL (http://localhost:4567) to enter the application. For an installation that has just been carried out, remember that the user name and password are both 'admin'.
The dashboard is the main working interface, accessed by clicking on the application name or the 'My Dashboard' link.
The software functionality is demonstrated by the systematic review of a group (cluster) of articles on software for the performance of systematic reviews.
Preparation of the Systematic Review
The systematic review is created by pressing the "New Systematic Review" button. A form is then displayed in which the main features of the research must be entered, including the period of years within which the search should be performed, and the categories that the study falls under according to Cooper's taxonomy.
Once the systematic review has been created, a technical sheet is displayed. A wide variety of possible actions will emerge for deploying the systematic review.
As shown here, three objectives were defined, thus a customized form can be created for the systematic review. To do this, click on the 'Analysis Fields' button.
Each form is made up of one or more fields. First, indicate where the field should be located inside the form. Second, the text to be contained in the form will be included in the description. Third, indicate the code that the field will have in the database. Said code may only consist of lowercase letters, numbers and underscores. Finally, indicate the field type (short text, long text, multiple choice). When you have finished, click ‘Create New Field'.
In the sample case, three fields are required: tools, stage and function. When the form definition is complete, generate the form by pressing the button 'Update Customized Field Record Table'.
Search Stage
By default, the system will initiate the search stage of the systematic review. At this stage, the searches done by the different evaluators must be recorded, whether carried out in bibliographic databases or informally, on different search engines.
To simplify the process of recording searches, the user dashboard can be accessed by clicking on the application name, which will call up the following interface.
The principal medium for incorporating search information is the entry of BibTeX files, available in virtually all bibliographic reference systems. Some examples: EndNote, Refwords and Mendeley.
For demonstration purposes, in the software's installation directory there is a manual. bib file with six texts, selected from the developer's customized Mendeley repository. To enter this search, click on the appropriate dashboard button.
Before filling out the form, the source type must first be specified. The following search modalities are offered: search in a indexed databases, informal search, backward snowballing (search in references contained in selected texts), and forward snowballing (search for articles that cite already-selected texts). The example given is that of an informal search. Secondly, entry of the database is requested from which the search was obtained. In the case shown, upon being obtained directly from Mendeley, the' general' option applies. Thirdly, the search criterion is left blank, as the indexed database is no longer used, and the description is completed. Finally, enter the manual. bib file in the last space on the form.
When the searches have been incorporated, they must be processed and later validated. To process them, click on the respective check box and click ‘Process searches’.
As the system processes the search, it captures as much information as possible from the records stored in the BibTeX file. It can be verified that the system has detected six records.
Upon entering 'Records', the system is seen to have entered information on the authors, year of publication, title, as well as the documents' DOI. In the example BibTeX contains the abstract of each article, and can be checked by pressing the corresponding button. Each search record is assigned a ‘canonical document’ that corresponds to the unique reference in the system to that document. Consequently, if various records of the same text with the same DOI come up in different searches, the system will assign all such records to one same canonical document.
Since the references are the ones expected, the search that was performed can then be validated. To validate, return to the search screen, click on the appropriate check box, and click the 'Valid' button. The result should be as follows
Once each and every search has been defined as valid or invalid, then we can proceed to the next stage: screening of titles and abstracts. To do this, enter the dashboard, pressing on the application title. To manage the validations, click on the line ‘Total number of review searches: 1’
In the search management screen, all searches performed by the various users are displayed, and the option offered of validating or invalidating them. Since an option already exists for all the searches, the option to advance to the next stage is offered.
Title and Abstract Screening Stage
Once the records have been defined, they should be reviewed to confirm whether they are useful or not. To determine this, the first criterion is to see whether the article title and abstract evidence eligibility for inclusion of the document into the study.
In the next stage, the system displays the administration interface.
By default, Buhos considers two users: an administrator with all the permissions to administer the system, and an analyst with an 'analyst' username and password, who is authorized to check the systematic reviews assigned to him/her. In the example, all documents were assigned to both users to show the resolution of divergences. To view, click on the 'CD Allocations' button.
All the documents can be assigned to a user, using the 'Assign All' buttons or assigning each document individually. In this case, the two 'Assign All' buttons were pressed.
The result should be similar to the following:
Upon entering the user dashboard, it will be seen that, as an administrator, we have six documents to resolve. As an evaluator, it is shown that six documents must be decided on. Next, click on the final link to begin the evaluation process.
The upper portion of the evaluation interface provides general information on the stage in question, the review objectives, and how far advanced it is. In this case there are six documents that have not been decided upon.
Each document pending assessment is submitted forthwith. The title and abstract of each document is shown, its reference in APA format, and how many citations it has. It is on the basis of this information that it must be decided whether the document provides enough information. It is observed that the sample abstract does not provide information on systematic review software, but rather refers to a study on how reviews are conducted. Therefore the decision should be marked ‘No’ and its status as research on reviews can be added on as a tag.
When the above-referenced decision is made, the color of the frame is seen to change and the selected tag is added.
The abstract of the following text on GAPScreener presents some of the key words that were established when the systematic review was defined. Judging from the document title and abstract the document is clearly relevant to the research. In fact, a tag can even be added indicating that the software refered on document is useful for the screening stage.
During the review of all the documents, the user dashboard display indicates when there are no unchecked documents left.
The same review process will now be performed, but this time by the user analyst. To proceed, log out by clicking on the 'Logout' link at the top of the site,
then log into the system as an analyst. By default, both the username and the password are 'analyst'.
The analyst’s user's dashboard indicates that he/she has no access to administration tools, but he/she does indicate that he/she has documents awaiting decisions.
In this example, the analyst points out that all the documents are important for the investigation.
Once all the users have decided on the texts, the administrator must decide whether it is necessary for him/her to resolve whether each document should or should not proceed to the following stage. We log into the system as administrator (user: admin, password: admin) and go to the link 'Unresolved Review 6 canonical documents'.
The' Decision statistics' box shows five documents with the decision pattern of two affirmatives ('Yes'), one document that one user decides that it is relevant, and another that it is not.
Since there is unanimity on five documents, click on the ‘Accept' button in the corresponding row. The resolutions for the texts will have changed from 'No resolution' to 'Yes'.
To see which texts the discrepancy occurred in, click on the 'View' button. That text will be precisely the one that an administrator pointed out was invalid.
In this instance various alternatives exist, depending on the systematic review protocol: the technical sheet can be used to report the discrepancy to the researchers, a third researcher can be incorporated to resolve the issue or to exercise the administrator's function and issue a resolution. In the example, the last option was taken by clicking on the 'Yes' button, leaving the decision for the subsequent stage of full-text review.
When the page is uploaded again, it is stated that the status of all the canonical documents has been resolved, thus allowing you to proceed to the next stage. Prior to this, references must be generated using Crossref. The process can take several minutes. If you want to verify the references that have been made, you can check them in the search interface.
Once the system resolves the Crossref references, you can advance to the next stage. In this next stage, you check whether there are any references to more than a certain number of documents selected in the title and abstract review stage. The number of references is listed in the reference data sheet as 'Minimum number of RTR documents for reference review'; by default, it is set at two. In our example, there is no reference that meets this condition, therefore proceed to the full-text review stage.
Full-Text Review
In full-text review, aside from the interfaces for assigning users to documents and issuing resolutions on them, files can be assigned to each canonical document. Four of these documents are open-access, so they are in the tutorial's resource directory and can be massively incorporated with the 'Batch File Management' button.
To enter the files, click on the 'Browse' button and select the four PDF files contained in the folder.
The four documents have been uploaded, but are not assigned to any canonical documents. If you click on 'Automatically Assign to Canonical Documents', the system will try to assign them using metadata from the PDFs.
The automatic assignment is quite satisfactory, as it correctly assigns three of the four documents. To assign the missing document for the ExaCT file, simply click on the selection box 'No Canonical Document', and select the appropriate canonical document.
Two of the selected articles are not free access. For purposes of our example, they will be excluded from review as they are considered texts without access, although in a real review the authors should be contacted directly to obtain a copy. To do this, as was done in the text and title review stage, go to the decisions per document section and click on the 'No' button to resolve not to include them.
The remaining four texts will be assigned manually to the administrator only. To do this, go to the 'CD Assignments' button, and click on the buttons for the specific texts to make the corresponding assignments.
The user dashboard will indicate that just four documents lack resolution and four still to be analyzed.
The interface of this stage shows whether or not there were specific instructions at the time of document assignment for each user, as well as whether any decisions have been made regarding the document.
To decide if the document is pertinent after reading it completely, as well as to extract information from it, click on the 'Extract information' button.
The decision and information extraction interface displays a box with the PDF file. It is the same decision box as the one for the title and screening review stage, with the questions added that were defined in the custom analysis fields at the time of the systematic review's preparation.
Upon completion of the process, from the dashboard we proceed to the management of the review and accept all the studies, then advance to the final stage.
Reporting
The systematic review report includes 3 online reports and 2 export types, to BibTeX and GraphML. The latter format, which stores the directed network of citations by the canonical documents, can be viewed in programs such as yEd or Gephi.
First, we have a PRISMA flowchart that can be edited in a vector drawing program such as Inkscape.
The data extraction report gives us the list of live codes displayed on each form, with the number of times it appears and the text where it is located.
A complete breakdown of the data extracted on each document is also provided.
The process report shows all decisions and resolutions of the administrator and the evaluators.
