de.lmu.ifi.dbs.elki.database.ids

Class DBIDUtil

java.lang.Object

de.lmu.ifi.dbs.elki.database.ids.DBIDUtil

public final class DBIDUtil
extends java.lang.Object

DBID Utility functions.

Since:

0.4.0

Author:

Erich Schubert

Field Summary

Fields

Modifier and Type	Field and Description
static EmptyDBIDs	EMPTYDBIDS Final, global copy of empty DBIDs.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	DBIDUtil() Static - no public constructor.

Method Summary

Modifier and Type	Method and Description
static int	asInteger(DBIDRef id) Export a DBID as int.
static DBIDRange	assertRange(DBIDs ids) Assert that the presented ids constitute a continuous DBIDRange.
static int	compare(DBIDRef id1, DBIDRef id2) Compare two DBIDs.
static void	deallocateDBIDRange(DBIDRange range) Deallocate a static DBID range.
static void	deallocateSingleDBID(DBID id) Return a single DBID for reuse.
static DBID	deref(DBIDRef ref) Dereference a DBID reference.
static ModifiableDBIDs	difference(DBIDs ids1, DBIDs ids2) Returns the difference of the two specified collection of IDs.
static ArrayDBIDs	ensureArray(DBIDs ids) Ensure that the given DBIDs are array-indexable.
static ModifiableDBIDs	ensureModifiable(DBIDs ids) Ensure modifiable.
static SetDBIDs	ensureSet(DBIDs ids) Ensure that the given DBIDs support fast "contains" operations.
static boolean	equal(DBIDRef id1, DBIDRef id2) Test two DBIDs for equality.
static DBID	generateSingleDBID() Generate a single DBID.
static DBIDRange	generateStaticDBIDRange(int size) Generate a static DBID range.
static ByteBufferSerializer<DBID>	getDBIDSerializer() Get a serializer for DBIDs.
static ByteBufferSerializer<DBID>	getDBIDSerializerStatic() Get a serializer for DBIDs with static size.
static DBID	importInteger(int id) Import and integer as DBID.
private static ModifiableDBIDs	internalIntersection(DBIDs first, DBIDs second) Compute the set intersection of two sets.
private static int	internalIntersectionSize(DBIDs first, DBIDs second) Compute the set intersection size of two sets.
static ModifiableDBIDs	intersection(DBIDs first, DBIDs second) Compute the set intersection of two sets.
static int	intersectionSize(DBIDs first, DBIDs second) Compute the set intersection size of two sets.
static DBIDRef	invalid() Get the invalid special ID.
static StaticDBIDs	makeUnmodifiable(DBIDs existing) Wrap an existing DBIDs collection to be unmodifiable.
static ArrayModifiableDBIDs	newArray() Make a new (modifiable) array of DBIDs.
static ArrayModifiableDBIDs	newArray(DBIDs existing) Make a new (modifiable) array of DBIDs.
static ArrayModifiableDBIDs	newArray(int size) Make a new (modifiable) array of DBIDs.
static ModifiableDoubleDBIDList	newDistanceDBIDList() Create a modifiable list to store distance-DBID pairs.
static ModifiableDoubleDBIDList	newDistanceDBIDList(int size) Create a modifiable list to store distance-DBID pairs.
static HashSetModifiableDBIDs	newHashSet() Make a new (modifiable) hash set of DBIDs.
static HashSetModifiableDBIDs	newHashSet(DBIDs existing) Make a new (modifiable) hash set of DBIDs.
static HashSetModifiableDBIDs	newHashSet(int size) Make a new (modifiable) hash set of DBIDs.
static KNNHeap	newHeap(int k) Create an appropriate heap for the distance type.
static KNNHeap	newHeap(KNNList exist) Build a new heap from a given list.
static DBIDPair	newPair(DBIDRef id1, DBIDRef id2) Make a DBID pair.
static DoubleDBIDPair	newPair(double val, DBIDRef id) Make a DoubleDBIDPair.
static DBIDVar	newVar() Make a new DBID variable.
static DBIDVar	newVar(DBIDRef val) Make a new DBID variable.
static DBIDs	randomSample(DBIDs ids, double rate, java.util.Random random) Produce a random sample of the given DBIDs.
static DBIDs	randomSample(DBIDs ids, double rate, RandomFactory random) Produce a random sample of the given DBIDs.
static ModifiableDBIDs	randomSample(DBIDs source, int k, int seed) Produce a random sample of the given DBIDs.
static ModifiableDBIDs	randomSample(DBIDs source, int k, java.lang.Long seed) Produce a random sample of the given DBIDs.
static ModifiableDBIDs	randomSample(DBIDs source, int k, java.util.Random random) Produce a random sample of the given DBIDs.
static ModifiableDBIDs	randomSample(DBIDs source, int k, RandomFactory rnd) Produce a random sample of the given DBIDs.
static DBIDVar	randomSample(DBIDs ids, java.util.Random random) Draw a single random sample.
static DBIDVar	randomSample(DBIDs ids, RandomFactory random) Draw a single random sample.
static ModifiableDBIDs	randomSampleExcept(DBIDs source, DBIDRef except, int k, java.util.Random random) Produce a random sample of the given DBIDs.
static ModifiableDBIDs	randomSampleExcept(DBIDs source, DBIDRef except, int k, RandomFactory rnd) Produce a random sample of the given DBIDs.
static void	randomShuffle(ArrayModifiableDBIDs ids, java.util.Random random) Produce a random shuffling of the given DBID array.
static void	randomShuffle(ArrayModifiableDBIDs ids, RandomFactory rnd) Produce a random shuffling of the given DBID array.
static void	randomShuffle(ArrayModifiableDBIDs ids, java.util.Random random, int limit) Produce a random shuffling of the given DBID array.
static ArrayDBIDs[]	randomSplit(DBIDs oids, int p, java.util.Random random) Randomly split IDs into p partitions of almost-equal size.
static ArrayDBIDs[]	randomSplit(DBIDs ids, int p, RandomFactory rnd) Randomly split IDs into p partitions of almost-equal size.
static void	symmetricIntersection(DBIDs first, DBIDs second, HashSetModifiableDBIDs firstonly, HashSetModifiableDBIDs intersection, HashSetModifiableDBIDs secondonly) Compute the set symmetric intersection of two sets.
static java.lang.String	toString(DBIDRef id) Format a DBID as string.
static java.lang.String	toString(DBIDs ids) Format a DBID as string.
static ModifiableDBIDs	union(DBIDs ids1, DBIDs ids2) Returns the union of the two specified collection of IDs.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTYDBIDS

public static final EmptyDBIDs EMPTYDBIDS

Final, global copy of empty DBIDs.

Constructor Detail

DBIDUtil

private DBIDUtil()

Static - no public constructor.

Method Detail

invalid

public static DBIDRef invalid()

Get the invalid special ID.

Returns:

invalid ID value

importInteger

public static DBID importInteger(int id)

Import and integer as DBID.

Note: this may not be possible for some factories!

Parameters:

id - Integer ID to import

Returns:

DBID

asInteger

public static int asInteger(DBIDRef id)

Export a DBID as int.

Note: this may not be possible for some factories!

Parameters:

id - DBID to export

Returns:

integer value

compare

public static int compare(DBIDRef id1,
                          DBIDRef id2)

Compare two DBIDs.

Parameters:

id1 - First ID

id2 - Second ID

Returns:

Comparison result

equal

public static boolean equal(DBIDRef id1,
                            DBIDRef id2)

Test two DBIDs for equality.

Parameters:

id1 - First ID

id2 - Second ID

Returns:

Comparison result

deref

public static DBID deref(DBIDRef ref)

Dereference a DBID reference.

Parameters:

ref - DBID reference

Returns:

DBID

toString

public static java.lang.String toString(DBIDRef id)

Format a DBID as string.

Parameters:

id - DBID

Returns:

String representation

toString

public static java.lang.String toString(DBIDs ids)

Format a DBID as string.

Parameters:

ids - DBIDs

Returns:

String representation

getDBIDSerializer

public static ByteBufferSerializer<DBID> getDBIDSerializer()

Get a serializer for DBIDs.

Returns:

DBID serializer

getDBIDSerializerStatic

public static ByteBufferSerializer<DBID> getDBIDSerializerStatic()

Get a serializer for DBIDs with static size.

Returns:

DBID serializer

generateSingleDBID

public static DBID generateSingleDBID()

Generate a single DBID.

Returns:

A single DBID

deallocateSingleDBID

public static void deallocateSingleDBID(DBID id)

Return a single DBID for reuse.

Parameters:

id - DBID to deallocate

generateStaticDBIDRange

public static DBIDRange generateStaticDBIDRange(int size)

Generate a static DBID range.

Parameters:

size - Requested size

Returns:

DBID range

deallocateDBIDRange

public static void deallocateDBIDRange(DBIDRange range)

Deallocate a static DBID range.

Parameters:

range - Range to deallocate

newVar

public static DBIDVar newVar(DBIDRef val)

Make a new DBID variable.

Parameters:

val - Initial value.

Returns:

Variable

newVar

public static DBIDVar newVar()

Make a new DBID variable.

Returns:

Variable

newArray

public static ArrayModifiableDBIDs newArray()

Make a new (modifiable) array of DBIDs.

Returns:

New array

newHashSet

public static HashSetModifiableDBIDs newHashSet()

Make a new (modifiable) hash set of DBIDs.

Returns:

New hash set

newArray

public static ArrayModifiableDBIDs newArray(int size)

Make a new (modifiable) array of DBIDs.

Parameters:

size - Size hint

Returns:

New array

newHashSet

public static HashSetModifiableDBIDs newHashSet(int size)

Make a new (modifiable) hash set of DBIDs.

Parameters:

size - Size hint

Returns:

New hash set

newArray

public static ArrayModifiableDBIDs newArray(DBIDs existing)

Make a new (modifiable) array of DBIDs.

Parameters:

existing - Existing DBIDs

Returns:

New array

newHashSet

public static HashSetModifiableDBIDs newHashSet(DBIDs existing)

Make a new (modifiable) hash set of DBIDs.

Parameters:

existing - Existing DBIDs

Returns:

New hash set

intersection

public static ModifiableDBIDs intersection(DBIDs first,
                                           DBIDs second)

Compute the set intersection of two sets.

Parameters:

first - First set

second - Second set

Returns:

intersection

internalIntersection

private static ModifiableDBIDs internalIntersection(DBIDs first,
                                                    DBIDs second)

Compute the set intersection of two sets.

Parameters:

first - First set

second - Second set

Returns:

result.

intersectionSize

public static int intersectionSize(DBIDs first,
                                   DBIDs second)

Compute the set intersection size of two sets.

Parameters:

first - First set

second - Second set

Returns:

size

internalIntersectionSize

private static int internalIntersectionSize(DBIDs first,
                                            DBIDs second)

Compute the set intersection size of two sets.

Parameters:

first - First set

second - Second set

Returns:

size

symmetricIntersection

public static void symmetricIntersection(DBIDs first,
                                         DBIDs second,
                                         HashSetModifiableDBIDs firstonly,
                                         HashSetModifiableDBIDs intersection,
                                         HashSetModifiableDBIDs secondonly)

Compute the set symmetric intersection of two sets.

Parameters:

first - First set

second - Second set

firstonly - OUTPUT: elements only in first. MUST BE EMPTY

intersection - OUTPUT: elements in intersection. MUST BE EMPTY

secondonly - OUTPUT: elements only in second. MUST BE EMPTY

union

public static ModifiableDBIDs union(DBIDs ids1,
                                    DBIDs ids2)

Returns the union of the two specified collection of IDs.

Parameters:

ids1 - the first collection

ids2 - the second collection

Returns:

the union of ids1 and ids2 without duplicates

difference

public static ModifiableDBIDs difference(DBIDs ids1,
                                         DBIDs ids2)

Returns the difference of the two specified collection of IDs.

Parameters:

ids1 - the first collection

ids2 - the second collection

Returns:

the difference of ids1 minus ids2

makeUnmodifiable

public static StaticDBIDs makeUnmodifiable(DBIDs existing)

Wrap an existing DBIDs collection to be unmodifiable.

Parameters:

existing - Existing collection

Returns:

Unmodifiable collection

ensureArray

public static ArrayDBIDs ensureArray(DBIDs ids)

Ensure that the given DBIDs are array-indexable.

Parameters:

ids - IDs

Returns:

Array DBIDs.

ensureSet

public static SetDBIDs ensureSet(DBIDs ids)

Ensure that the given DBIDs support fast "contains" operations.

Parameters:

ids - IDs

Returns:

Set DBIDs.

ensureModifiable

public static ModifiableDBIDs ensureModifiable(DBIDs ids)

Ensure modifiable.

Parameters:

ids - IDs

Returns:

Modifiable DBIDs.

newPair

public static DBIDPair newPair(DBIDRef id1,
                               DBIDRef id2)

Make a DBID pair.

Parameters:

id1 - first ID

id2 - second ID

Returns:

DBID pair

newPair

public static DoubleDBIDPair newPair(double val,
                                     DBIDRef id)

Make a DoubleDBIDPair.

Parameters:

val - double value

id - ID

Returns:

new pair

newHeap

public static KNNHeap newHeap(int k)

Create an appropriate heap for the distance type. This will use a double heap if appropriate.

Parameters:

k - K value

Returns:

New heap of size k, appropriate for this distance type.

newHeap

public static KNNHeap newHeap(KNNList exist)

Build a new heap from a given list.

Parameters:

exist - Existing result

Returns:

New heap

randomShuffle

public static void randomShuffle(ArrayModifiableDBIDs ids,
                                 RandomFactory rnd)

Produce a random shuffling of the given DBID array.

Parameters:

ids - Original DBIDs, no duplicates allowed

rnd - Random generator

randomShuffle

public static void randomShuffle(ArrayModifiableDBIDs ids,
                                 java.util.Random random)

Produce a random shuffling of the given DBID array.

Parameters:

ids - Original DBIDs, no duplicates allowed

random - Random generator

randomShuffle

public static void randomShuffle(ArrayModifiableDBIDs ids,
                                 java.util.Random random,
                                 int limit)

Produce a random shuffling of the given DBID array. Only the first limit elements will be fully randomized, but the remaining objects will also be changed.

Parameters:

ids - Original DBIDs, no duplicates allowed

random - Random generator

limit - Shuffling limit.

randomSample

public static ModifiableDBIDs randomSample(DBIDs source,
                                           int k,
                                           int seed)

Produce a random sample of the given DBIDs.

Parameters:

source - Original DBIDs, no duplicates allowed

k - k Parameter

seed - Random generator seed

Returns:

new DBIDs

randomSample

public static ModifiableDBIDs randomSample(DBIDs source,
                                           int k,
                                           java.lang.Long seed)

Produce a random sample of the given DBIDs.

Parameters:

source - Original DBIDs, no duplicates allowed

k - k Parameter

seed - Random generator seed

Returns:

new DBIDs

randomSample

public static ModifiableDBIDs randomSample(DBIDs source,
                                           int k,
                                           RandomFactory rnd)

Produce a random sample of the given DBIDs.

Parameters:

source - Original DBIDs, no duplicates allowed

k - k Parameter

rnd - Random generator

Returns:

new DBIDs

randomSampleExcept

public static ModifiableDBIDs randomSampleExcept(DBIDs source,
                                                 DBIDRef except,
                                                 int k,
                                                 RandomFactory rnd)

Produce a random sample of the given DBIDs.

Parameters:

source - Original DBIDs, no duplicates allowed

except - Excluded object

k - k Parameter

rnd - Random generator

Returns:

new DBIDs

randomSample

public static ModifiableDBIDs randomSample(DBIDs source,
                                           int k,
                                           java.util.Random random)

Produce a random sample of the given DBIDs.

Parameters:

source - Original DBIDs, no duplicates allowed

k - k Parameter

random - Random generator

Returns:

new DBIDs

randomSampleExcept

public static ModifiableDBIDs randomSampleExcept(DBIDs source,
                                                 DBIDRef except,
                                                 int k,
                                                 java.util.Random random)

Produce a random sample of the given DBIDs.

Parameters:

source - Original DBIDs, no duplicates allowed

except - Excluded object

k - k Parameter

random - Random generator

Returns:

new DBIDs

randomSample

public static DBIDs randomSample(DBIDs ids,
                                 double rate,
                                 RandomFactory random)

Produce a random sample of the given DBIDs.

Parameters:

ids - Original ids, no duplicates allowed

rate - Sampling rate

random - Random generator

Returns:

Sample

randomSample

public static DBIDs randomSample(DBIDs ids,
                                 double rate,
                                 java.util.Random random)

Produce a random sample of the given DBIDs.

• values less or equal 0 mean no sampling.
• values larger than 0, but at most 1, are relative rates.
• values larger than 1 are supposed to be integer counts.

Parameters:

ids - Original ids, no duplicates allowed

rate - Sampling rate

random - Random generator

Returns:

Sample

randomSample

public static DBIDVar randomSample(DBIDs ids,
                                   java.util.Random random)

Draw a single random sample.

Parameters:

ids - IDs to draw from

random - Random value

Returns:

Random ID

randomSample

public static DBIDVar randomSample(DBIDs ids,
                                   RandomFactory random)

Draw a single random sample.

Parameters:

ids - IDs to draw from

random - Random value

Returns:

Random ID

randomSplit

public static ArrayDBIDs[] randomSplit(DBIDs ids,
                                       int p,
                                       RandomFactory rnd)

Randomly split IDs into p partitions of almost-equal size.

Parameters:

ids - Original DBIDs

p - Desired number of partitions.

rnd - Random generator

randomSplit

public static ArrayDBIDs[] randomSplit(DBIDs oids,
                                       int p,
                                       java.util.Random random)

Randomly split IDs into p partitions of almost-equal size.

Parameters:

oids - Original DBIDs

p - Desired number of partitions.

random - Random generator

newDistanceDBIDList

public static ModifiableDoubleDBIDList newDistanceDBIDList(int size)

Create a modifiable list to store distance-DBID pairs.

Parameters:

size - Estimated upper list size

Returns:

Empty list

newDistanceDBIDList

public static ModifiableDoubleDBIDList newDistanceDBIDList()

Create a modifiable list to store distance-DBID pairs.

Returns:

Empty list

assertRange

public static DBIDRange assertRange(DBIDs ids)

Assert that the presented ids constitute a continuous DBIDRange.

Parameters:

ids - ID range.

Returns:

DBID range.

Throws:

AbortException