Reporting

To allow users some flexibility in report creation a unique system for specifying how to build reports was created. This system is described here. The key framework to keep in mind is that there are 3 different reports and 2 ways to build each one. The specifications also slightly differ between each other and between author_search and reference_search. The 3 reports are summary_report, project_report, and collaborator_report. Each report can be specified using a formatted text string or using a dictionary to specify rows and columns.

To specify a report using a formatted string include the “template” attribute for the report. To specify a report using rows and columns include the “columns” attribute for the report. “columns” should be a dictionary where the keys are column names and values are what should be in each row of the column. Typically, the values will be keywords.

If specifying the report with the “columns” attribute there are other attributes that can be used in conjuction. “file_format” allows you to specify whether the report should be a CSV or Excel file. The 2 allowed values are “csv” and “xlsx”. “sort” allows you to specify how to sort the table. It should be a list of column names. Similarly, “column_order” allows you to specify the order of the columns of the table. The order of the columns should be the same as the order given in “columns”, but just in case “column_order” is provided to manually set the order. “separator” allows you to specify the separator character for CSV files. It must be one character in length and defaults to a comma.

“filename” allows you to specify the filename of the report regardless of whether “columns” or “template” are used to specify the report, but if the “file_format” is “xlsx” and the filename extension is not xlsx then “.xlsx” will be added to the filename.

To email a report as an attachment simply include the email related attributes in the report section. If the email attributes are missing then no email is sent.

Example Config JSON Excerpt

"summary_report" : {"template":"This is a header\n<project_loop><project_name>:\n<author_loop><author_first>:\n<pub_loop><title></pub_loop></author_loop></project_loop>",

                    "columns":{"Project":"<project_name>", "Author":"<author_first>; <author_last>", "Publication":"<title>"},
                    "column_order":["Project", "Author", "Publication"],
                    "sort":["Project", "Author"],
                    "file_format":"csv",
                    "separator":"\t",

                    "filename":"summary_report.txt",

                    "email_body":"Please see attached summary_report.",
                    "email_subject":"Summary of Publications",
                    "to_email":["person1@email.edu"],
                    "from_email":"your_email@email.edu",
                    "cc_email":["person2@email.edu"]}

Note that "template" takes precedent over "columns" so if both are specified "template" is used. This example is just trying to give a full example.

Summary Report

Using the summary_report section of the configuration JSON a custom summary report can be created. Academic Tracker will read the template or columns attribute of this section and certain keywords (described below) will be replaced with information collected during the run. The keywords and inherent nature of how the report is built differs between author_search and reference_search.

If the summary_report section is missing then no summary report will be made. If the template and columns attributes are not in the summary_report section then a default template will be used (described below).

Summary reports are saved in the tracker directory under summary_report.txt by default.

Default Template Strings

Author Search

Summary

<project_loop><project_name>\n<author_loop>\t<author_first> <author_last>:<pub_loop>\n\t\tTitle: <title> \n\t\tAuthors: <authors> \n\t\tJournal: <journal> \n\t\tDOI: <DOI> \n\t\tPMID: <PMID> \n\t\tPMCID: <PMCID> \n\t\tGrants: <grants>\n</pub_loop>\n</author_loop></project_loop>

Project

<author_loop><author_first> <author_last>:<pub_loop>\n\tTitle: <title> \n\tAuthors: <authors> \n\tJournal: <journal> \n\tDOI: <DOI> \n\tPMID: <PMID> \n\tPMCID: <PMCID> \n\tGrants: <grants>\n</pub_loop>\n</author_loop>

Author

<author_loop><author_first> <author_last>:<pub_loop>\n\tTitle: <title> \n\tAuthors: <authors> \n\tJournal: <journal> \n\tDOI: <DOI> \n\tPMID: <PMID> \n\tPMCID: <PMCID> \n\tGrants: <grants>\n</pub_loop>\n</author_loop>

Reference Search

<pub_loop>Reference Line:\n\t<ref_line>\nTokenized Reference:\n\tAuthors: <tok_authors>\n\tTitle: <tok_title>\n\tPMID: <tok_PMID>\n\tDOI: <tok_DOI>\nQueried Information:\n\tDOI: <DOI>\n\tPMID: <PMID>\n\tPMCID: <PMCID>\n\tGrants: <grants>\n\n</pub_loop>

Collaborator Report

Creating a collaborator report for an author is actually a unique use case from a typical author_search run, but since all of the steps are the same it is included as a report in author_search rather than being its own command. The idea is to be able to go through an author’s publications and build a report that contains all of the other authors they have worked with. This type of report is required by some funding providers.

Collaborator reports are only created for author_search. There is no conception of them in reference_search. To create a collaborator report for an author include the collaborator_report attribute for the author in the config JSON. Although a collaborator report is done on a per author basis it can be included in a project of the config JSON as a convenience. If it is included in a project then a collaborator report will be created for each author associated with the project.

The report is built by looping over each publication for the author and each author on the publication. Unlike the project report though only the pub_author_loop is available for the collaborator report. Tags denote the beginning and end of the loop.

The collaborator report is a little unique compared to the sumary and project reports because it defaults to a tabular file using the “columns” attribute rather than using the “template” attribute.

If the collaborator_report attribute is missing then no collaborator report will be made. If the template and columns attributes are not in the collaborator_report section then a default columns and sort will be used (described below). If from_email is absent then no emails will be sent. If from_email is provided and to_email is provided then the report is sent to the to_email address, otherwise it is sent to the author’s email.

Collaborator reports are saved in the tracker directory under author_id_collaborators.csv by default.

Keywords

<pub_author_first>         -  Collaborator's first name.
<pub_author_last>          -  Collaborator's last name.
<pub_author_initials>      -  Collaborator's initials.
<pub_author_affiliations>  -  Collaborator's affiliations.
<pub_author_ORCID>         -  Collaborator's ORCID.
<pub_author_id>            -  Collaborator's ID.

Examples

Collaborator Report Attributes:
columns = ["Name", "Affiliations"]
values = ["<last_name>, <first_name>", "<affiliations>"]
sort = ["Name"]

Output CSV:
Name                   Affiliations
Brewer, Dawn           University of Kentucky Department of Dietetics and Human Nutrition.
Christian, W Jay   University of Kentucky College of Public Health.
Evans, Steven          Kentucky Water Resources Research Institute.

Default Values

columns : {"Name":"<last_name>, <first_name>", "Affiliations":"<affiliations>"}
column_order : ["Name", "Affiliations"]
sort : ["Name"]
separator : ","