Have any questions? Please email us at ecoliwiki@gmail.com

Cacao

Jump to: navigation, search

This page is intended to be a reference for setting up a new session for CACAO on GONUTS FOR INSTRUCTORS.

Things you'll need

A class roster or list of participants
Each student needs to have a username (either chosen or assigned) and a valid email address.
A (tentative) schedule of your class
You can set up CACAO in a variety of ways, see the discussion below for more information.
Topic(s) for annotation
CACAO can operate using any scientific literature, but it sometimes easier to focus upon a particular area

Setting up a CACAO session

Some definitions:

  • Session: We define a CACAO session as a group of annotation activities. These are typically a semester long, but can be of any arbitrary length.
  • Inning: A session is divided into one or more innings. An inning is divided into one or more parts based on the allowed activities
    • Annotation - Participants make annotations. Challenges are blocked
    • Challenge - Participants challenge annotations made by members of other teams. New annotations are blocked
    • Open - Both annotations and challenges are allowed.

A CACAO session involves several different kinds of pages on GONUTS.

Session scoreboard pages

Each CACAO session has a main scoreboard page with a name like Category:CACAO_Spring_2017. This organizes the teams in a CACAO session and is a central hub for the scoreboards and assessments. The schedule of innings is also set from the Session page.

The Session page name must start with a "Category:" prefix to place it in the Category namespace (this is required for various features like assigning teams to a Session)

Making an new session page

To create a new CACAO session,

  • make an empty page with an appropriate page name.
  • Put {{subst:CACAO page}} in the content and save it. The first time you save it the Scheduling table won't show up.
  • Click Edit and save it again.
  • Edit the schedule table to set up the innings.


Players and teams

While it is possible to set up players and teams manually, it is much easier to send us the information in a tab-delimited text file so we can use a script on the server to set everything up automatically.

If you don't know which users are going to be in which groups, don't worry - this is a wiki, it's quite flexible.

Organize users into groups

Some of the organization was done in the previous step. If you are not sure which students will be in which teams, you can defer this step until later. It is possible to edit any page at any time, and you can easily add a user to a category (a team) at a later date.

At this point in our tutorial the students have been arranged into teams, but the actual Category: pages for those teams do not have any content. You can edit each team's page by following links from users' pages (the containing categories are listed at the bottom of a page), or by browsing to them. For example, if you look at the example user-page above you will see Daniel is in Team Aggies. This means you will want to go to http://gowiki.tamu.edu/wiki/index.php/Category:Team Aggies.

Even though each user has a <cacao></cacao> table on their page it is sometimes useful to see an entire group's annotations. GONUTS is smart enough to show all annotations from all members of a group if you put a <cacao></cacao> tag on a category page. For example, Category:Team Aggies might look something like this:

Hello! We are TEAM AGGIES! Welcome to our team's page!

==Our Group's Annotations==
<cacao>
session = Texas A&M Sample CACAO 2011
</cacao>
 
==Our favorite links==
* http://tamu.edu 
* http://gowiki.tamu.edu

Each group must be put in the top-level category to be part of that Cacao. Just like we put the users into groups using categories, we will put the groups into a cacao using categories. In each group page add a Category: tag for the Cacao you would like to use. For example, we'll add our sample group to Texas A&M Sample CACAO 2011. The group's page would then look like this:

Hello! We are TEAM AGGIES! Welcome to our team's page!

==Our Group's Annotations==
<cacao>
session = Texas A&M Sample CACAO 2011
</cacao>

==Our favorite links==
* http://tamu.edu 
* http://gowiki.tamu.edu

[[Category:Texas A&M Sample CACAO 2011]]

This must be done for each group.

Ambox notice.png To be part of CACAO a groups page must include a single <cacao></cacao> set of tags with one parameter in-between them:
  1. session = session
    The session/class the user is in, with or without the Category: prefix.


==See Also==
*Help:Gene Ontology
*Category:CACAO

Where to go for Help

If you have any questions or none of this makes any sense to you, then please email us at ecoliwiki@gmail.com. Someone from our team would love to help you get started using GONUTS. We can also set up some training via phone-conference on everything from using GONUTS to "what is the Gene Ontology." Please don't hesitate to contact us.

CACAO Code

The code for CACAO is written as an extension to Mediawiki. It is written in object-oriented PHP and is free for download. Please email us for more information.

See Also

This is the general help for the CACAO software. Here you will find information on how to use the parser tags and what types of parameters they expect.

Terminology

session
The highest level at which groups can be arranged. Multiple sessions can be run concurrently on GONUTS, but they are always mutually exclusive. No students from one session can challenge annotations from students in another session.
Session pages are always Category: pages that contain zero or more groups.
group
A Category: page containing students' User: pages. Students are grouped together to compete against each other. All annotations made while a member of a group are attributed to that group. Points are assessed based on the groups annotations and challenge history.
inning
A time interval during the CACAO semester in which annotation, challenges, and assessments are made. Each session must contain at least one inning, though it could last the entire semester. Innings run sequentially, though multiple innings from different sessions can run concurrently.
period
A time interval during an inning in which only one action is allowed. For example, there can be an annotation period and a challenge period during an inning in which only that action is allowed. This was created to keep students from challenging each other while they should be focus on annotating.

Parser Tags

The CACAO software requires the use of "parser tags" in some pages. These tags are similar to HTML or XML tags, and in general look like: <<i>tag_name</i> />. These tags are placeholders for more complicated content that usually needs to be created dynamically. For example, putting the <cacao /> tag within a user's Userpage will show his/her annotations for CACAO to show up once the page is saved.

Below is a list of the available tags for CACAO.

<cacao />

The <cacao /> tag will show the annotations for a particular user or group, depending on which type of page it is on. If it is on a page in the User namespace, it will show all annotations for that user, irregardless of which group that user is currently in. If it is on a page in the Category namespace, it will show all annotations that were made for that group -- even if those users are not currently in that category.

It is important that the members of the group are included in the Category of their group so that their annotations show up using the <cacao /&gt tag. For example, if a user specifies his/her group as "Foo", but does not have the associated wikitext [[Category:Foo]] in their page (which adds them to the group), then their annotations will not show up on the Category:Foo page. The <cacao /&gt tag will show a message saying that they are not currently in the group, but won't fix the problem.

Usage:

<cacao>
group   = Category:Foo
session = Category:Bar
</cacao>
group
The group that this user is in. It can be specified with or without the "Category:" prefix (as all groups are categories.)
session
The global session that this user is in. It can be specified with or without the "Category:" prefix (as all session are categories containing multiple groups.)

<scoreboard />

The <scoreboard /> tag shows the current standing of all groups participating in a global session of CACAO. This tag is typically found on the Category page that contains all the groups for a class. Given no parameters, the tag assumes that it is on a global session page and tries to display a scoreboard for that session. Alternatively, you can specify a session using the session= parameter like so:

<scoreboard>
session = Category:Foobar
</scoreboard>

In this case it will display a scoreboard for the Foobar CACAO session.


<myAnnotations />

The <myAnnotations /> tag was used in previous versions of CACAO to show a user or group's annotations. This tag has been deprecated in favor of the <cacao /> tag. It will still work, however, and will behave exactly as the <cacao /> tag does.


Setup & Technical

This section is for the system administrator or the curious user :).

Requirements

Because the CACAO system was developed in-house for the Hu Laboratory at Texas A&M University, it requires a number of MediaWiki extensions and code libraries developed by our lab.

extension
  1. TableEdit
  2. DataTables
libraries
  1. The Hu-Lab code/ library, an extension of the MediaWiki framework for biological wikis.

Everything used to run GONUTS and CACAO is open-source and available upon request. Please contact Jim Hu or Daniel Renfro for more information.

Global Variables

These variables are placed within LocalSettings.php. It does not matter whether they are defined before or after the CACAO code is included.

$wgCacaoTableTemplate

This variable defines the TableEdit template for the annotation table.

$wgCacaoInstructor

This variable defines the name of the role of the CACAO instructor. Using this information, CACAO sets up permissions for annotation, challenging, and assessing. An example:

$wgCacaoInstructor = 'cacao_instructor';
$wgGroupPermissions[$wgCacaoInstructor]['*'] = true;

$wgCacaoPointsForAnnotation

The number of points a team is awarded for making a single annotation - the value should be an integer. The default is 5 points.

$wgCacaoGlobalSessions

A large array defining the global sessions and their innings. Each session can have multiple innings, and each inning can have multiple (mutually exclusive) periods. Each period must contain at least a start and an end. See below for an example:

/**
 * Global session assignment. Session-names need to be in the following format: "Category:_______".
 *   It's best to just copy-and-paste the appropriate part of the URL from your browser into this
 *   array of settings.
 */
$wgCacaoGlobalSessions = array(

	// Older cacao sessions; defined here so that their <scoreboard />s still show/render 
	'World_Series_2011_CACAO' 		=> array(),
	'Category:CACAO_Fall_2010' 		=> array(),
	'Category:CACAO Spring 2011' 	=> array(),
	'Category:Penn State CACAO'		=> array(),

	// Current cacao sessions
	'Category:CACAO Fall 2011' => array(
		array(
			'annotation' 	=> array( 'start' => '2011:09:19 00:00:00', 'end' => '2011:09:25 23:59:59' ),
			'challenge' 	=> array( 'start' => '2011:09:26 00:00:00', 'end' => '2011:10:02 23:59:59' ),
		),
		array(
			'annotation' 	=> array( 'start' => '2011:10:03 00:00:00', 'end' => '2011:10:09 23:59:59' ),
			'challenge' 	=> array( 'start' => '2011:10:10 00:00:00', 'end' => '2011:10:16 23:59:59' ),
		),
		array(
			'annotation' 	=> array( 'start' => '2011:10:17 00:00:00', 'end' => '2011:10:23 23:59:59' ),
			'challenge' 	=> array( 'start' => '2011:10:24 00:00:00', 'end' => '2011:10:30 23:59:59' ),
		),	
		array(
			'annotation' 	=> array( 'start' => '2011:10:31 00:00:00', 'end' => '2011:11:06 23:59:59' ),
			'challenge' 	=> array( 'start' => '2011:11:07 00:00:00', 'end' => '2011:11:13 23:59:59' ),
		),	
		array(
			'annotation' 	=> array( 'start' => '2011:11:14 00:00:00', 'end' => '2011:11:20 23:59:59' ),
			'challenge' 	=> array( 'start' => '2011:11:21 00:00:00', 'end' => '2011:11:27 23:59:59' ),
		),
		array(
			'closed'		=> array( 'start' => '2011:11:28 00:00:00' )
		)
	),
);	

$wgCacaoDebug

When set to true (or any expression that evaluates true,) the scheduling code is turned off - meaning that anyone can preform any action at any time. This is typically for debugging when we don't want to check the $wgCacaoGlobalSessions array.