This page describes how to prepare the files that constitute a transparency appendix (TRAX). This document provides general guidance on the content of the TRAX. For a detailed discussion of a TRAX and its theoretical foundations, see QDR’s Guide to Active Citation.
As QDR is working towards an easy-to-use, automated workflow to create and submit the annotations that make up the TRAX, we accept annotations in a range of provisional formats and will convert them to a standardized format after deposit. Possible deposit formats (with links to instructions) include Word comments, PDF comments, Word links with bookmarks, and PDF links with bookmarks (using LaTeX and similar markup languages). If you would like to submit your annotations in a different format, please contact QDR.
Overview
Some of the ways in which you might want to describe your research process for transparency may not readily attach themselves to a particular segment of the publication. You can use an introductory Overview section to describe these aspects of your research. The Overview is analogous to a methodological appendix in the quantitative or formal traditions of political science.
Typically, the Overview consists of two parts: (1) a narrative description of the processes you used to collect the sources and generate the data employed in the article; and (2) a general description of how the research attends to the inferential rules and structures that underlie the type of analysis you carried out.
The first part clarifies your data collection activities by addressing questions you think are relevant about the overall body of potential evidence and what justifies the decisions to select or sample particular evidence to examine, to analyze in detail, and to cite. What relevant data were not or could not be consulted and what is their potential effect on the analysis? What instruments and procedures were employed to collect data?
The second part clarifies how your data analysis corresponds to your methodology. It describes your logic of annotation. How do you draw inferences from the data you present and how does that correspond to your underlying epistemology? How did you select which are important or controversial claims that required annotation? Where have you added analytic notes, and what is their main function (e.g., do they elucidate links between evidence and claim or do they provide additional context).
Some overviews of data projects on QDR that can serve as examples are
- The Overview for Samuel Handlin’s The Politics of Polarization and
- The Overview for Hillel Soifer’s “Elite Preferences, Administrative Institutions, and Educational Development.”
However, note that these are examples, not templates. The content and internal structure of your overview should be determined by your data project.
The overview is titled: <author> _<date>_TRAX_Overview.pdf.
Annotations for Transparent Inference
The bulk of the TRAX consists of annotations. The remainder of these instructions describes steps to produce an annotated Word or PDF version of your publication for deposit. QDR will extract the comments from that document to create a version of your TRAX that can be shared with others via the repository.
Annotation Contents
For each footnote, endnote, in-text citation, or other text passage you want to annotate, create an annotation. Annotations can and should differ widely. Below are some examples highlighting various functions. They are by no means exhaustive: you should use annotations in a way that best serves to make your research more transparent. Click on the thumbnails to open a full-size image of the note in a new tab.
Each annotation consists of a combination of one or more of the following elements:
- Source excerpt: typically 100 to 150 words from a textual source; for handwritten material, audiovisual material, or material generated through interviews or focus groups, an excerpt from the transcription (required for AJPS replication).
- Source excerpt translation: if the excerpt is not in English, a translation of the key passage and the source of the translation. QDR encourages you to provide translations of important source excerpts (required for AJPS replication).
- Analytic Note: discussion that illustrates how the data generated from the source(s) support empirical claims in the text or that otherwise contextualizes evidence.
- Filename for source file: the name of the corresponding source file that you will deposit. QDR strongly encourages you to supply source files for all primary and hard-to-obtain sources. Make sure to read and follow the file naming conventions below.
You will submit this annotated Word document or PDF. This copy will not typically be available to repository users, but rather will be used by QDR staff to extract the TRAX, which consists only of the annotations and their location in the text (see here if you are interested in the details of this process). Please name the file: <author> _<date>_<publicationtitle>.pdf (or .docx when using Word). If the full bibliographic information is not included in footnotes, a bibliography must follow the text.
Submitting the TRAX
Submit TRAX Overview (as a documentation file) and the annotated article or book chapter (as a data file), together with any accompanying source files (also as data), to QDR via the Data Deposit Form.
For submitting AJPS replication files, please follow our instructions for TRAX conversion, then submit the extracted annotations to the AJPS Dataverse following the instructions provided by the AJPS. Please contact QDR should you require assistance in the conversion process.
Source File Naming Conventions
Please use the following file naming convention. Please also make sure that the actual filename corresponds to the filename you have listed in the annotation.
<author’s last name>_<one-word description>_<date of original publication/creation>_<page range>
Where
<author’s last name>refers to your last name. For two authors use firstauthor_secondauthor, for three or more firstauthor_etal<one-word description>should be a one word description of the source, such as its original author and/or its type ( e.g., Jonesinterview). You should number or otherwise distinguish multiple sources of the same type (e.g. interview1 or interviewA)<date of original publication/creation>refers to the publication date of a source or the time the data was collected (e.g., in the case of an interview)<page range>is optional and need only be used if you plan to use several excerpts from the same source. It refers to the page or page range from the source. Separate page ranges with an underscore. Prepare separate files containing relevant passages/pages for each excerpt.
File name examples:
Brown_Interview1_1995
Brown_FieldNote3_2005
Brown_NewspaperWSJ5_2000
Brown_Huntington_1993_pp23_25
Brown_Huntington_1993_pp43_47
Please avoid the following in filenames to ensure compatibility across systems and with machine readability: spaces, special characters other than underscore (e.g., & : * . - ), file name distinctions relying on capitalization (Windows systems do not distinguish capitalization in filenames).