Wednesday, March 25, 2015

ASU Dissertation Template Now on ShareLaTeX

I have already posted about the LaTeX template that I developed for Arizona State University (ASU) theses and dissertations. I was and am highly motivated to help ASU grad students get through format review quickly and painlessly. In my view, the template is a great step in that direction.

In the README for the GitHub repo for the dissertation template, I invite users to contact me if they need help using the template. Most of the messages that I have gotten are actually requests for help setting up TeX rather than resolving problems with the template. It seems that people that struggle to use the template are stumbling on the first step: getting a TeX distribution up and running on their computers.

Troubleshooting these problems is incredibly difficult from a distance. There are so many things that could be going wrong on the user end. The problem could be with the TeX distribution or my dissertation template; it could be the particular TeX editor that the person is using; or it could be something else entirely. I have to admit I’m not sure how to troubleshoot these problems unless I’m sitting at the user’s computer and able to try it out for myself, but in-person support is not a practical solution.

So I have turned my dissertation template into a ShareLaTeX template. ShareLaTeX is an online LaTeX editor. Anyone can write or upload LaTeX code, and ShareLaTeX will convert it into a PDF—no need for installing TeX on your own computer. I’ve tried it out over the past couple days, and it seems like quite a fast, stable site with some cool features. Creating an account is painless; it just takes an email account and password. I don’t think you even need to confirm your email address.

Once you have an account, you can start a new project based on the ASU dissertation template. Go to the page for the ASU dissertation template, and click “Open in ShareLaTeX”. ShareLaTeX will automatically create a new project for you based on the template.

I have tested the template on ShareLaTeX, and it runs great. So ASU grad students rejoice! You now have an even more user-friendly way to format your dissertations and theses.

ShareLaTeX also provides some tutorial information for people new to LaTeX:

The second point, the documentation page, contains a wealth of information about LaTeX basics, such as making text bold and inserting tables, and more advanced topics, such as integrating R code into your LaTeX documents. (By the way, I’m sort of blown away that ShareLaTeX supports R. This is an incredibly handy feature.)

To recap, the basic steps for using the ASU dissertation template on ShareLaTeX follow:

  1. Create a ShareLaTeX account.

  2. Start a new project based on the ASU dissertation template:
    1. Visit the template page.
    2. Click the “Open in ShareLaTeX” button.
  3. Update the template with your own dissertation information (e.g., author name) and content. (The README file and the template file itself walks you through where and how to update the template.)

  4. Click the “Compile” or “Recompile” button to make your document.

Using ShareLaTeX should make dissertation and thesis formatting easier than it was before. For people who want an entirely painless formatting experience, I offer a typesetting service through my consulting company. I’ll take your LaTeX files and update them so that your thesis or dissertation passes format review. I have found that many people end up coming to me after going through a couple rounds of revisions with the format reviewers at the grad office as graduation deadlines are fast approaching. Please don’t wait to get in touch if you’re stuck on formatting. I’ll help however I can, whether answering questions by email (for free) or doing the typesetting myself (for a fee).

Monday, March 16, 2015

Literature Review: Citing Sources That Cite Sources

General Advice

The overriding idea behind providing citations is proper attribution. Work (i.e., analysis, ideas, interpretations, and so forth) that is not your own should be attributed to the people that actually did the work. The general advice to undergraduates and graduate students often boils down to the following:

  1. Information that comes from sources needs to be correctly attributed to those sources.
  2. Word-for-word reproductions from sources need to be correctly attributed and accompanied by a location identifier—usually a page number.

In the first situation, you are paraphrasing a source, and in the second situation you are providing a direct quotation.

That advice covers most of the territory that students and other authors are likely to encounter. But concrete advice on the finer points of citing sources can be scarce. For example, what if you are citing a source that cites another source?

Citing Sources That Cite Sources

Direct Quotations

If you are reproducing a direct quotation, you should find the original source with the quotation and cite from it. If the original source is unavailable, you can still provide the direct quotation and indicate that the quote is from a secondary source. The correct format for citing from a secondary source varies according to style guide. In Chicago style, for example, authors should “mention the original author and date in the text, and cite the secondary source in the reference list entry. The text citation would include the words ‘quoted in’” (University of Chicago 2010, §15.52).

Paraphrasing

A common situation that involves paraphrasing sources that cite other sources is paraphrasing academic journal articles, which themselves contain many citations. Literature reviews in these articles can be great sources of information about a given topic. But when you paraphrase from the literature review of such an article, should you cite the article or the sources cited in the article? It depends on what the article says and why you’re citing it.

Consider the following scenario: Paper 1 cites papers A, B, and C. You have read paper 1, but you have not yet read papers A, B, or C.

If you are paraphrasing paper 1’s analysis of papers A, B, and C, then cite paper 1. For example, paper 1 might say, “Researchers in the field have struggled to develop a valid and reliable instrument for this variable of interest (Paper A, Paper B, Paper C).” Your paraphrase of paper 1’s analysis of the state of the field should be made directly to paper 1. You’re not reproducing paper 1’s analysis of the field, and you didn’t come up with that analysis of the field on your own (presumably). So paper 1 should get the credit for that analysis. You might even cite paper 1’s analysis and then argue that it’s incorrect.

However, if you are discussing the contents of papers A, B, or C, it is your responsibility to read those papers and cite them directly. For example, paper 1 might say, “Participant recall improves when [some condition] is true (Paper A, Paper B, Paper C).” Assuming all three papers (A, B, and C) directly address this point (that [some condition] improves participant recall) and paper 1 is simply gathering and citing the sources that have shown this to be the case (i.e., no additional analysis is done in paper 1), then you should read and cite papers A, B, and C.

Remember that by citing a source, you are indicating to the reader that you have obtained and reviewed the source. There are at least two reasons for taking this approach: (1) honesty and (2) accuracy. First, an in-text citation indicates that you are paraphrasing from that source, and it does not make sense to paraphrase from a source you have not read. You should not grab citations out of a source, like an academic journal article, and use them in your own work unless you have reviewed the cited works yourself. Second, sometimes authors misinterpret or even misrepresent the sources that they cite. I have often found that I disagree with the way that authors characterize sources that they cite after I have found and reviewed the original sources. And unless authors are rigorous about reviewing the sources that they cite, misinformation about original sources can easily propagate.

References

University of Chicago. 2010. The Chicago Manual of Style. 16th ed. Chicago; London: University of Chicago.

Wednesday, March 11, 2015

Zotero + Word Tutorial

I mentioned Zotero in my first academic workflow post. Zotero is a great citation manager with many great features. And if you write your documents in Word, Zotero is a no brainer. A Zotero plug-in for Word lets you insert citations from your Zotero database in your Word documents, and then Zotero automatically formats in-text citations and the reference list at the end of the document. Plus, it’s free!

Most students, whether graduate students or undergrads, use Word to write their school essays, term papers, and manuscripts, so Zotero is a great, free option for easily handling citations in these documents.

In this post, I provide a tutorial for getting citations into Zotero and getting citations from Zotero into your Word documents. At the end of the post, I provide links to some additional tutorials (including screencasts) on installing and using Zotero.

Installation

Basic Installation

You can download and install Zotero from this page. There are two ways to install Zotero:

  • Standalone
  • Zotero for Firefox

The stand-alone option installs Zotero like any other application that runs on your computer. Note that if you install the stand-alone version, you should also install the plug-in for whichever browser you use when you do academic research (Firefox, Chrome, or Safari). Using a browser with Zotero makes it much easier to get citations into your reference database. Install the browser add-on after installing the stand-alone version.

If you install Zotero for Firefox, you will need to have Firefox open to use Zotero (including putting references into Zotero and citing references from Zotero).

Zotero Plug-in for Word

You definitely want to install the plug-in for Word so that you can create citations automatically in Word documents. If you install the stand-alone version of Zotero, the Word plug-in is included. If you install Zotero for Firefox, you need to manually add the Word plug-in (available here).

Getting Sources into Your Reference Library

There are four main ways to get citation information into your Zotero database. I give step-by-step instructions here plus a few exercises, so you can try them out.

Web Page with Embedded Metadata

The browser that is integrated with Zotero (e.g., Firefox) can quickly and easily import sources into the Zotero library. Many web pages embed metadata into the web page itself (e.g., the web pages for academic journal articles hosted on ScienceDirect). Zotero can recognize this information and import it.

Other useful websites with embedded metadata include Amazon, Google Books, and most newspapers. So, for example, when I have a hard copy of a book, I often look it up on Amazon and grab the citation information from there, so I don’t have to type it in manually.

Exercise

Open the web browser that is integrated with Zotero, and go to this random academic journal article hosted on ScienceDirect: http://www.sciencedirect.com/science/article/pii/S1053811902913303. (Note that it does not matter if you have access to the full text of the article.) Look at the right-hand portion of the address bar of your web browser. There should be a small icon that looks like a single piece of paper. If you click on that icon, Zotero will automatically import the citation into your reference library. It’s hard to imagine how it could be any easier.

External Citation Files

Citation information can also exist in external files. I usually only resort to importing from external files when importing from metadata embedded in a web page does not work. There are several citation file types (with extensions, such as *.bib and *.rdf). Fortunately, their details don’t really matter. Zotero should be able to import all of the ones you are likely to encounter. You can usually download these files from academic journal article databases (such as ScienceDirect and Google Scholar).

Exercise

Search for a famous journal article called “The Tragedy of the Commons” on Google Scholar. (Or click this link to navigate straight to the search results.) When I wrote this post, the second result was the correct article (by Garrett Hardin). Click on the link titled “Cite”. A dialogue will pop up with text that you can copy and paste for MLA, APA, and Chicago-style citations. Click on any of the links at the bottom of the dialogue: BibTeX, EndNote, RefMan, or RefWorks. The format doesn’t really matter, but RefMan is Zotero’s native format, so I recommend clicking that one. Another dialogue will pop up asking you where to download the file on your hard drive. Select a location, and download the file. (If you clicked on the RefMan link, the file will have a *.ris extension.)

Next, open Zotero, click on the gear button (which should reveal a drop-down menu containing items like “Import ...” and “Import from clipboard”). Click on the item labeled “Import ...”. Zotero will pop up a dialogue, so you can select the file from your hard drive. Do so, and Zotero will import the citation information for “The Tragedy of the Commons” by Garrett Hardin into your library.

PDF with Embedded Metadata

Just like web pages, PDFs of recent academic journal articles often contain embedded metadata. Zotero can extract this data and write a new entry in the Zotero database for the PDF. Note that this usually only works with PDFs of relatively recent academic journal articles, but you can try it with any PDF.

Exercise

Download the full text of the first result from the Google Scholar search in the previous exercise. This is an article written by Elinor Ostrom, a Noble Prize winner, who has written extensively about the tragedy of the commons and common-pool resources. Or you can directly retrieve the PDF by clicking here.

Open Zotero, and drag the PDF into the main window (which should also list other references, usually according to title and author). After doing so, the PDF will appear with an Adobe Acrobat symbol next to it, but the citation information for the PDF has not been properly entered into the database, yet. Right-click on the title of the PDF. A menu will pop up; select “Retrieve Metadata for PDF”. Another dialogue will pop up showing Zotero’s progress. If Zotero is able to retrieve the metadata for the PDF, it will automatically create a new entry and save the PDF as an attachment to the entry.

Note that you can select multiple PDFs at the same time, right-click on them, and retrieve metadata as described above for a single PDF.

Shared Libraries

Zotero comes with an amazing feature that lets Zotero users share references with each other via Zotero Groups, again, for free. See the link for instructions on setting up Zotero Groups and syncing your Zotero collection.

If you have a shared library (whether the library is owned by you or another person), sources that are added or edited by any member of the shared library will appear in your local copy of the library. If you have enough storage for the library (currently everyone gets 300 MB for free), attachments (including PDFs) will sync, as well. These sources are available to you like any other source in your library.

Using Your Reference Library to Make Citations

In Word for PC, Zotero commands appear in their own toolbar. In Word for Mac, Zotero appears under the script icon between the “Window” and “Help” menus. To insert a citation, click “Add citation”. The first time you use this command in a Word document, Zotero will ask which citation format you want to use in that document. Select your preferred citation format from the pop-up menu, and I recommend to leave the “Store references in document” option checked. Doing so ensures that when you share your document with others, they will also be able to see and work with your Zotero citations.

Anytime you insert a citation from Zotero, a Zotero search bar will pop up, or Zotero will bring you to a window of your Zotero library. If the search bar pops up, type in the author or title of the source you want to cite. If the window of your Zotero library pops up, click on the source(s) you want to cite. Zotero will automatically insert a properly formatted in-text citation.

You may need to edit your citations as you draft your document or to format them properly (e.g., to add a page number for an in-text citation after a direct quote). You can modify in-text citations by clicking on them (so the cursor is in the in-text citation) and then selecting “Edit citation” from Word’s Zotero menu. A Zotero dialogue will pop up. Right-click on the citation you want to modify, and select the options you want.

At any time, you can use the “Add bibliography” command in Word’s Zotero menu to insert the full reference list. The reference list will appear in the same citation format as the in-text citations.

To change the citation format for both in-text references and the reference list, use the “Set document preferences” command in Word’s Zotero menu.

Using More Citation Formats

Zotero has many citation formats (7,449 at the time of writing)—far more than the basic APA, MLA, and Chicago styles. See the Zotero Style Repository for a list. If you’re writing a manuscript for an academic journal, Zotero might even have a custom citation style for the journal you’re submitting to. Zotero does not automatically download all the available citation styles. The most popular ones are preloaded, and others need to be downloaded and installed manually. (See here for instructions.)

Additional Resources

Of course, this tutorial is not exhaustive, so here are some additional resources for your further edification:

  • This page includes a tutorial for installing Zotero.
  • Here is a video tutorial on installing and using the Zotero plug-in for Word.
  • This page has a video tutorial that goes over the basics of using Zotero.
  • Finally, this page contains links to a variety of more specific topics on using Zotero.

Monday, March 2, 2015

Automating Sente Exports

In this post, I’ll provide some guidance on getting and using Sente’s reference library without opening the application itself. In last week’s post, I wrote about fixing Sente’s export to BibTeX. Being able to fix up the *.bib file that Sente exports helps with writing documents in LaTeX. Using the fix that I demoed in last week’s post, you could also make your reference metadata more consistent (e.g., removing internal periods from US state abbreviations) and ensure the metadata conforms to your style guide (e.g., capitalization of source titles). However, the fix that I demoed requires opening up Sente and exporting the reference library both as SenteXML and as BibTeX. Doing so is not an unbearable burden, but it obstructs fully scripting (i.e., fully automating) parts of the workflow.

Sente Library Basics

The Sente reference library is an SQLite3 database. SQLite is a implementation of SQL, and, according to its website, “the most widely deployed SQL database engine in the world.” In my experience, it is lightweight and relatively easy to use.

To access Sente’e SQLite database, you first have to find it. Sente library files have the extension *.sente6lib. This file is actually a folder that contains several files including the SQLite database and PDFs for articles (if you have elected to include them in the Sente library file).

Open a terminal and navigate to the folder containing the Sente library file. Then, navigate into the sub-folder with the SQLite database. One of my library files is called ASU-References or ASU-References.sente6lib in full, so to get to the folder containing the SQLite database, I enter the following in the terminal:

cd ASU-References.sente6lib/Contents

As far as I can tell, the SQLite database is always called primaryLibrary.sente601, although it may differ in other versions of Sente. To get into the database, enter the following in the terminal:

sqlite3 primaryLibrary.sente601

This command opens SQLite and allows you to get information about the database and its tables and to perform SQL queries on the database. To get a list of tables in the database, enter

.tables

To get the schema for a given table, enter

.schema TABLENAME

For example,

.schema Reference

To get just the column headings, enter

.indices TABLENAME

For example,

.indices Reference

These are some helpful basics. For a full list of SQLite commands, simply enter

.help

To exit SQLite, enter

.q

Sente Citation Identifier

One of the most valuable pieces of identifying information about a source is its Sente citation identifier. The citation identifier is the tag that Sente reads when it scans text documents (e.g., Word documents). An example in-text citation follows:

This is a made up sentence for display purposes only {Arnstein 1969}.

The tag is “{Arnstein 1969}”. So if you’re using Sente to cite sources, your documents are full of Sente citation identifiers. And if you want to do something automatic with citations, there is a good chance you will want to retrieve information about a source based on its citation identifier.

The citation identifier appears in the SparseAttribute table, which contains a lot of other additional information about each citation, too. The table has three columns:

  • ReferenceUUID
  • AttributeName
  • AttributeValue

Here are the table contents for one reference in the SparseAttributes table:

C914FC95|EndNote reference number|116
C914FC95|publicationCountry|
C914FC95|publisher|Routledge
C914FC95|Primary contributor role|Author
C914FC95|DOI|10.1080/01944366908977225
C914FC95|BibTeX cite tag|arnstein1969ladder
C914FC95|Citation identifier|Arnstein 1969
C914FC95|publicationStatus|Unknown
C914FC95|ISSN|0194-4363
C914FC95|Web data source|Google Scholar

In the output above and throughout the rest of the post, I have abbreviated the entry in the first column, which is the ReferenceUUID, from C914FC95-5EE5-4C2D-BC80-1621EC22C2EC to C914FC95.

This particular reference is a well-known article on community participation. Its full citation is

Arnstein, Sherry R. 1969. “A Ladder of Citizen Participation.” Journal of the American Planning Association 35 (4): 216–224. doi:10.1080/01944366908977225.

Sente References’ ReferenceUUID

As far as I can tell, the ReferenceUUID is Sente’s true key for each entry in the database. In database terms, the ReferenceUUID is the unique, primary key for a reference.

Aside from being the primary key for a reference, the ReferenceUUID is also important because Sente will serve it up to other applications that request information about highlighted Sente references. For example, to use Robin Trew’s AppleScript (which exports Sente reference notes to DevonThink), you highlight references in Sente and then run the script. The script gets the ReferenceUUID for highlighted references, uses it to grab more information (including notes) about each reference, applies some formatting, and then ships the results to DevonThink. I recommended using this AppleScript in my original post on academic workflows.

It should be possible to pull the citation identifier out of the AttributeValue column by looking up the ReferenceUUID for a given reference, selecting the row that contains “Citation identifier” in the AttributeName column, and pulling the value in the AttributeValue column for that row. For the Arnstein reference, the goal is to retrieve the seventh row from the output above. The seventh row is

C914FC95|Citation identifier|Arnstein 1969

I would expect the following SQL query to retrieve the citation identifier:

select AttributeValue from SparseAttribute 
where AttributeName='Citation identifier' 
and ReferenceUUID='C914FC95'; 

But this query fails. To figure out why it fails, I examined the schema for the SparseAttribute table, which is

CREATE TABLE SparseAttribute 
    ( ReferenceUUID varchar, 
    AttributeName varchar COLLATE SenteLocalizedNoCase, 
    AttributeValue varchar COLLATE SenteLocalizedNoCase );
CREATE INDEX SparseAttributeByName 
    ON SparseAttribute ( AttributeName );
CREATE UNIQUE INDEX SparseAttributePK 
    ON SparseAttribute 
    ( ReferenceUUID, AttributeName );

Note that this table has a collation sequence. I have to admit that I don’t know what that is or what it does, but it causes the SQL query to throw an error. The following is a corrected version of the SQL query:

select AttributeValue from SparseAttribute 
where AttributeName='Citation identifier' COLLATE NOCASE 
and ReferenceUUID='C914FC95' COLLATE NOCASE;

This SQL query gives the following result:

Arnstein 1969

This is the correct citation identifier for the reference.

Next Steps

When I was working on my dissertation, I found that Robin Trew’s AppleScript stopped working. I was relying on the script to export Sente reference notes to DevonThink, and it was a key part of my workflow. The AppleScript makes SQL queries to Sente’s reference database, processes the information it retrieves, and then sends it to DevonThink. So I used all this information about Sente’s SQLite database to update the script and get it working again. If people are interested, I can post my version of the script, although mine may have become out of date by now, too.

In general, I hope this post helps other people who want to write scripts that retrieve information about their Sente references. With access to Sente’s SQL database, it’s possible to do … pretty much anything with metadata about references in your Sente library. You could even reimplement Sente’s export commands (e.g., to fix errors in the way Sente exports to BibTeX).