Flash API for Boosters
Please discuss on the Talk page.
General coding form
Accessing the applet
var applet = document.getElementById('maingame');
if (applet == null) return "maingame element missing";
from there, APIs can be used like this:
var ok = applet.set_sequence_string(my_seq);
Exploring the API without writing a booster
Every modern browser has some sort of console that lets users input javascript commands.
- Open the puzzle
- Use the stamper option in the booster menu, but cancel the operation. This activates the scripting interface
- Open the javascript console of your browser, and play around
Now let's see what happens:
Synchronous vs Asynchronous
The Tsumego script is an example of a synchronous booster. Synchronous boosters have following properties:
- they do not use setTimeout() or setInterval()
- they return a simple value
The Naive Solver script is an example of an asynchronous booster. The features that make it asynchronous are:
- it uses setTimeout()
- the script signals asynchronicity to the applet by using the statement:
return {async: "true"};
- the actual end of the execution is signalled by calling:
applet['end_'+sid](r);
where sid is the Drupal node ID of the script (here, 6713763) - EternaScripts have timeout-checking statements automatically inserted in loops. A special statement is used in lengthy computations to prevent this global timeout (10 seconds by default) from unwanted triggering:
global_timer = new Date();
Omei's understanding after talking with Nando:
- Having a booster return {async: "true"} has one and only one direct effect. Specifically, it blocks any additioanal user input while still allowing the UI to be updated by booster code that has been or will be initiated by event triggering. User input will be reenabled only when the applet['end_'+sid](r) code above is executed.
Getters
get_sequence_string()
Parameters: none
Returns:
a string representing the sequence
get_full_sequence(index)
Parameters:
index: 0-based index of the state to be queried
Returns:
a string representing the full-length sequence, including the oligos in the case of a multistrand puzzle
get_locks()
Parameters: none
Returns:
a 0-based array of booleans indicating locked (true) and mutable (false) positions in the puzzle
get_targets()
Parameters: none
Returns:
an array of objects describing the structural constraints of each state in the puzzle (details to be added later)
get_native_structure(index)
Parameters:
index: 0-based index of the state to be queried
Returns:
the dot-bracket representation of the predicted MFE for the queried state in the puzzle (i.e. the native fold)
get_full_structure(index)
Parameters:
index: 0-based index of the state to be queried
Returns:
the complete dot-bracket representation of the predicted MFE, including oligos, for the queried state in the puzzle (i.e. the native fold)
get_free_energy(index)
Parameters:
index: 0-based index of the state to be queried
Returns:
the free energy of the queried state
get_tracked_indices()
Parameters: none
Returns:
an array listing the indices of the bases that have been marked with the black mark
get_barcode_indices()
Parameters: none
Returns:
an array listing the indices of the bases forming the barcode, if present in the lab puzzle
is_barcode_available()
Parameters: none
Returns:
a boolean describing whether the barcode in the puzzle is still available for the current round or not
current_folder()
Parameters: none
Returns:
the name of the currently selected folding engine (only available in labs)
check_constraints()
Parameters: none
Returns:
a boolean describing whether all constraints are fulfilled (true) or if at least one of them fails (false)
Setters
select_folder(folder_name)
selects a folding engine by its name
only available in lab puzzles
Parameters:
folder_name: name of the folding engine to be used
Returns:
a boolean, true if successful, false otherwise (the operation may fail, for instance Vienna2 cannot be selected on a puzzle that contains multistrand states)
set_sequence_string(seq)
sets the sequence in the puzzle
the applet recomputes foldings, free energies and reevaluates contraints
Parameters:
seq: the sequence
Returns
a boolean, true if successful, false otherwise (the operation may fail, if seq contains invalid characters for instance)
set_tracked_indices(marks)
sets all black marks in the puzzle
Parameters:
marks: an array of indices of bases to be marked
Returns: nothing
set_design_title(design_title)
Data browser specific.
Displays a title for the current view.
Parameters:
design_title: a string containing a title/description
Returns: nothing
Folding
fold(seq, constraint = null)
Folds the seq sequence, eventually considering limitations defined in constraint
Parameters:
seq: a string representing the sequence to be folded
constraint: optional constraints (Vienna formatted)
Returns:
the dot-bracket representation of the MFE structure
energy_of_structure(seq, secstruct)
computes the free energy of the seq sequence folded as specified by secstruct
Parameters:
seq: the sequence
secstruct: the dot-bracket representation of the secondary structure
Return:
a floating-point number, expressed in kcal/mol
fold_with_binding_site(seq, site, bonus)
(tbd)
pairing_probabilities(seq, secstruct = null)
(tbd)
cofold(seq, oligo, malus = 0., constraint = null)
(tbd)
Miscellanous
sparks_effect(from, to)
initiates a sparking effect on the specified segment
Parameters:
from: start index
to: index of the last base
Returns: nothing
