From GONUTS

Jump to: navigation, search

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

Setting up a CACAO session

Background Info

First, a word about categories, users, and pages on GONUTS. MediaWiki, the software we use to run GONUTS, allows many different types of pages to exist on the same wiki; we'll be interested in four of them:

(1.) Main Namespace

Normal pages are exactly what you think - creatable, editable places for documentation or notes. On GONUTS you are allowed to make pages as you see fit. However, because of the scientific nature of GONUTS, we've created tools to facilitate making pages (specifically pages about genes and ontology terms.) These pages are in the Main namespace and do not need a prefix (like some other namespaces which we'll see later.)

(2.) User Namespace

User: pages are wiki pages associated with a particular user. Each user gets his/her own page. On GONUTS we use these to display a users' annotations and put them in groups. These pages require the User: prefix before the pagename. For example, if you wanted to view Fred Flintstone's page you might browse to:

User:Yabba Dabba Doo

(3.) Category Namesapce

Category: pages group similar wiki pages by topic. Category pages can include content, but their main purpose is an organizational one. Categories in MediaWiki are constructed in a bottom-up type of fashion. Instead of listing a category's members on it's page, each wiki page lists the category it is in. This is done by putting the following code within the source of a page: [[Category:category-name]].

For example, a page about College Station, TX might include the following wikitext:

[[Category:Cities in Texas]]
[[Category:American college towns]]
[[Category:Friendliest places on Earth]]

You can find more information about categories at: http://www.mediawiki.org/wiki/Help:Categories.

(4.) Template Namespace

Template: pages are like Category: pages, but they do not organize content. Instead they provide a way of abstracting content into one place that can be included on many different pages. You need not worry about the Template: namespace much, MediaWiki handles things transparently.

More information about namespaces can be found at http://www.mediawiki.org/wiki/Help:Namespaces.

Overview

Setting up a CACAO class can technically be done in any order, but over the years (and through lots of trial-and-error) we've found that some things are easier when done in a specific order. Before we get started, here's a quick overview of the steps we'll proceed through:

make user accounts & setup user pages
organize users into groups, fill in group pages
organize groups into a session, fill in the session page

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.

Make user accounts & Setup user pages

Each participant of CACAO needs to have an account. GONUTS operates on the "Vampire-Model" of account creation: any registered user can create new user accounts. If you don't already have an account email us at ecoliwiki@gmail.com to set one up for you. Once you have an account you can create new accounts one at a time by going to Special:UserLogin and clicking create account. Typically all that is required for an account is an email and a real-name. We suggest clicking the "by email" button - this means GONUTS will create a temporary password and email it to the new user.

Once you have created the accounts you can do one of two things:

have the participants setup their user pages themselves
set up their pages for them

Each user page for participants of CACAO should contain (at the minimum) two things:

a <cacao></cacao> tag
- This tag will be where you specify which group and which class/session this user/student is in.
a team category
- We are using categories to group the users. (The way we put a user (or a user-page) into a category is similar to using templates, but instead of double curly-brackets we use double square-brackets with a Category: prefix. )

For example, Daniel's page looks something like this:

==My Annotations==
<cacao>
group = Team Aggies
session = Texas A&M Sample CACAO 2011
</cacao>
[[Category:Team Aggies]]

This is a very simple user page. You can insert this wikitext into a user page by clicking the edit tab at the top of the page, entering text into the textbox and then clicking save page.

To be part of CACAO a user's page must include a single <cacao></cacao> set of tags with two parameters in-between them:
group = group
The group the user is in, with or without the Category: prefix.

session = session
The session/class the user is in, with or without the Category: prefix.

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.

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

Setup Top-most Category

This page is where most of the class information will be and will contain the scoreboard and all challenge information. The scoreboard tag looks very similar to the <cacao></cacao> tag.

<scoreboard />

In semester prior to Fall 2011, the <scoreboard /> tag was called the <cacaoScoreboard /> tag. The latter is still allowed for backwards-compatibility, but deprecated nonetheless.

Here is a sample Cacao session page:

=Class Information= 
Welcome to another exciting semester of biocuration using the Gene Ontology! 

=Schedule=
* Tuesdays 7-8:   curating!!!

=Scoreboard=
<scoreboard />

==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 Daniel for more information.

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 TableEdit DataTables

libraries 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.

Cacao

Contents

Setting up a CACAO session

Background Info

Overview

Make user accounts & Setup user pages

Organize users into groups

Setup Top-most Category

Where to go for Help

CACAO Code

See Also

Contents

Terminology

Parser Tags

<cacao />

<scoreboard />

<myAnnotations />

Setup & Technical

Requirements

Global Variables

$wgCacaoTableTemplate

$wgCacaoInstructor

$wgCacaoPointsForAnnotation

$wgCacaoGlobalSessions

$wgCacaoDebug

Personal tools

Namespaces

Variants

Views

Actions

Search

Navigation

Cacao

Journal Clubs

Toolbox