// $Id: keysets,v 1.2 1995/02/18 20:50:04 rd Exp $

            Keysets (summary) -- Sam Cartinhour

A keyset is a collection of object names from one or more classes.
They are used thoughout ACEDB to support browsing, queries, analysis,
display, and data management. Keyset windows can have a variety of
labels ("Keyset", "New Keyset", "Query Answer", "Exported Keyset",
"Main Keyset", and "Copied Keyset") but their functionality is the
same. Note that there is a class called "KeySet" that may appear on
your main window. It is possible to name and save keysets; if you do
so they will appear as members of this class.

-----Putting things into and getting them out of keysets

Users first encounter keysets via the main window. When ACEDB starts
the most "senior" class (upper-left) on the main window is opened and
the names of its members displayed in the Main Keyset. The contents of
the keyset are replaced if a new class is double-clicked.  The default
is always to show every member of a class. However, the Template box
makes it possible to display only those objects whose names fit a
certain pattern.  For example the Template *a will pass only those
objects whose name ends with the character 'a'.

The Text search box (main window) also generates a keyset but differs
from the Template box in three important ways. (1). Although the Text
Search examines object names, it does so for all classes, not just the
one currently selected in the main window. (2). Text Search looks
inside every object and examines the contents of any ?Text fields
against the pattern. (3). The resulting keyset may contain objects
from more than one class. The user will need to open them to determine
class identities.

Other simple keyset manipulations are available in any keyset window's
pop-up menu. "Add-Remove Keys" makes it possible to assemble a keyset
using completely arbitrary criteria. Items are added by
double-clicking on object or object symbols in any available window
(try the arrow keys!!).  An object is removed from the keyset by
double-clicking on it in the keyset window. "Copy" copies all the
members a keyset to a "Copied Keyset" window.  "Save" allows the user
to name and save a keyset. It then appears as a member of the KeySet
class on the main window.

Set operations (AND, OR, XOR, MINUS) are also available on a keyset's
pop-up menu. Note however that these apply to a pair of keysets.
Select the first keyset by clicking once on any of its objects; you
have succeeded when the pink "Selected Keyset" box shows at the top of
the window. Then pop the menu in the second keyset and choose one of
the operations. "AND" will display the intersection; "OR" their union;
"MINUS" will remove whatever is in the first keyset from the second
keyset; "XOR" will display whatever is *not* in common between the
keysets. Warning: currently these operations are destructive in that
they replace the second keyset (the one from which the menu is popped)
with the "answer" and there is no "undo". Also, popping the menu from
the selected (pink rectangled) keyset means that the two keysets being
compared are identical. Thus: AND, MINUS and XOR will wipe out your
keyset and OR will do nothing.

"Find Neighbors" generates a new keyset. Each keyset object is
examined and any object linked to it is added to the keyset. A few
rounds of this will collect zillions of objects in a
well-interconnected database.

Note that keysets can be acquired from "highlighted" objects on some
graphical displays. Howeverm "highlighted" means more than "specially
colored". For example, clicking once on a map locus does *not*
"highlight" it. Keysets can also be generated by analysis tools.

-----Dumping information into files from keysets

Information can be dumped from a keyset window using the menu items
"Ace Dump", "Name Dump" and "Sequence Dump". The first dumps (in .ace
format) all the information associated with each object in the keyset.
The second dumps only the object names (you can use this to create
a keyset as a .ace file). The third option creates a file of sequence
data in FastA format.

-----Miscellaneous things you can do to keyset members

"Show as Text": show any selected object in the keyset in a tree
(text) display; useful if the default for the object is a special
graphical display.

"Show as Multimap": allows maps to be compared via the  Multimap
display.

"Show Related Biblio": triggers the biblio display for all the
members of the keyset. Currently this works only if the objects
are associated with bibliographic references via a "Paper" tag.

Don't forget: you can browse keyset members using the up or down arrow
keys.

-----not discussed at all (hopefully will be covered by others)

Some displays (e.g., the genetic map) are sensitive to keysets.
Some analysis tools (e.g. DNA) also use them.
Query answers are always expressed as keysets.
The TableMaker can examine keysets and can export objects to them.