pctheory.pcseg
################

.. py:function:: adjacent_search(pcseg: list, corpus: list)

     Performs an adjacent search on a corpus of pcsegs. Returns all pcsegs in the corpus that contain pcseg as an ordered sublist.
    :param pcseg: A pcseg to search for
    :param corpus: The corpus of pcsegs to search
    :return: A sublist of pcsegs from the corpus that have pcseg in them. If an entry in the original corpus contains pcseg more than once, it will only be included once in this sublist. If no entries have pcseg in them, returns an empty list.
    *Compatible with all PitchClass modulos  

.. py:function:: are_combinatorial2(row1: list, row2: list)

    Determines if two rows are hexachordally combinatorial

    :param row1: A row
    :param row2: A row
    :return: True or False
    *Compatible only with chromatic pcsegs

.. py:function:: are_combinatorial3(row1: list, row2: list, row3: list)

    Determines if three rows are tetrachordally combinatorial

    :param row1: A row
    :param row2: A row
    :param row3: A row
    :return: True or False
    *Compatible only with chromatic pcsegs

.. py:function:: are_combinatorial4(row1: list, row2: list, row3: list, row4: list)

    Determines if four rows are trichordally combinatorial

    :param row1: A row
    :param row2: A row
    :param row3: A row
    :param row4: A row
    :return: True or False
    *Compatible only with chromatic pcsegs

.. py:function:: bip_n(imb: list)

    Gets the BIP_n of a list of set-classes generated by IMB_n

    :param imb: The IMB_n list
    :return: The BIP_n
    *Compatible only with chromatic pcsegs

.. py:function:: create_ormap(pcseg: list)
    
    Creates the ORMAP of a row

    :param pcseg: A row
    :return: The ORMAP
    *Compatible with all PitchClass modulos  

.. py:function:: generate_pcseg12_from_interval_list(interval_list: list, starting_pc=None)
    
    Generates a pcseg from an interval list
    
    :param interval_list: The interval list
    :param starting_pc: The starting pitch-class. If None, a random starting pitch-class is used.
    :return: A pcseg
    *Compatible only with chromatic pcsegs

.. py:function:: generate_pcseg24_from_interval_list(interval_list: list, starting_pc=None)
    
    Generates a pcseg from an interval list

    :param interval_list: The interval list
    :param starting_pc: The starting pitch-class. If None, a random starting pitch-class is used.
    :return: A pcseg
    *Compatible only with microtonal pcsegs

.. py:function:: generate_random_all_interval_row(starting_pc=None)
    
    Generates a random all-interval row

    :param starting_pc: The starting pitch-class. If None, a random starting pitch-class is used.
    :return: An all-interval row
    *Compatible only with chromatic pcsegs

.. py:function:: generate_random_all_trichord_row(starting_pc=None)
    
    Generates a random all-trichord row
    
    :param starting_pc: The starting pitch-class. If None, a random starting pitch-class is used.
    :return: An all-trichord row
    *Compatible only with chromatic pcsegs

.. py:function:: generate_random_all_trichord_babbitt_row(starting_pc=None)
    
    Generates a random all-trichord (Babbitt) row

    :param starting_pc: The starting pitch-class. If None, a random starting pitch-class is used.
    :return: An all-trichord (Babbitt) row
    *Compatible only with chromatic pcsegs

.. py:function:: generate_random_pcseg12(length: int, non_duplicative=False, starting_pc=None)
    
    Generates a random pcseg

    :param length: The length of the pcseg
    :param non_duplicative: Whether or not duplicate pcs may occur (must be True to generate a row)
    :param starting_pc: The starting pitch-class. If None, a random starting pitch-class is used.
    :return: A random pcseg
    *Compatible only with chromatic pcsegs

.. py:function:: generate_random_pcseg24(length: int, non_duplicative=False, starting_pc=None)
    
    Generates a random pcseg

    :param length: The length of the pcseg
    :param non_duplicative: Whether or not duplicate pcs may occur (must be True to generate a row)
    :param starting_pc: The starting pitch-class. If None, a random starting pitch-class is used.
    :return: A random pcseg
    *Compatible only with microtonal pcsegs

.. py:function:: generate_random_pcseg_from_pcset(pcset: set)
    
    Generates a random pcseg from a pcset

    :param pcset: A pcset
    :return: A pcseg
    *Compatible with all PitchClass modulos    

.. py:function:: generate_random_ten_trichord_row(starting_pc=None)
    
    Generates a random ten-trichord row

    :param starting_pc: The starting pitch-class. If None, a random starting pitch-class is used.
    :return: A ten-trichord row
    *Compatible only with chromatic pcsegs

.. py:function:: get_intervals(pcseg: list)

    Gets the interval sequence of a pcseg

    :param pcseg: The pcseg
    :return: The interval sequence
    *Compatible with all PitchClass modulos   

.. py:function:: get_row_class(row: list)
    
    Gets all of the rows in a row-class
    
    :param row: A row
    :return: The row-class, as a set of rows
    *Compatible with PitchClasses mod 12 and 24

.. py:function:: get_row_dsym(row: list)
    
    Gets the degree of symmetry of a row
    
    :param row: A row
    :return: The degree of symmetry of the row
    *Compatible with PitchClasses mod 12 and 24

.. py:function:: imb_n(pcseg: list, n: int)
    
    Gets the IMB_n of a pcseg. The IMB_n is the segment of imbricated set-classes of cardinality n.

    :param pcseg: The pcseg
    :param n: The cardinality of imbrication
    :return: The IMB_n
    *Compatible with all PitchClass modulos        

.. py:function:: invert(pcseg: list)
    
    Inverts a pcseg
    
    :param pcseg: The pcseg
    :return: The inverted pcseg
    *Compatible with all PitchClass modulos    

.. py:function:: is_all_interval_row(pcseg: list)
    
    Determines if a pcseg is an all-interval row
    
    :param pcseg: The pcseg
    :return: Whether or not the pcseg is an all-interval row
    *Compatible with PitchClasses mod 12 and 24

.. py:function:: is_all_trichord_row(pcseg: list)
    
    Determines if a pcseg is an all-trichord row
    
    :param pcseg: The pcseg
    :return: Whether or not the pcseg is an all-trichord row
    *Compatible only with chromatic pcsegs

.. py:function:: is_all_trichord_babbitt_row(pcseg: list)
    
    Determines if a pcseg is an "all-trichord" row (after Babbitt). This kind of row
    contains ten unique imbricated trichords, none of which are set-classes [036] or [048].
    Rotation is not considered.
    
    :param pcseg: The pcseg
    :return: Whether or not the pcseg is an "all-trichord" row (after Babbitt)
    *Compatible only with chromatic pcsegs

.. py:function:: is_link_chord(pcseg: list)
    
    Determines if a row is a Link chord (an all-interval row containing the all-trichord hexachord as a subset)
    
    :param pcseg: A pcset
    :return: True or False
    *Compatible only with chromatic pcsegs

.. py:function:: is_row(pcseg: list)
    
    Determines if a pcseg is a row
    
    :param pcseg: The pcseg
    :return: Whether or not the pcseg is a row
    *Compatible with PitchClasses mod 12 and 24

.. py:function:: is_row_generator(rgen: list)
    
    Determines if a row generator is valid
    
    :param rgen: A row generator
    :return: True if the row generator is valid; false otherwise
    *Compatible only with chromatic pcsegs

.. py:function:: is_ten_trichord_row(pcseg: list)
    
    Determines if a pcseg is a ten-trichord row. This kind of row
    contains ten unique imbricated trichords. Rotation is not considered.
    
    :param pcseg: The pcseg
    :return: Whether or not the pcseg is an "all-trichord" row (after Babbitt)
    *Compatible only with chromatic pcsegs

.. py:function:: make12(*args)
    
    Makes a pcseg
    
    :param args: Pcs
    :return: A pcseg
    *Compatible only with chromatic pcsegs

.. py:function:: make_pcseg12(*args)
    
    Makes a pcseg. Alias for make12.
    
    :param args: Pcs
    :return: A pcseg
    *Compatible only with chromatic pcsegs

.. py:function:: make24(*args)
    
    Makes a pcseg
    
    :param args: Pcs
    :return: A pcseg
    *Compatible only with microtonal pcsegs

.. py:function:: make_pcseg24(*args)
    
    Makes a pcseg. Alias for make24.
    
    :param args: Pcs
    :return: A pcseg
    *Compatible only with microtonal pcsegs

.. py:function:: multiply(pcseg: list, n: int)
    
    Multiplies a pcseg
    
    :param pcseg: The pcseg
    :param n: The multiplier
    :return: The multiplied pcseg
    *Compatible with all PitchClass modulos    

.. py:function:: multiply_order(pcseg: list, n: int)
    
    Multiplies a pcseg's order
    
    :param pcseg: The pcseg
    :param n: The multiplier
    :return: The order-multiplied pcseg
    *Compatible with all PitchClass modulos

.. py:function:: ormap(row: list, ormap: dict)
    
    Performs the ORMAP mapping on a row, given a provided ORMAP
    
    :param row: A row
    :param ormap:
    :return: The ORMAP mapping for the row
    *Compatible with all PitchClass modulos

.. py:function:: prot(pcseg: list)
    
    Generates the protocol pairs for a pcseg
    
    :param pcseg: A pcseg
    :return: A set of protocol pairs
    *Compatible with all PitchClass modulos

.. py:function:: retrograde(pcseg: list)
    
    Retrogrades a pcseg
    
    :param pcseg: The pcseg
    :return: The retrograded pcseg
    *Compatible with all PitchClass modulos

.. py:function:: rotate(pcseg: list, n: int)
    
    Rotates a pcseg
    
    :param pcseg: The pcseg
    :param n: The index of rotation
    :return: The rotated pcseg
    *Compatible with all PitchClass modulos

.. py:function:: transform(pcseg, string)
    
    Transforms a pcseg with a provided transformation string
    - Tn: transpose
    - I: invert
    - Mn: multiply
    - R: retrograde
    - rn: rotate
    
    :param pcseg: The pcseg to transform
    :param string: The transformation string
    :return: The transformed pcseg

.. py:function:: transform_hstack(pcseg, transformation_list)
    
    Generates a really long pcseg by horizontally stacking transformed versions of it
    
    :param pcseg: The pcseg to stack
    :param transformation_list: A list of transformations to stack
    :return: The stacked and transformed pcseg

.. py:function:: transpose(pcseg: list, n: int)
    
    Transposes a pcseg
    
    :param pcseg: The pcseg
    :param n: The index of transposition
    :return: The transposed pcseg
    *Compatible with all PitchClass modulos

.. py:function:: transpositional_combination(pcseg1: list, pcseg2: list)
    
    Transpositionally combines (TC) two pcsegs. This is Boulez's "multiplication."

    :param pcseg1: A pcseg
    :param pcseg2: A pcseg
    :return: The TC pcset
    *Compatible with all PitchClass modulos

.. py:class:: InvarianceMatrix

    Represents an invariance matrix. Compatible with all PitchClass modulos for T and I
    matrices, and compatible with mod 12 and mod 24 for various M matrices
    (M5, M7 for mod 12; M5, M7, M11, M13, M17, M19 for mod 24)

    .. py:property:: mx

        The matrix

    .. py:property:: pcseg_a

        The pcseg A

    .. py:property:: pcseg_b

        The pcseg B

    .. py:property:: pcseg_c

        The pcseg C

    .. py:method:: __init__(self, mx_type="T", a=None, c=None)
        
        Creates an invariance matrix
        
        :param mx_type: The matrix type (T, I, M, or MI)
        :param a: Pcseg A
        :param c: Pcseg B

    .. py:method:: __getitem__(self, i, j)
        
        Gets the pc at the specified row and column
        
        :param i: The row
        :param j: The column
        :return: The pc

    .. py:method:: __repr__(self)
        
        Gets a representation of the InvarianceMatrix object
        
        :returns: A string representation of the InvarianceMatrix object

    .. py:method:: __str__(self)
        
        Converts the InvarianceMatrix object to string
        
        :returns: A string conversion of the InvarianceMatrix object

    .. py:method:: get_column(self, j)
        
        Gets a column of the matrix
        
        :param j: The column index
        :return: The column

    .. py:method:: get_row(self, i)
        
        Gets a row of the matrix
        
        :param i: The row index
        :return: The row

    .. py:method:: load_matrix(self, a: list, c: list)
        
        Loads the matrix
        
        :param a: Pcseg A
        :param c: Pcseg C
        
    .. py:method:: print(self, include: list = None)
        
        Prints the invariance matrix. You can specify to only print certain pcs to highlight invariance.
        
        :param include: The pcs to include (if None, all pcs will be printed)
        :returns: None

.. py:class:: TwelveToneMatrix

    Represents a twelve-tone matrix. Compatible only with mod 12 PitchClasses.

    .. py:property:: labels_bottom

        Gets the labels for the bottom of the matrix

    .. py:property:: labels_left

        Gets the labels for the left of the matrix

    .. py:property:: labels_right

        Gets the labels for the right of the matrix

    .. py:property:: labels_top

        Gets the labels for the top of the matrix

    .. py:property:: matrix

        Gets the matrix

    .. py:property:: row

        Gets the row

    .. py:method:: __init__(self, row=None)
        
        Creates a twelve-tone matrix
        
        :param row: A row to import

    .. py:method:: __getitem__(self, i, j)
        
        Gets the pc at the specified row and column
        
        :param i: The row
        :param j: The column
        :return: The pc

    .. py:method:: __repr__(self)
        
        Generates a string representation of the TwelveToneMatrix that can be printed
        
        :return: A string representation of the TwelveToneMatrix

    .. py:method:: __str__(self)
        
        Generates a string representation of the TwelveToneMatrix that can be printed
        
        :return: A string representation of the TwelveToneMatrix

    .. py:method:: get_column(self, j)
        
        Gets a column of the matrix

        :param j: The column index
        :return: The column

    .. py:method:: get_row(self, i)
        
        Gets a row of the matrix
        
        :param i: The row index
        :return: The row

    .. py:method:: import_row(self, row: list)
        
        Imports a row
        
        :param row: The row to import