TITLE: IRIS Software Protocol
AUTHORS: Leonardo Zilli, Erica Andreose, Salvatore Di Marzo

[DESCRIPTION]
We present a step-by-step methodology for tracking the coverage of the IRIS dataset in the OpenCitations Corpus. 
The methodology filters the original IRIS dataset and the OpenCitations Meta and Index dumps, producing two novel dataset containing the data that are then queried to answer the 5 research questions.

[BEFORE_START]
Before starting, we suggest cloning the repository of the code by running the following command:
 

We also recommend, in case you would want to run the optional step of matching the id-less entities to Meta through the matching of the title, to create a .env file in the root of the folder and place your OpenCitations API key (you can obtain here) like so:
 


We suggest to make sure you have Python3.x installed on your computer. 
In order to correctly execute the provided scripts, you also must install the required libraries:
requirements.txt. You can do so by running the following command:
 



[GUIDELINES]
To allow complete reproducibility of the protocol, links to the data used are provided here.
Download link for the UNIBO IRIS bibliographic data dump, dated 14 March 2024: https://amsacta.unibo.it/id/eprint/7608/
OpenCitations Meta CSV dataset of all bibliographic metadata, dated April 2024: https://doi.org/10.6084/m9.figshare.21747461.v8

OpenCitations Index CSV dataset of all the citation data, dated November 2023:
https://doi.org/10.6084/m9.figshare.24356626.v2

The code used for this research, along with the data produced to answer to the research questions can be found in the github repository (doi:10.5281/zenodo.11262417)

[STEPS]
SECTION: IRIS Dataset Preparation
1. Make sure that the IRIS dump is present in the work directory.


SECTION: Create iris_in_meta dataset
2. This step will create a version of the OpenCitations Meta dump that is transformed and filtered according to the elements in the IRIS dump. This new dataset is stored in a parquet format that makes it lean and fast to query. 


If you want to skip the creation of the dataset, you can download the final dataset here
 

SECTION: Create iris_in_index dataset
3. This step will create a version of the OpenCitations Index dump that is transformed and filtered according to the elements in the Iris in Meta dataset. This new dataset is also stored in a parquet format.

If you want to skip the creation of the dataset, you can download the final dataset here
 

SECTION: Create iris_in_meta dataset
2.2. The purpose of this step is to read each CSV file in the Meta dump and process it by applying the following operations:
Select the ['id', 'title', 'type'] columns
Extract from the 'id' column the omid, and the doi, isbn and pmid if present through a regex pattern search. These 4 different elements are inserted into a new column created for each. 
Create a new 'id' column by combining the 'doi', 'isbn', and 'pmid' columns, preferring the first non-null value.
Get rid of the 'doi', 'isbn', and 'pmid' columns
Remove null values from the new 'id' column
Perform an inner join with the dois_isbns_pmids dataframe
 

7. Write the resulting dataframe to a .parquet file. 


You can perform this step by using the following command:
 

 

SECTION: Create iris_in_index dataset
3.1. Download the index dump and place it in the 'data/' folder in your work directory.
 

SECTION: Create iris_in_meta dataset
2.1. Download the meta dump and place it in the 'data/' folder in your work directory.
 

SECTION: IRIS Dataset Preparation
1.1. Download the iris dump and place it in a 'data/' folder in your work directory. It is not required to unzip the archive.
 

SECTION: Create iris_in_index dataset
3.2. The purpose of this step is to read all archives containing the CSV files of the Index dump and process it by applying the following operations:
Select the ['id', 'citing', 'cited'] columns
Filter the Dataframe to keep all rows that have, either in the 'cited' or 'citing' an id that is present in the omids_list Dataframe.
 

3. Write each dataframe to a .parquet file. 



You can perform this step by using the following command:
 


 

 

 

SECTION: Research Question answering
4. Each substep in this step will explain the answering process of each of the research questions mentioned in the abstract of this protocol.

You can decide to run the code for answering to a specific RQ by specifying it in the command used to run the script. It is also possible to answer all research questions at once by not specifying a specific one to the script, like so:
 

SECTION: Research Question answering
4.1. RQ1: What is the coverage of the publications available in IRIS, that strictly concern research conducted within the University of Bologna, in OpenCitations Meta?

This research question is answered by simply computing the length of the Iris in Meta dataframe.

You can run the code to answer to this research question using the following command: 
 

 

SECTION: Research Question answering
4.2. RQ2: What are the types of publications that are better covered in the portion of OpenCitations Meta covered by IRIS?

This research question is answered by grouping the Iris in Meta dataframe by the 'type' column and then counting the length of the resulting dataframe. 

You can run the code to answer to this research question using the following command: 
 

 


SECTION: Research Question answering
4.3. RQ3: What is the amount of citations (according to OpenCitations Index) the IRIS publications included in OpenCitations Meta are involved in (as citing entity and as cited entity)?

This research question is answered by simply computing the length of the Iris in Index dataframe.

You can run the code to answer to this research question using the following command: 
 

 

SECTION: Research Question answering
4.4. RQ4: How many of these citations come from and go to publications that are not included in IRIS?

This research question is answered by filtering each 'citing' and 'cited' column of the Iris in Index dataset to remove all rows in which elements from the aforementioned omids_list are present. The length of each of the two resulting dataframes are then computed to get the final answer. 

You can run the code to answer to this research question using the following command: 
 

 

SECTION: Research Question answering
4.5. RQ5: How many of these citations involve publications in IRIS as both citing and cited entities?

This research question is answered by filtering the Iris in Index dataset to keep only the rows in which elements from the aforementioned omids_list are present in either the 'citing' or in the 'cited' columns. The length of the resulting dataframe is then computed to get the final answer. 

You can run the code to answer to this research question using the following command: 
 

 

SECTION: Create iris_in_meta dataset
2.3. It is also possible to attempt to retrieve and enrich the Iris in Meta dataset with the identifiers of the elements in the IRIS dump that do not have any DOI, ISBN, or PMID. This is done by querying the OpenCitations Meta SPARQL endpoint to search for each entitity by their title.
From our tests this optional step was able to retrieve 150 additional entities. 

This is an optional step.  This step has not been performed in the presented state of our research as its result can vary and it could lead to reproducibility incongruences. 
We decided to report this only for completeness' sake.