Skip to content

Combination

Pactole Index / Combinations / Combination

Auto-generated documentation for combinations.combination module.

BoundCombination

Show source in combination.py:748

A class representing a bound combination of values.

Arguments

values (CombinationInputOrRank | None): The values of the combination. If an integer is provided, it is treated as the lexicographic rank of the combination. rank (CombinationRank | None, optional): The lexicographic rank of the combination. If not provided, it will be calculated on demand from the values. Defaults to None. start (int | None): The start value of the combination range. Defaults to DEFAULT_START. end (int | None): The end value of the combination range. Defaults to DEFAULT_END. count (int | None): The count of numbers in the combination. Defaults to DEFAULT_COUNT. combinations (int | None): The total number of possible combinations. If not provided, it is calculated based on the start, end, and count.

Examples

>>> bound_comb = BoundCombination(values=10, start=1, end=50, count=5)
>>> bound_comb.values
[2, 3, 4, 5, 7]
>>> bound_comb.end
50
>>> bound_comb.count
5
>>> bound_comb.combinations
2118760

Signature

class BoundCombination(Combination):
    def __init__(
        self,
        values: CombinationInputOrRank | None = None,
        rank: CombinationRank | None = None,
        start: int | None = None,
        end: int | None = None,
        count: int | None = None,
        combinations: int | None = None,
    ) -> None: ...

See also

BoundCombination().combinations

Show source in combination.py:847

Return the total number of possible combinations.

Returns

  • int - The total number of combinations.

Examples

>>> bound_comb = BoundCombination(values=[1, 2, 3], start=1, end=50, count=5)
>>> bound_comb.combinations
2118760

Signature

@property
def combinations(self) -> int: ...

BoundCombination().copy

Show source in combination.py:885

Return a copy of the BoundCombination with optional modifications.

Arguments

values (CombinationInputOrRank | None): The values of the combination. If an integer is provided, it is treated as the lexicographic rank of the combination. If None, the current values are used. Defaults to None. rank (CombinationRank | None, optional): The lexicographic rank of the combination. If not provided, it will be calculated on demand from the values. Defaults to None. start (int | None): The start value of the combination range. If None, the current start is used. Defaults to None. end (int | None): The end value of the combination range. If None, the current end is used. Defaults to None. count (int | None): The count of numbers in the combination. If None, the current count is used. Defaults to None. combinations (int | None): The total number of possible combinations. If None, the current combinations are used. Defaults to None.

Returns

  • BoundCombination - A new BoundCombination instance with the specified modifications.

Examples

>>> bound_comb = BoundCombination(values=[1, 2, 3], start=1, end=50, count=5)
>>> new_comb = bound_comb.copy(values=15)
>>> new_comb.values
 [1, 2, 5, 6, 7]

Signature

def copy(
    self,
    values: CombinationInputOrRank | None = None,
    rank: CombinationRank | None = None,
    start: int | None = None,
    end: int | None = None,
    count: int | None = None,
    combinations: int | None = None,
) -> BoundCombination: ...

BoundCombination().count

Show source in combination.py:833

Return the count of numbers in the combination.

Returns

  • int - The count of numbers.

Examples

>>> bound_comb = BoundCombination(values=[1, 2, 3], start=1, end=50, count=5)
>>> bound_comb.count
5

Signature

@property
def count(self) -> int: ...

BoundCombination().end

Show source in combination.py:819

Return the end value of the combination range.

Returns

  • int - The end value.

Examples

>>> bound_comb = BoundCombination(values=[1, 2, 3], start=1, end=50, count=5)
>>> bound_comb.end
50

Signature

@property
def end(self) -> int: ...

BoundCombination.from_dict

Show source in combination.py:986

Create a BoundCombination instance from a dictionary.

Arguments

  • Data dict - A dictionary containing the keys 'values', 'rank', 'start', 'end', 'count', and 'combinations'.

Returns

  • BoundCombination - A new BoundCombination instance created from the dictionary data.

Examples

>>> data = {
...     'values': [1, 2, 3],
...     'rank': 0,
...     'start': 1,
...     'end': 50,
...     'count': 5,
...     'combinations': 2118760
... }
>>> bound_comb = BoundCombination.from_dict(data)
>>> bound_comb.values
[1, 2, 3]
>>> bound_comb.rank
0
>>> bound_comb.start
1
>>> bound_comb.end
50
>>> bound_comb.count
5
>>> bound_comb.combinations
2118760

Signature

@staticmethod
def from_dict(data: dict) -> BoundCombination: ...

BoundCombination().generate

Show source in combination.py:861

Generate a list of random combinations within the bounds.

Arguments

  • n int - The number of combinations to generate. Defaults to 1.
  • partitions int - The number of partitions to divide the range into for generation. Defaults to 1.

Returns

  • list[BoundCombination] - A list of randomly generated combinations.

Examples

>>> bound_comb = BoundCombination(start=1, end=50, count=5)
>>> random_combs = bound_comb.generate()
>>> len(random_combs)
1
>>> random_combs[0].values
[3, 15, 22, 34, 45]

Signature

def generate(self, n: int = 1, partitions: int = 1) -> list[BoundCombination]: ...

BoundCombination().to_dict

Show source in combination.py:959

Convert the BoundCombination instance to a dictionary.

Returns

  • dict - A dictionary representation of the BoundCombination instance.

Examples

>>> bound_comb = BoundCombination(values=[1, 2, 3], start=1, end=50, count=5)
>>> bound_comb.to_dict()
{
    'values': [1, 2, 3],
    'rank': 0,
    'start': 1,
    'end': 50,
    'count': 5,
    'combinations': 2118760
}

Signature

def to_dict(self) -> dict: ...

BoundCombination().to_string

Show source in combination.py:946

Convert the Combination instance to a string representation.

Returns

  • str - A string representation of the combination values.

Examples

>>> combination = Combination([3, 1, 2], rank=123)
>>> combination.to_string()
'values: [1,2,3]  rank: 123'

Signature

def to_string(self) -> str: ...

Combination

Show source in combination.py:168

A class representing a combination of values.

Arguments

values (CombinationInputValues | CombinationInputWithRank | None, optional): The values of the combination. Defaults to None. rank (CombinationRank | None, optional): The lexicographic rank of the combination. If not provided, it will be calculated on demand from the values. Defaults to None. - start int, optional - The starting offset for the combination values. Defaults to DEFAULT_START.

Raises

  • ValueError - If the provided rank is negative or if the values are not valid.

Examples

>>> combination = Combination([12, 3, 42, 6, 22])
>>> combination.values
[3, 6, 12, 22, 42]
>>> combination.rank
755560
>>> combination.length
5
>>> combination.start
1

Signature

class Combination:
    def __init__(
        self,
        values: CombinationInputValues | CombinationInputWithRank | None = None,
        rank: CombinationRank | None = None,
        start: int | None = None,
    ) -> None: ...

Combination().compares

Show source in combination.py:485

Compare the combination with another combination or lexicographic rank.

Arguments

  • combination CombinationInput - The combination or lexicographic rank to compare with.

Returns

  • int - -1 if self < combination, 0 if self == combination, 1 if self > combination.

Examples

>>> combination1 = Combination([1, 2, 3])
>>> combination2 = Combination([1, 2, 4])
>>> combination1.compares(combination2)
-1
>>> combination2.compares(combination1)
1
>>> combination1.compares([1, 2, 3])
0

Signature

def compares(self, combination: CombinationInput) -> int: ...

See also

Combination().copy

Show source in combination.py:311

Return a copy of the Combination with optional modifications.

Arguments

values (CombinationInputOrRank | None): The values of the combination. If an integer is provided, it is treated as the lexicographic rank of the combination. If None, the current values are used. Defaults to None. rank (CombinationRank | None, optional): The lexicographic rank of the combination. If not provided, it will be calculated on demand from the values. Defaults to None. start (int | None): The starting offset for the combination values. If None, the current start is used. Defaults to None.

Returns

  • Combination - A new Combination instance with the specified modifications.

Examples

>>> combination = Combination([4, 5, 6], start=1)
>>> new_comb = combination.copy(values=[2, 3, 4])
>>> new_comb.values
[2, 3, 4]
>>> new_comb.start
1
>>> new_comb = combination.copy(start=2)
>>> new_comb.values
[5, 6, 7]
>>> new_comb.start
2

Signature

def copy(
    self,
    values: CombinationInputOrRank | None = None,
    rank: CombinationRank | None = None,
    start: int | None = None,
) -> Combination: ...

Combination().equals

Show source in combination.py:370

Check if the combination is equal to another combination or lexicographic rank.

Arguments

  • combination CombinationInput - The combination or lexicographic rank to compare with.

Returns

  • bool - True if the combinations are equal, False otherwise.

Examples

>>> combination1 = Combination([1, 2, 3])
>>> combination2 = Combination([3, 2, 1])
>>> combination1.equals(combination2)
True
>>> combination1.equals([1, 2, 4])
False
>>> rank = get_combination_rank([1, 2, 3], offset=1)
>>> combination1.equals(rank)
True
>>> combination1.equals(rank + 1)
False

Signature

def equals(self, combination: CombinationInput) -> bool: ...

See also

Combination.from_csv

Show source in combination.py:633

Create a Combination instance from CSV data.

Arguments

  • Data CombinationValues - A list of combination values from CSV.

Returns

  • Combination - A new Combination instance created from the CSV data.

Examples

>>> data = [1, 2, 3]
>>> combination = Combination.from_csv(data)
>>> combination.values
[1, 2, 3]

Signature

@classmethod
def from_csv(cls, data: CombinationValues) -> Combination: ...

See also

Combination.from_dict

Show source in combination.py:671

Create a Combination instance from a dictionary.

Arguments

  • Data dict - A dictionary containing the keys 'values', 'rank', and 'start'.

Returns

  • Combination - A new Combination instance created from the dictionary data.

Examples

>>> data = {'values': [1, 2, 3], 'rank': 0, 'start': 0}
>>> combination = Combination.from_dict(data)
>>> combination.values
[1, 2, 3]
>>> combination.rank
0
>>> combination.start
0

Signature

@staticmethod
def from_dict(data: dict) -> Combination: ...

Combination.from_json

Show source in combination.py:651

Create a Combination instance from JSON data.

Arguments

data (CombinationValues | dict): A list of combination values or a dictionary from JSON.

Returns

  • Combination - A new Combination instance created from the JSON data.

Examples

>>> data = [1, 2, 3]
>>> combination = Combination.from_json(data)
>>> combination.values
[1, 2, 3]

Signature

@classmethod
def from_json(cls, data: CombinationValues | dict) -> Combination: ...

Combination.from_string

Show source in combination.py:599

Create a Combination instance from a string representation.

Arguments

  • Data str - A string representation of the combination, expected in the
    • format 'values - [1,2,3] rank: 123'.

Returns

  • Combination - A new Combination instance created from the string data.

Examples

>>> data = 'values: [1,2,3]  rank: 123'
>>> combination = Combination.from_string(data)
>>> combination.values
[1, 2, 3]
>>> combination.rank
123

Signature

@classmethod
def from_string(cls, data: str) -> Combination: ...

Combination().get_values

Show source in combination.py:355

Get the values of the combination as a sorted list with an optional new start offset.

Arguments

  • Combination().start int, optional - The new starting offset for the values. Defaults to None.

Returns

Signature

def get_values(self, start: int | None = None) -> CombinationValues: ...

See also

Combination().includes

Show source in combination.py:403

Check if the combination includes another combination.

Arguments

combination (CombinationNumber | CombinationInputValues): The combination to check for inclusion, or a single number.

Returns

  • bool - True if the combination includes the other combination, False otherwise.

Examples

>>> combination1 = Combination([2, 4, 6])
>>> combination2 = Combination([2, 4])
>>> combination1.includes(combination2)
True
>>> combination1.includes([2, 5])
False

Signature

def includes(self, combination: CombinationNumber | CombinationInputValues) -> bool: ...

Combination().intersection

Show source in combination.py:458

Get the intersection of the combination with another combination.

Arguments

combination (CombinationInputValues | Combination): The combination to intersect with.

Returns

  • Combination - The intersection of the two combinations.

Examples

>>> combination1 = Combination([1, 2, 3])
>>> combination2 = Combination([3, 4, 5])
>>> intersection = combination1.intersection(combination2)
>>> intersection.values
[3]
>>> intersection2 = combination1.intersection([4, 5, 6])
>>> intersection2.values
[]

Signature

def intersection(self, combination: CombinationInputValues) -> Combination: ...

See also

Combination().intersects

Show source in combination.py:432

Check if the combination intersects with another combination.

Arguments

combination (CombinationInputValues | Combination): The combination to check for intersection.

Returns

  • bool - True if the combination intersects with the other combination, False otherwise.

Examples

>>> combination1 = Combination([1, 2, 3])
>>> combination2 = Combination([3, 4, 5])
>>> combination1.intersects(combination2)
True
>>> combination1.intersects([4, 5, 6])
False

Signature

def intersects(self, combination: CombinationInputValues | Combination) -> bool: ...

Combination().length

Show source in combination.py:280

Get the length of the combination.

Returns

  • int - The length of the combination.

Examples

>>> combination = Combination([3, 1, 2])
>>> combination.length
3

Signature

@cached_property
def length(self) -> int: ...

Combination().rank

Show source in combination.py:246

Get the lexicographic rank of the combination.

Returns

Examples

>>> combination = Combination([3, 1, 2])
>>> combination.rank
0

Signature

@property
def rank(self) -> CombinationRank: ...

See also

Combination().similarity

Show source in combination.py:522

Calculate the similarity between the combination and another combination.

Arguments

  • combination CombinationInputValues - The combination to compare with.

Returns

  • float - The similarity ratio between the two combinations.

Examples

>>> combination1 = Combination([1, 2, 3])
>>> combination2 = Combination([2, 3, 4])
>>> combination1.similarity(combination2)
0.6666666666666666
>>> combination1.similarity([4, 5, 6])
0.0

Signature

def similarity(self, combination: CombinationInputValues) -> float: ...

See also

Combination().start

Show source in combination.py:294

Get the starting offset of the combination.

Returns

  • int - The starting offset of the combination.

Examples

>>> combination = Combination([3, 1, 2], start=0)
>>> combination.start
0
>>> combination = Combination([3, 1, 2])
>>> combination.start
1

Signature

@property
def start(self) -> int: ...

Combination().stored_rank

Show source in combination.py:262

Get the stored lexicographic rank of the combination without calculating it.

Returns

CombinationRank | None: The stored lexicographic rank of the combination, or None if it has not been calculated yet.

Examples

>>> combination = Combination([3, 1, 2])
>>> combination.stored_rank
None
>>> _ = combination.rank  # Calculate the rank
>>> combination.stored_rank
0

Signature

@property
def stored_rank(self) -> CombinationRank | None: ...

Combination().to_csv

Show source in combination.py:560

Convert the Combination instance to a format suitable for CSV export.

Returns

Examples

>>> combination = Combination([3, 1, 2])
>>> combination.to_csv()
[1, 2, 3]

Signature

def to_csv(self) -> CombinationValues: ...

See also

Combination().to_dict

Show source in combination.py:586

Convert the Combination instance to a dictionary.

Returns

  • dict - A dictionary representation of the Combination instance.

Examples

>>> combination = Combination([3, 1, 2], start=0)
>>> combination.to_dict()
{'values': [1, 2, 3], 'rank': 0, 'start': 0}

Signature

def to_dict(self) -> dict: ...

Combination().to_json

Show source in combination.py:573

Convert the Combination instance to a JSON-serializable format.

Returns

Examples

>>> combination = Combination([3, 1, 2])
>>> combination.to_json()
[1, 2, 3]

Signature

def to_json(self) -> CombinationValues: ...

See also

Combination().to_string

Show source in combination.py:547

Convert the Combination instance to a string representation.

Returns

  • str - A string representation of the combination values.

Examples

>>> combination = Combination([3, 1, 2], rank=123)
>>> combination.to_string()
'values: [1,2,3]  rank: 123'

Signature

def to_string(self) -> str: ...

Combination().values

Show source in combination.py:232

Get the values of the combination as a sorted list.

Returns

Examples

>>> combination = Combination([3, 1, 2])
>>> combination.values
[1, 2, 3]

Signature

@cached_property
def values(self) -> CombinationValues: ...

See also

CombinationInputWithRank

Show source in combination.py:736

Type representing a combination input along with its lexicographic rank.

Signature

class CombinationInputWithRank(TypedDict): ...

generate

Show source in combination.py:139

Generate a list of random combination ranks within a given range.

Arguments

  • Combinations int - The total number of possible combinations.
  • n int - The number of combinations to generate. Defaults to 1.
  • partitions int - The number of partitions to divide the range into for generation. Defaults to 1.

Yields

  • int - A randomly generated combination rank.

Examples

>>> list(generate(10, n=3))
[2, 5, 7]
>>> list(generate(100, n=5, partitions=2))
[10, 20, 30, 40, 50]

Signature

def generate(combinations: int, n: int = 1, partitions: int = 1) -> Iterator[int]: ...

get_combination_from_rank

Show source in combination.py:81

Get the combination corresponding to a given lexicographic rank.

Values are returned sorted, and offset is added to each value in the resulting combination.

Arguments

  • rank int - The lexicographic rank of the combination.
  • length int, optional - The length of the combination. Defaults to 2.
  • offset int, optional - An offset to apply to each value in the combination. Defaults to 0.

Returns

  • list[int] - The combination corresponding to the lexicographic rank.

Raises

  • ValueError - If the rank or length is negative.

Examples

>>> get_combination_from_rank(0, 3)
[0, 1, 2]
>>> get_combination_from_rank(2, 3)
[0, 2, 3]
>>> get_combination_from_rank(0, 3, offset=1)
[1, 2, 3]

Signature

def get_combination_from_rank(
    rank: int, length: int = 2, offset: int = 0
) -> list[int]: ...

get_combination_rank

Show source in combination.py:48

Get the lexicographic rank of a given combination.

Values are sorted before computing rank, and offset is subtracted from each value during ranking.

Arguments

  • combination Iterable[int] - The combination to get the lexicographic rank for.
  • offset int, optional - An offset to apply to each value in the combination. Defaults to 0.

Returns

  • int - The lexicographic rank of the combination.

Examples

>>> get_combination_rank([0, 1, 2])
0
>>> get_combination_rank([0, 2, 3])
2
>>> get_combination_rank([1, 2, 3], offset=1)
0

Signature

def get_combination_rank(combination: Iterable[int], offset: int = 0) -> int: ...