GONUTS has been updated to MW1.31 Most things seem to be working but be sure to report problems.

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[edit]

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[edit]

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[edit]

To create a new CACAO session,

  • make an empty page with an appropriate page name. Double click on replace_session_name and replace it with the name of your session. The form will automatically place the new page in the Category namespace.

  • 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.
  • Go to the Talk page and put {{subst:CACAO talk page}} in the content and save it.

Players and teams[edit]

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.

Picking team names[edit]

We try to have all team names start with the word Team, which distinguishes CACAO teams from other Mediawiki category pages. A list of previously used team names can be found at Special:Cacao_Teams (you can see that we haven't always been good at enforcing the use of Team in the name).

Send us your roster[edit]

We can automate the creation of users and teams from a tab-delimited text file you send us. The format should be one user per row. Any row that starts with a # character is treated as a comment and is ignored. Example 

#Team                 username            user_real_name         user_email
Team Groot            IamGroot            Groot                  groot@iplant.org	
Team Groot            Rocket              Rocket Racoon          guardian@timely.com	
Team Star Lord        PQuill              Peter Quill            quill@ravagers.org	
Team Star Lord        KPryde              Kitty Pryde            shadowcat@xavierschool.edu	
Team Infinity         Gamora              Bambi Long             gamora@daughtersofthanos.org
Team Infinity         AdamW               Adam Warlock           Adam@tribumal.com

Note that the username can be anything but the first letter must be uppercase. The real name should be in First Last.

Using this text file, we can automatically create accounts and user and group pages for the competition. This assumes we also know the name of CACAO session the players are participating in. You can view what these look like by going to one of the older CACAO competitions and looking at the Team and User links from the scoreboard.

When the accounts are created, the participants will receive an email telling them to claim their account. If they don't get the email, they should check their spam filters. The account has to be activated within 7 days or the account activation will expire. We can fix these manually, but it's easier to have people confirm their accounts as soon as possible.

Where to go for Help[edit]

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[edit]

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[edit]

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[edit]

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[edit]

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 />[edit]

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 />[edit]

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 />[edit]

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[edit]

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

Requirements[edit]

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[edit]

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

$wgCacaoTableTemplate[edit]

This variable defines the TableEdit template for the annotation table.

$wgCacaoInstructor[edit]

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[edit]

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[edit]

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[edit]

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.

Retrieved from "https://gowiki.tamu.edu/wiki/index.php/Special:Cacao"