Class GeneBitSet

java.lang.Object
  |
  +--GeneBitSet

class GeneBitSet

extends java.lang.Object

The class manipulates lists of 64-bit bit sets for performing Boolean set operations. It implements these operations (union, intersection, difference) efficiently. It is also a required data structure in GeneLists and is the default gene list representation. You may convert a GeneBitSet.bitset to an ordered gene list GeneList.mList[]. The notation talks about adding an "item" which is the mid value corresponding to a Gene. The GeneBitSet userBS[0:nUserBS-1] is the database of all GeneBitSets.

 A GeneBitSet has maxSize and is a (unsigned) long bitData[nWords] 
 where: 
       nWords= (maxSize/64)+1.
 For an endtry eIdx, it is indexed as ((bitData[wIdx] >>> bitIdx) & 01)
 where: 
       wIdx= eIdx/64 (i.e. eIdx >>> 6),
       bitIdx= eIdx - (wIdx*64), (i.e. wIdx<<6) 

This work was produced by Peter Lemkin of the National Cancer Institute, an agency of the United States Government. As a work of the United States Government there is no associated copyright. It is offered as open source software under the Mozilla Public License (version 1.1) subject to the limitations noted in the accompanying LEGAL file. This notice must be included with the code. The MAExplorer Mozilla and Legal files are available on http://maexplorer.sourceforge.net/.

Version:

$Date: 2003/04/03 21:03:27 $ $Revision: 1.7 $

Author:

P. Lemkin (NCI), G. Thornwall (SAIC), NCI-Frederick, Frederick, MD

See Also:

MAExplorer Home, GeneList

Field Summary

private static long	ALL_BITS 0XFFFFFFFFFFFFFFFF is all 64-bits that is also 1's complement -1
(package private) java.lang.String	assignedBSname if this was assigned from another bitSet
(package private) long[]	bitData list of nWords bit words allocated [0:maxSize-1] and active [0:highMID-1]
private int	bitIdx index within a bitWord right to left
private int	bitWord 64 bit long subset of bits from bitData
(package private) java.lang.String	bName name of bit set
private int	bsEnum enumeration index 0 to length-1
(package private) static boolean	cbsDbug flag: selective debugging enable
(package private) int	count # of ITEMS used in this GeneBitSet
(package private) int	highMID highest MID in this GeneBitSet
private static MAExplorer	mae link to global MAExplorer instance
(package private) static int	MAX_USER_BS max # user assignable gene bit setst hat can be created
(package private) int	maxItems maximum # ITEMS in bit space allocated
(package private) static int	maxUserBS max # user assignable gene bit sets
(package private) int	maxWords max # 64-bit WORDS alloc'ed in bitData[]
(package private) GeneList	ml Associated Master GeneList if any, else null
(package private) static int	nUserBS # user assignable gene bit sets in use
private static GeneBitSet	tempSetBL temporary bit set used in set operations
(package private) static GeneBitSet[]	userBS [1:maxUserBS] user assignable gene bit sets.
private int	wIdx index of bitWord = bitData[wIdx]

Constructor Summary

(package private)	GeneBitSet(MAExplorer maE, int maxItems, GeneList ml) GeneBitSet() - constructor to create a GeneBitSet without a name.
(package private)	GeneBitSet(MAExplorer maE, int maxItems, java.lang.String bName, GeneList ml) GeneBitSet() - constructor to create a named GeneBitSet.

Method Summary

(package private) boolean	addItem(int item) addItem() - add Item (i.e.
private void	allocGeneBitSet(int maxItems, java.lang.String bName, GeneList ml) allocGeneBitSet() - create named GeneBitSet by allocating bit set structures.
(package private) int	assignCLtoUserBS(java.lang.String userSetName, GeneList ml) assignCLtoUserBS() - assign GeneList ml to new user GeneBitSet userBS[] database.
(package private) boolean	assignCSbinOprToUserBS(java.lang.String bsName1, java.lang.String bsName2, java.lang.String userSetName, java.lang.String opr) assignCSbinOprToUserBS() - assign GeneBitSet binary Boolean opr to new user GeneBitSet.
(package private) void	cleanup() cleanup() - cleanup global static allocated variables in this class.
(package private) boolean	clearNull() clearNull() - clear gene bit set and set entries to null.
(package private) static boolean	copyBStoBS(GeneBitSet b1Dst, GeneBitSet b2Src) copyBStoBS() - copy GeneBitSet b2Src to GeneBitSet b1Dst.
(package private) boolean	copyBStoCL(GeneList c1Dst, GeneBitSet b2Src) copyBStoCL() - copy GeneBitSet b2Src to GeneList c1Dst.mList[].
(package private) static boolean	copyCLtoBS(GeneBitSet b1Dst, GeneList c2Src, boolean useCopyBitArrayFlag) copyCLtoBS() - copy GeneList c2Src to GeneBitSet b1Dst.
(package private) boolean	cvtBStoCL(GeneList ml) cvtBStoCL() - convert GeneBitSet ml.bitSet to GeneList c1.mList[] (allocate data structures if needed).
(package private) boolean	difference(GeneBitSet b1, GeneBitSet b2, GeneBitSet b3) difference() - difference of GeneBitSets (b2 - b1)==> b3.
(package private) int	findCountAndhighMID(GeneList ml) findCountAndhighMID() - find count and highest MID in gene bit set BitData[].
(package private) java.lang.String[]	getGBSnames() getGBSnames() - return String array of active Gene Bit Set names.
(package private) java.lang.String	getListGeneBitSetsStr() getListGeneBitSetsStr() - convert list of active GeneBitSets userBS[] to summary print string.
(package private) boolean	intersection(GeneBitSet b1, GeneBitSet b2, GeneBitSet b3) intersection() - intersection of GeneBitSets (b1 | b2) ==> b3.
(package private) boolean	isItemInGeneBitSet(int item) isItemInGeneBitSet() - is an item (i.e.
(package private) void	listGeneBitSets(java.lang.String optMsg) listGeneBitSets() - popup a text window to list the user's gene sets.
(package private) static int	lookupGeneSetByName(java.lang.String userSetName, boolean exactFlag) lookupGeneSetByName() - lookup index of GeneBitSet in userBS[] database.
(package private) static GeneBitSet	lookupGeneSetObjByName(java.lang.String userSetName, boolean exactFlag) lookupGeneSetObjByName() - lookup GeneBitSet object by name in userBS[] DB.
(package private) static int	lookupOrMakeNewGeneBitSet(java.lang.String userSetName, GeneBitSet bs) lookupOrMakeNewGeneBitSet() - lookup or create new GeneBitSet in userBS[].
(package private) int	nextMID() nextMID() - get next mid in enumeration in [0:highMID] of this gene bit set
(package private) boolean	removeUserBS(java.lang.String userSetName) removeUserBS() - remove user GeneBitSet by name from userBS[] database Do NOT remove the gct.nSpecialGC bit sets at the front of the list.
(package private) void	resetEnumeration() resetEnumeration() - reset the gene bit set eumeration count to 0
(package private) boolean	rmvItem(int item) rmvItem() - remove Item (i.e.
(package private) boolean	setItem(int item) setItem() - set bit in gene bit set corresponding to item (i.e.
(package private) boolean	union(GeneBitSet b1, GeneBitSet b2, GeneBitSet b3) union() - compute union of GeneBitSets sets (b1 & b2) ==> b3.
(package private) void	updateListGeneBitSets() updateListGeneBitSets() - update existing "UserGeneSets" popup window
(package private) boolean	useGeneSetBS(GeneList mlDest, java.lang.String gbsName, java.lang.String userSetNameSrc) useGeneSetBS() - assign the specified GeneBitSet by name to GeneList ml.

Methods inherited from class java.lang.Object

, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait

Field Detail

mae

private static MAExplorer mae

link to global MAExplorer instance

ALL_BITS

private static final long ALL_BITS

0XFFFFFFFFFFFFFFFF is all 64-bits that is also 1's complement -1

MAX_USER_BS

static final int MAX_USER_BS

max # user assignable gene bit setst hat can be created

tempSetBL

private static GeneBitSet tempSetBL

temporary bit set used in set operations

userBS

static GeneBitSet[] userBS

[1:maxUserBS] user assignable gene bit sets. No set 0.

nUserBS

static int nUserBS

# user assignable gene bit sets in use

maxUserBS

static int maxUserBS

max # user assignable gene bit sets

cbsDbug

static boolean cbsDbug

flag: selective debugging enable

bsEnum

private int bsEnum

enumeration index 0 to length-1

bitWord

private int bitWord

64 bit long subset of bits from bitData

wIdx

private int wIdx

index of bitWord = bitData[wIdx]

bitIdx

private int bitIdx

index within a bitWord right to left

ml

GeneList ml

Associated Master GeneList if any, else null

assignedBSname

java.lang.String assignedBSname

if this was assigned from another bitSet

bName

java.lang.String bName

name of bit set

bitData

long[] bitData

list of nWords bit words allocated [0:maxSize-1] and active [0:highMID-1]

maxWords

int maxWords

max # 64-bit WORDS alloc'ed in bitData[]

maxItems

int maxItems

maximum # ITEMS in bit space allocated

highMID

int highMID

highest MID in this GeneBitSet

count

int count

# of ITEMS used in this GeneBitSet

Constructor Detail

GeneBitSet

GeneBitSet(MAExplorer maE,
           int maxItems,
           GeneList ml)

GeneBitSet() - constructor to create a GeneBitSet without a name.

Parameters:

maE - is instance of MAExplorer

maxItems - is the max size of a bit set

ml - is the GeneList instance to associate with the bitset

See Also:

allocGeneBitSet(int, java.lang.String, GeneList)

GeneBitSet

GeneBitSet(MAExplorer maE,
           int maxItems,
           java.lang.String bName,
           GeneList ml)

GeneBitSet() - constructor to create a named GeneBitSet.

Parameters:

maE - is instance of MAExplorer

maxItems - is the max size of a bit set

bName - is the bit set name

ml - is the GeneList instance to associate with the bitset

See Also:

allocGeneBitSet(int, java.lang.String, GeneList)

Method Detail

allocGeneBitSet

private void allocGeneBitSet(int maxItems,
                             java.lang.String bName,
                             GeneList ml)

allocGeneBitSet() - create named GeneBitSet by allocating bit set structures. We packing 64 items (i.e. genes) in a 64 bit (unsigned long) word.

Parameters:

maxItems - is the max size of a bit set

bName - is the bit set name

ml - is the GeneList instance to associate with the bitset

setItem

boolean setItem(int item)

setItem() - set bit in gene bit set corresponding to item (i.e. MID). It also extends the list length.

Parameters:

item - to be set

Returns:

true if set, false if any problems.

addItem

boolean addItem(int item)

addItem() - add Item (i.e. MID) to the gene bit set.

Parameters:

item - to be added

Returns:

true if added, false if any problems.

rmvItem

boolean rmvItem(int item)

rmvItem() - remove Item (i.e. MID) from gene bit set.

Parameters:

item - to be removed

Returns:

true if removed it, false if not found.

See Also:

findCountAndhighMID(GeneList)

isItemInGeneBitSet

boolean isItemInGeneBitSet(int item)

isItemInGeneBitSet() - is an item (i.e. MID) in the GeneBitSet.

Parameters:

maxItems - is the max size of a bit set

Returns:

true if item is in the GeneBitSet.

clearNull

boolean clearNull()

clearNull() - clear gene bit set and set entries to null. Return true if successful.

findCountAndhighMID

int findCountAndhighMID(GeneList ml)

findCountAndhighMID() - find count and highest MID in gene bit set BitData[]. If the mList[] is specified, then set mList[0:count-1] with genes from the midStaticCL.mList[] database.

Parameters:

ml - is the GeneList instance to associate with the bitset

Returns:

count

cvtBStoCL

boolean cvtBStoCL(GeneList ml)

cvtBStoCL() - convert GeneBitSet ml.bitSet to GeneList c1.mList[] (allocate data structures if needed).

Parameters:

ml - is the GeneList instance to convert.

Returns:

true if succeed.

See Also:

GeneList.clearMlist(), findCountAndhighMID(GeneList), nextMID(), resetEnumeration()

copyBStoCL

boolean copyBStoCL(GeneList c1Dst,
                   GeneBitSet b2Src)

copyBStoCL() - copy GeneBitSet b2Src to GeneList c1Dst.mList[]. It also copies b2Src to c1Dst.bitSet. DO NOT rename c1Dst.

Parameters:

c1Dst - is the GeneList destination operand

b2Src - is the GeneBitSet source operand

Returns:

true if succeed.

See Also:

copyBStoBS(GeneBitSet, GeneBitSet), cvtBStoCL(GeneList)

copyCLtoBS

static boolean copyCLtoBS(GeneBitSet b1Dst,
                          GeneList c2Src,
                          boolean useCopyBitArrayFlag)

copyCLtoBS() - copy GeneList c2Src to GeneBitSet b1Dst. Do Not rename b1Dst.

Parameters:

b1Dst - is the GeneBitSet destination operand

c2Src - is the GeneList source operand

useCopyBitArrayFlag - copy bit array data

Returns:

true if succeed.

See Also:

clearNull(), addItem(int)

copyBStoBS

static boolean copyBStoBS(GeneBitSet b1Dst,
                          GeneBitSet b2Src)

copyBStoBS() - copy GeneBitSet b2Src to GeneBitSet b1Dst. Do NOT rename b1Dst.

Parameters:

b1Dst - is the GeneBitSet destination operand

b2Src - is the GeneBitSet source operand

Returns:

true if succeed.

resetEnumeration

void resetEnumeration()

resetEnumeration() - reset the gene bit set eumeration count to 0

nextMID

int nextMID()

nextMID() - get next mid in enumeration in [0:highMID] of this gene bit set

Returns:

mid if succeed, else -1 if none (at end of the list).

union

boolean union(GeneBitSet b1,
              GeneBitSet b2,
              GeneBitSet b3)

union() - compute union of GeneBitSets sets (b1 & b2) ==> b3. Then, copy the results into b3. Note: b1 or b2 can be the same as b3. It will copy the result AFTER it has been computed.

Parameters:

b1 - is the GeneBitSet first source operand

b2 - is the GeneBitSet second source operand

b3 - is the GeneBitSet destination operand

Returns:

true if succeed.

See Also:

findCountAndhighMID(GeneList)

intersection

boolean intersection(GeneBitSet b1,
                     GeneBitSet b2,
                     GeneBitSet b3)

intersection() - intersection of GeneBitSets (b1 | b2) ==> b3. Then, copy the results into b3. Note: b1 or b2 can be the same as b3. It will copy the result AFTER it has been computed.

Parameters:

b1 - is the GeneBitSet first source operand

b2 - is the GeneBitSet second source operand

b3 - is the GeneBitSet destination operand

Returns:

true if succeed.

See Also:

findCountAndhighMID(GeneList)

difference

boolean difference(GeneBitSet b1,
                   GeneBitSet b2,
                   GeneBitSet b3)

difference() - difference of GeneBitSets (b2 - b1)==> b3. That is, subtract items in b1 that are in b2 but DON'T subtract items in b1 that are not in b2 - this is assymetric! The results are copied into b3. Note: b1 or b2 can be the same as b3. It will copy the result AFTER it has been computed.

Parameters:

b1 - is the GeneBitSet first source operand

b2 - is the GeneBitSet second source operand

b3 - is the GeneBitSet destination operand

Returns:

true if succeed.

See Also:

findCountAndhighMID(GeneList)

listGeneBitSets

void listGeneBitSets(java.lang.String optMsg)

listGeneBitSets() - popup a text window to list the user's gene sets.

Parameters:

optMsg - is optional message to add to front of the report.

See Also:

ShowStringPopup, getListGeneBitSetsStr()

updateListGeneBitSets

void updateListGeneBitSets()

updateListGeneBitSets() - update existing "UserGeneSets" popup window

See Also:

PopupRegistry.lookupShowStringPopupInstance(java.lang.String), ShowStringPopup.updateText(java.lang.String), getListGeneBitSetsStr()

getListGeneBitSetsStr

java.lang.String getListGeneBitSetsStr()

getListGeneBitSetsStr() - convert list of active GeneBitSets userBS[] to summary print string.

Returns:

print string report

getGBSnames

java.lang.String[] getGBSnames()

getGBSnames() - return String array of active Gene Bit Set names.

Returns:

list of gene bit set names

lookupGeneSetObjByName

static GeneBitSet lookupGeneSetObjByName(java.lang.String userSetName,
                                         boolean exactFlag)

lookupGeneSetObjByName() - lookup GeneBitSet object by name in userBS[] DB. If it is a numeric string, then return the object, else search the bName's for a match. Do matching ignoring case.

Parameters:

userSetName - of gene bit set

exactFlag - to do an equal() exact match else use startsWith()

Returns:

the userBS[1:maxUserBS] object if found, null if not found

lookupGeneSetByName

static int lookupGeneSetByName(java.lang.String userSetName,
                               boolean exactFlag)

lookupGeneSetByName() - lookup index of GeneBitSet in userBS[] database. If it is a numeric string, then return the number, else search the bName's for a match. Do matching ignoring case.

Parameters:

userSetName - of gene bit set

exactFlag - to do an equal() exact match else use startsWith()

Returns:

the index CBS in userBS[1:maxUserBS] if found, -1 if not found

lookupOrMakeNewGeneBitSet

static int lookupOrMakeNewGeneBitSet(java.lang.String userSetName,
                                     GeneBitSet bs)

lookupOrMakeNewGeneBitSet() - lookup or create new GeneBitSet in userBS[].

Parameters:

userSetName - is the name of the existing or new gene bit set

bs - is the optional GeneBitSet to copy or use

Returns:

index of userBS[] entry, else -1 if fail.

See Also:

Util.showMsg(java.lang.String), copyBStoBS(GeneBitSet, GeneBitSet), lookupGeneSetByName(java.lang.String, boolean)

assignCLtoUserBS

int assignCLtoUserBS(java.lang.String userSetName,
                     GeneList ml)

assignCLtoUserBS() - assign GeneList ml to new user GeneBitSet userBS[] database. Fail if the GeneBitSet does not exist for that GeneList. Note: when you create a GeneList you ALWAYS make a GeneBitSet but not always the other way around. If the userSetName NEQ ml.cName, then we are creating a new bit set.

Parameters:

userSetName - is the name of the existing or new gene bit set

ml - is the optional GeneList to assign

Returns:

the new bit set index for userBS[idx] if successful, else -1.

See Also:

Util.showMsg(java.lang.String), copyBStoBS(GeneBitSet, GeneBitSet), lookupOrMakeNewGeneBitSet(java.lang.String, GeneBitSet)

removeUserBS

boolean removeUserBS(java.lang.String userSetName)

removeUserBS() - remove user GeneBitSet by name from userBS[] database Do NOT remove the gct.nSpecialGC bit sets at the front of the list.

Parameters:

userSetName - is the name of the existing or new gene bit set

Returns:

true if succeed

See Also:

Util.showMsg(java.lang.String), lookupGeneSetByName(java.lang.String, boolean)

useGeneSetBS

boolean useGeneSetBS(GeneList mlDest,
                     java.lang.String gbsName,
                     java.lang.String userSetNameSrc)

useGeneSetBS() - assign the specified GeneBitSet by name to GeneList ml.

Parameters:

ml - is the GeneList destination operand

gbsName - is the print msg of destination bit set

userSetNameSrc - is the name of the source bit set

Returns:

true if succeed

See Also:

Util.showMsg(java.lang.String), copyBStoBS(GeneBitSet, GeneBitSet), lookupGeneSetByName(java.lang.String, boolean), union(GeneBitSet, GeneBitSet, GeneBitSet), intersection(GeneBitSet, GeneBitSet, GeneBitSet), difference(GeneBitSet, GeneBitSet, GeneBitSet), copyBStoCL(GeneList, GeneBitSet)

assignCSbinOprToUserBS

boolean assignCSbinOprToUserBS(java.lang.String bsName1,
                               java.lang.String bsName2,
                               java.lang.String userSetName,
                               java.lang.String opr)

assignCSbinOprToUserBS() - assign GeneBitSet binary Boolean opr to new user GeneBitSet. The value of opr is either "union", "intersection" or "difference". If there is a GeneList associated with the BitSet bs3 then update the cs3.mList[0:length-1].

Parameters:

bsName1 - is the name of the first bit setsource operand

bsName2 - is the name of the second bit set source operand

userSetNameSrc - is the name of the destination bit set operand

opr - is the name of the operator: "union", "intersection" or "difference"

Returns:

true if succeed

See Also:

Util.showMsg(java.lang.String), lookupGeneSetByName(java.lang.String, boolean), lookupOrMakeNewGeneBitSet(java.lang.String, GeneBitSet)

cleanup

void cleanup()

cleanup() - cleanup global static allocated variables in this class. If statics are added later to this class, then set them to null here.