Flash API for Boosters

From Eterna Wiki

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

 

Flash API 1.png

Flash API 2.png

 

Now let's see what happens:

 

Flash API 3.png

Flash API 4.png

 

 

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