API

Targeting Flags

The TargetingFlags class is relevant to SDSS carton-to-bit version 1 (SDSSC2BV).

class sdss_semaphore.targeting.TargetingFlags(array: Optional[Union[numpy.ndarray, Iterable[Iterable[int]], Iterable[bytearray], Iterable[sdss_semaphore.BaseFlags]]] = None)

Bases: sdss_semaphore.targeting.BaseTargetingFlags

Communicating with SDSS-V targeting flags.

are_all_bits_set(*bits) → numpy.array

Return an N-length boolean array indicating whether all of the given bits are set for each item.

Parameters

bits – The zero-indexed bit positions to check.

Returns

A boolean array indicating whether all of the given bits are set for each item.

are_any_bits_set(*bits) → numpy.array

Return an N-length boolean array indicating whether any of the given bits are set for each item.

Parameters

bits – The zero-indexed bit positions to check.

Returns

A boolean array indicating whether any of the given bits are set for each item.

as_boolean_array() → numpy.ndarray

Return a (N, F) shaped big-endian boolean array indicating whether each bit is set for each item, where the input data array has shape (N, B) and F = B * n_bits is the maximum possible number of flags.

clear_bit(index, bit)

Clear the given bit for the given index.

Parameters

• index – The item index.

• bit – The zero-indexed bit position to clear.

count(skip_empty: bool = False) → dict

Return a dictionary containing the number of items assigned by each carton label.

Parameters

skip_empty – [optional] Skip cartons with no items assigned to them.

Returns

A dictionary with carton labels as keys and item counts as values.

count_by_attribute(attribute, skip_empty: bool = False) → dict

Return a dictionary of the items assigned with flags of a given attribute.

The keys are the bit positions of each flag, or if an attribuet is given, then this will be the attribute of the flags to count. The values are the number of items assigned to flags with that attribute.

Parameters

• attribute – The flag attribute to count by.

• skip_empty – [optional] Skip flags with no items assigned to them.

get_bits_with_attribute(key, value) → List[int]

Return the bit positions for all items with the given attribute.

Parameters

• key – The attribute key.

• value – The attribute value.

Returns

A list of bit positions.

in_alt_name(alt_name: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to any cartons with the given alternative name.

Parameters

alt_name – The alternative flag name.

in_alt_program(alt_program: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to any cartons with the given alternative program.

Parameters

alt_program – The alternative program name.

in_carton_label(label: str) → numpy.array

Return a N-length boolean array indicating whether the items are assigned to the carton with the given label.

Parameters

label – The carton label.

in_carton_name(name: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to a carton with the given name.

Parameters

name – The flag name.

in_carton_pk(carton_pk: int) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to the carton with the given primary key.

Parameters

carton_pk – The carton primary key.

in_mapper(mapper: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to any cartons with the given mapper.

Parameters

mapper – The mapper name.

in_program(program: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to any cartons with the given program.

Parameters

program – The program name.

is_attribute_set(key, value) → numpy.array

Return a N-length boolean array indicating whether the item has any flag with the given attribute.

Parameters

• key – The attribute key.

• value – The attribute value.

Returns

A boolean array indicating whether the item has any flag with the given attribute.

is_bit_set(bit) → numpy.array

Return an N-length boolean array indicating whether the given bit is set for each item.

Parameters

bit – The zero-indexed bit position to check.

Returns

A boolean array indicating whether the given bit is set for each item.

set_bit(index, bit)

Set the given bit for the given item.

Parameters

• index – The item index.

• bit – The zero-indexed bit position to set.

set_bit_by_carton_pk(index: int, carton_pk: int)

Set the bit for the carton with the given primary key.

Parameters

• index – The index of the item to set.

• carton_pk – The carton primary key.

shrink()

Shrink the data array to the maximum required shape based on the highest bit set.

toggle_bit(index, bit)

Toggle the given bit for the given index.

Parameters

• index – The item index.

• bit – The zero-indexed bit position to clear.

property all_alt_names

Return a list of all alternative carton names.

property all_alt_programs

Return a list of all alternative carton programs.

property all_mappers

Return a tuple of all mappers.

property all_names

Return a list of all carton names.

property all_programs

Return a list of all programs.

property bit_position_from_carton_pk

Return a dictionary with carton primary keys as keys, and bit positions as values.

This is a helper method for efficiency creating large TargetingFlags objects.

property bits_set

A generator that yields a tuple of bits set for each item.

If you want a more efficient lookup, you can use:

items, bits = np.where(flags.as_boolean_array())

property flags_set

A generator that yields all set flags.

This can be a hugely expensive query if you have large number of items (e.g., stars).

Base Targeting Flags

The BaseTargetingFlags class provides utilities for targeting flags which do not depend on a specific version of the SDSS carton-to-bit mapping.

class sdss_semaphore.targeting.BaseTargetingFlags(array: Optional[Union[numpy.ndarray, Iterable[Iterable[int]], Iterable[bytearray], Iterable[sdss_semaphore.BaseFlags]]] = None)

Bases: sdss_semaphore.BaseFlags

A base class for communicating SDSS-V targeting information with flags.

are_all_bits_set(*bits) → numpy.array

Return an N-length boolean array indicating whether all of the given bits are set for each item.

Parameters

bits – The zero-indexed bit positions to check.

Returns

A boolean array indicating whether all of the given bits are set for each item.

are_any_bits_set(*bits) → numpy.array

Return an N-length boolean array indicating whether any of the given bits are set for each item.

Parameters

bits – The zero-indexed bit positions to check.

Returns

A boolean array indicating whether any of the given bits are set for each item.

as_boolean_array() → numpy.ndarray

Return a (N, F) shaped big-endian boolean array indicating whether each bit is set for each item, where the input data array has shape (N, B) and F = B * n_bits is the maximum possible number of flags.

clear_bit(index, bit)

Clear the given bit for the given index.

Parameters

• index – The item index.

• bit – The zero-indexed bit position to clear.

count(skip_empty: bool = False) → dict

Return a dictionary containing the number of items assigned by each carton label.

Parameters

skip_empty – [optional] Skip cartons with no items assigned to them.

Returns

A dictionary with carton labels as keys and item counts as values.

count_by_attribute(attribute, skip_empty: bool = False) → dict

Return a dictionary of the items assigned with flags of a given attribute.

The keys are the bit positions of each flag, or if an attribuet is given, then this will be the attribute of the flags to count. The values are the number of items assigned to flags with that attribute.

Parameters

• attribute – The flag attribute to count by.

• skip_empty – [optional] Skip flags with no items assigned to them.

get_bits_with_attribute(key, value) → List[int]

Return the bit positions for all items with the given attribute.

Parameters

• key – The attribute key.

• value – The attribute value.

Returns

A list of bit positions.

in_alt_name(alt_name: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to any cartons with the given alternative name.

Parameters

alt_name – The alternative flag name.

in_alt_program(alt_program: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to any cartons with the given alternative program.

Parameters

alt_program – The alternative program name.

in_carton_label(label: str) → numpy.array

Return a N-length boolean array indicating whether the items are assigned to the carton with the given label.

Parameters

label – The carton label.

in_carton_name(name: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to a carton with the given name.

Parameters

name – The flag name.

in_carton_pk(carton_pk: int) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to the carton with the given primary key.

Parameters

carton_pk – The carton primary key.

in_mapper(mapper: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to any cartons with the given mapper.

Parameters

mapper – The mapper name.

in_program(program: str) → numpy.array

Return an N-length boolean array indicating whether the items are assigned to any cartons with the given program.

Parameters

program – The program name.

is_attribute_set(key, value) → numpy.array

Return a N-length boolean array indicating whether the item has any flag with the given attribute.

Parameters

• key – The attribute key.

• value – The attribute value.

Returns

A boolean array indicating whether the item has any flag with the given attribute.

is_bit_set(bit) → numpy.array

Return an N-length boolean array indicating whether the given bit is set for each item.

Parameters

bit – The zero-indexed bit position to check.

Returns

A boolean array indicating whether the given bit is set for each item.

set_bit(index, bit)

Set the given bit for the given item.

Parameters

• index – The item index.

• bit – The zero-indexed bit position to set.

set_bit_by_carton_pk(index: int, carton_pk: int)

Set the bit for the carton with the given primary key.

Parameters

• index – The index of the item to set.

• carton_pk – The carton primary key.

shrink()

Shrink the data array to the maximum required shape based on the highest bit set.

toggle_bit(index, bit)

Toggle the given bit for the given index.

Parameters

• index – The item index.

• bit – The zero-indexed bit position to clear.

property all_alt_names

Return a list of all alternative carton names.

property all_alt_programs

Return a list of all alternative carton programs.

property all_mappers

Return a tuple of all mappers.

property all_names

Return a list of all carton names.

property all_programs

Return a list of all programs.

property bit_position_from_carton_pk

Return a dictionary with carton primary keys as keys, and bit positions as values.

This is a helper method for efficiency creating large TargetingFlags objects.

property bits_set

A generator that yields a tuple of bits set for each item.

If you want a more efficient lookup, you can use:

items, bits = np.where(flags.as_boolean_array())

property flags_set

A generator that yields all set flags.

This can be a hugely expensive query if you have large number of items (e.g., stars).

Base Flags

The BaseFlags class provides functionality for any kind of flagging system, irrespective of the bit-attribute mapping.

class sdss_semaphore.BaseFlags(array: Optional[Union[numpy.ndarray, Iterable[Iterable[int]], Iterable[bytearray], Iterable[sdss_semaphore.BaseFlags]]] = None)

Bases: object

A base class for communicating with flags.

are_all_bits_set(*bits) → numpy.array

Return an N-length boolean array indicating whether all of the given bits are set for each item.

Parameters

bits – The zero-indexed bit positions to check.

Returns

A boolean array indicating whether all of the given bits are set for each item.

are_any_bits_set(*bits) → numpy.array

Return an N-length boolean array indicating whether any of the given bits are set for each item.

Parameters

bits – The zero-indexed bit positions to check.

Returns

A boolean array indicating whether any of the given bits are set for each item.

as_boolean_array() → numpy.ndarray

Return a (N, F) shaped big-endian boolean array indicating whether each bit is set for each item, where the input data array has shape (N, B) and F = B * n_bits is the maximum possible number of flags.

clear_bit(index, bit)

Clear the given bit for the given index.

Parameters

• index – The item index.

• bit – The zero-indexed bit position to clear.

count(skip_empty: bool = False) → dict

Return a dictionary containing the number of items assigned with each flag.

Parameters

skip_empty – [optional] Skip flags with no items assigned to them.

count_by_attribute(attribute, skip_empty: bool = False) → dict

Return a dictionary of the items assigned with flags of a given attribute.

The keys are the bit positions of each flag, or if an attribuet is given, then this will be the attribute of the flags to count. The values are the number of items assigned to flags with that attribute.

Parameters

• attribute – The flag attribute to count by.

• skip_empty – [optional] Skip flags with no items assigned to them.

get_bits_with_attribute(key, value) → List[int]

Return the bit positions for all items with the given attribute.

Parameters

• key – The attribute key.

• value – The attribute value.

Returns

A list of bit positions.

is_attribute_set(key, value) → numpy.array

Return a N-length boolean array indicating whether the item has any flag with the given attribute.

Parameters

• key – The attribute key.

• value – The attribute value.

Returns

A boolean array indicating whether the item has any flag with the given attribute.

is_bit_set(bit) → numpy.array

Return an N-length boolean array indicating whether the given bit is set for each item.

Parameters

bit – The zero-indexed bit position to check.

Returns

A boolean array indicating whether the given bit is set for each item.

set_bit(index, bit)

Set the given bit for the given item.

Parameters

• index – The item index.

• bit – The zero-indexed bit position to set.

shrink()

Shrink the data array to the maximum required shape based on the highest bit set.

toggle_bit(index, bit)

Toggle the given bit for the given index.

Parameters

• index – The item index.

• bit – The zero-indexed bit position to clear.

property bits_set

A generator that yields a tuple of bits set for each item.

If you want a more efficient lookup, you can use:

items, bits = np.where(flags.as_boolean_array())

property flags_set

A generator that yields all set flags.

This can be a hugely expensive query if you have large number of items (e.g., stars).