Annotations

Overview

For an overview of how to annotate artifacts, please see the following YouTube video.

How do I create a structured analytic?

Technically, a structured analytic is a tag that gets applied to an analytic. So let’s say that you have the question: “What is the main argument of the article?” and you want to add it to a structured analytic called “Analyzing a research paper.” In PECE, “Analyzing a research paper” would be a tag that the user associates with the question. By structuring the structured analytic as a tag (rather than a folder or some other encompassing structure), users can associate their questions with more than one structured analytic without having to duplicate the question in multiple structured analytic folders.

Because of this, in order to create a structured analytic, the user should simply create an analytic and add a new tag (by clicking on the green ‘+’ next to the list of question sets). The user will be directed to a new form where they can name the structured analytic and add a description. Once the analytic is saved the structured analytic will be added to the list of structured analytics with which analytics can be associated.

How do I create an analytic?

Navigate to ‘Dashboard’. This link is listed in the main menu. Under the ‘Add Content’ heading, select ‘Analytic’. You will be directed to a web form to create the content. Enter the relevant fields. Select the structured analytic that the analytic will be added to. If you would like to add the analytic to a new structured analytic, follow the instructions for creating a new structured analytic. Save the content.

How do I annotate an artifact?

Navigate to the artifact you would like to annotate. Click the ‘Annotate’ button below the artifact. Select a ‘Structured Analytic’ (set of questions) that you will use to annotate the artifact, and click ‘Continue’. Select a question to respond to, and click ‘Continue’. To add a question, Select <Create new>, enter the question title in the field that appears, and click ‘Continue’. Enter the relevant fields, and click ‘Save and Continue’. Repeat steps 4 and 5 until finished annotating and then click ‘Finish’.

Frequently Asked Questions

What is the difference between a structured analytic, an analytic, and an annotation?

Analytic: An analytic is a question designed to elicit various viewpoints about the artifact.

Structured Analytic: A structured analytic is named set of organized questions (or analytics).

Annotation: An annotation is a user's response to an analytic.

Do I have to answer all of the questions for a certain structured analytic when annotating an artifact?

No, you can skip a question.

When creating an annotation, if I hit Save and Continue, and then decide I do not want to answer another question, there is no button for ‘Finish’ from the window that lists structured analytics or the window that lists analytics. Will I lose all of my work if I close out of the window?

No, as soon as you hit Save and Continue, the response to your question is saved. You can now close out of the window or ‘Cancel’ at any point without losing your previously saved work.

How do I edit an annotation?

PECE users should be able to edit their own annotations from any interface where their annotations are displayed by clicking on the ‘Edit Annotation’ button. See How do I access my annotations?.

How do I edit an analytic?

The titles of analytics should not be edited for any reason. Since all questions on the platform are shared, and users may have already used the question to annotate an artifact, changing the text of the question could comprise the context of existing annotations on the platform. To add the analytic to another structured analytic, navigate to the page for analytic, and click the ‘Edit’ tab. Check the box for the structured analytic to which you would like to add the analytic.

How do I see a list of all existing structured analytics?

In the newest update to PECE, navigate to the ‘Analyze’ link. This link will be listed in the main menu. A list of all existing structured analytics will appear here.

How do I see a list of all analytics in a given structured analytic?

In the newest update to PECE, navigate to the ‘Analyze’ link. This link will be listed in the main menu. A list of all existing structured analytics will appear here. Click on the structured analytic to be directed to a list of analytics that have been designated a part of that structured analytic.

How do I reorder the structured analytics list?

1. First, refer to the "Analyze" page to see the current order of your list.

2. Then, click on the structure tab on the top menu bar.

3. In the dropdown menu, click on Taxonomy.

4. In the Taxonomy page, click on "list terms" of the Structured Analytics row. Here you will see a list of all the terms in your structured analytics page.

5. If you want a certain term to appear at the top of the list, first click on that term. Then, click on edit. Click on relations, and set the weight to -50. Save your changes. Go back to the Analyze page to check if your changes have been made.

6. If you want other terms to appear at the top of the list, repeat steps 2-5 but use different weights. The list is ordered from smallest weight to highest weight. So, if you wanted another term to appear second on the list, you would use a weight of -49. Likewise, if you wanted another term to appear at the top of the list, you would use a weight of -51 and so forth.

Demo video

How do I access my annotations?

There are a few options for accessing annotations.

1. Navigate to your ‘Dashboard’ and click on the tab for ‘Annotated Artifacts’.

2. Navigate to an artifact that you’ve annotated. Under the rendered file and the ‘Annotate’ button, you will see a list of users that have annotated the artifact. Click on your username to see your annotations of the artifact.

3. Navigate to the ‘Analyze’ link in the main menu. Click on a structured analytic you’ve used to annotate an artifact and a question that you’ve used to annotate an artifact. You can then filter this page to your username to see the annotations that you’ve created from this question.

How do I see how others annotated an artifact?

Navigate to the artifact. Under the rendered file and the ‘Annotate’ button, you will see a list of users that have annotated the artifact. Click on a username to view their annotations. From the page that lists the user’s annotation of an artifact, you can also click on a question to see how multiple users responded to that question for the artifact.

How do I see all of the responses to a particular analytic?

In the newest update to PECE, navigate to the ‘Analyze’ link. This link will be listed in the main menu. A list of all existing structured analytics will appear here. Click on the structured analytic to be directed to a list of analytics that have been designated a part of that structured analytic. Click on the analytic to view all responses to the analytic. From here you can filter the responses to a particular user’s responses or to responses to a particular artifact.

How do I see all of the responses to a particular analytic for a given artifact?

See How do I see all of the responses to a particular analytic?

How do I see all of the responses to a particular analytic created by a given user?

See How do I see all of the responses to a particular analytic?

I annotated a Private or Restricted artifact, and my annotation is appearing in both Search and on Tag pages. Shouldn’t my annotation be Private or Restricted if it is responding to a Private or Restricted artifact?

Yes, it should. Unfortunately, right now, all annotations default to Open.

Annotation Etiquette

There are several important things to remember when creating analytics for the platform. All analytics are shared by everyone across the platform. As soon as you create an analytic, it is available to everyone in the platform to use for annotating any artifact. PECE has been designed to take advantage of this. As diverse users respond to the same set of questions, it becomes possible to juxtapose answers to questions.

Therefore,

1. You should avoid creating questions that respond to only one artifact or are relevant to only a very specific fieldsite within a broad structured analytic. For instance, you should avoid adding a question like, “How has the Obama administration’s Open Government Directive influenced the New York City open data policy?” under a structured analytic called “Profiling a Policy.” Instead, a question like, “How have existing policies and directives influenced the structure and content of this policy?” would be accessible to many users on the platform to annotate many artifacts about diverse policies.

2. More specific questions should all be categorized into Structured Analytic. A question like “How has the Obama administration’s Open Government Directive influenced the New York City open data policy?” would be appropriate in a structured analytic called “Profiling the New York City open data policy,” which could be useful if a set of researchers were all going to be annotating artifacts related to the New York City open data policy.

It can be valuable to use the structured analytic headings to cordon off more specific questions so that certain groups can respond to the same set of questions. For instance, in The Asthma Files, we have one Structured Analytic called “Special Issue for Transport Policy.” A group of researchers created this analytic so that they can share a set of questions for annotating each other’s abstracts for a special issue to which they were all contributing articles. While these questions were not relevant to any other users on the platform, categorizing the questions under the “Special Issue for Transport Policy” structured analytic, separated these questions out from other more general questions.

1. Be sure to navigate the existing structured analytics by clicking on ‘Analyze’ in the main menu before creating a new analytic or structured analytic. If you see questions or sets of questions similar to the ones you were planning to create, gauge whether there is analytic value to create a separate analytic. If you do create a separate analytic, it will not be possible to juxtapose the responses to this question to the responses the similar questions you identified. This is a tradeoff that you will need to consider.

2. If a question is relevant to more than one structured analytic, categorize it under both structured analytics following these instructions. Do not duplicate the analytic to categorize it under a separate structured analytic.