a
    yn„f‚  ã                   @  sz   d dl mZ d dlZd dlmZ d dlmZmZ d dl	m
Z
 d dlmZ dZe
 ¡ Zeƒ dd	ddd
œdd„ƒZdd„ ZdS )é    )ÚannotationsN)Úhigh_level_function)ÚHighLevelContextÚmaybe_posaxis)ÚNumpyMetadata)Úregularize_axis)Úflattené   T)Ú	highlevelÚbehaviorÚattrsc                c  s   | fV  t | ||||ƒS )a.  
    Args:
        array: Array-like data (anything #ak.to_layout recognizes).
        axis (None or int): If None, the operation flattens all levels of
            nesting, returning a 1-dimensional array. Otherwise, it flattens
            at a specified depth. The outermost dimension is `0`, followed
            by `1`, etc., and negative values count backward from the
            innermost: `-1` is the innermost dimension, `-2` is the next
            level up, etc.
        highlevel (bool): If True, return an #ak.Array; otherwise, return
            a low-level #ak.contents.Content subclass.
        behavior (None or dict): Custom #ak.behavior for the output array, if
            high-level.
        attrs (None or dict): Custom attributes for the output array, if
            high-level.

    Returns an array with one level of nesting removed by erasing the
    boundaries between consecutive lists. Since this operates on a level of
    nesting, `axis=0` is a special case that only removes values at the
    top level that are equal to None.

    Consider the following.

        >>> array = ak.Array([[[1.1, 2.2, 3.3],
        ...                    [],
        ...                    [4.4, 5.5],
        ...                    [6.6]],
        ...                   [],
        ...                   [[7.7],
        ...                    [8.8, 9.9]
        ...                   ]])

    At `axis=1`, the outer lists (length 4, length 0, length 2) become a single
    list (of length 6).

        >>> ak.flatten(array, axis=1).show()
        [[1.1, 2.2, 3.3],
         [],
         [4.4, 5.5],
         [6.6],
         [7.7],
         [8.8, 9.9]]

    At `axis=2`, the inner lists (lengths 3, 0, 2, 1, 1, and 2) become three
    lists (of lengths 6, 0, and 3).

        >>> ak.flatten(array, axis=2).show()
        [[1.1, 2.2, 3.3, 4.4, 5.5, 6.6],
         [],
         [7.7, 8.8, 9.9]]

    There's also an option to completely flatten the array with `axis=None`.
    This is useful for passing the data to a function that doesn't care about
    nested structure, such as a plotting routine.

        >>> ak.flatten(array, axis=None).show()
        [1.1,
         2.2,
         3.3,
         4.4,
         5.5,
         6.6,
         7.7,
         8.8,
         9.9]

    Missing values are eliminated by flattening: there is no distinction
    between an empty list and a value of None at the level of flattening.

        >>> array = ak.Array([[1.1, 2.2, 3.3], None, [4.4], [], [5.5]])
        >>> ak.flatten(array, axis=1)
        <Array [1.1, 2.2, 3.3, 4.4, 5.5] type='5 * float64'>

    As a consequence, flattening at `axis=0` does only one thing: it removes
    None values from the top level.

        >>> ak.flatten(array, axis=0)
        <Array [[1.1, 2.2, 3.3], [4.4], [], [5.5]] type='4 * var * float64'>

    As a technical detail, the flattening operation can be trivial in a common
    case, #ak.contents.ListOffsetArray in which the first `offset` is `0`.
    In that case, the flattened data is simply the array node's `content`.

        >>> array = ak.Array([[0.0, 1.1, 2.2], [], [3.3, 4.4], [5.5], [6.6, 7.7, 8.8, 9.9]])
        >>> array.layout
        <ListOffsetArray len='5'>
            <offsets><Index dtype='int64' len='6'>
                [ 0  3  3  5  6 10]
            </Index></offsets>
            <content><NumpyArray dtype='float64' len='10'>
                [0.  1.1 2.2 3.3 4.4 5.5 6.6 7.7 8.8 9.9]
            </NumpyArray></content>
        </ListOffsetArray>

        >>> ak.flatten(array).layout
        <NumpyArray dtype='float64' len='10'>
            [0.  1.1 2.2 3.3 4.4 5.5 6.6 7.7 8.8 9.9]
        </NumpyArray>

        >>> array.layout.content
        <NumpyArray dtype='float64' len='10'>
            [0.  1.1 2.2 3.3 4.4 5.5 6.6 7.7 8.8 9.9]
        </NumpyArray>

    However, it is important to keep in mind that this is a special case:
    #ak.flatten and `content` are not interchangeable!

        >>> array = ak.Array(
        ...     ak.contents.ListArray(
        ...         ak.index.Index64(np.array([ 9, 100, 5, 8, 1])),
        ...         ak.index.Index64(np.array([12, 100, 7, 9, 5])),
        ...         ak.contents.NumpyArray(
        ...             np.array([999, 6.6, 7.7, 8.8, 9.9, 3.3, 4.4, 999, 5.5, 0., 1.1, 2.2, 999])
        ...         ),
        ...     )
        ... )
        >>> array.show()
        [[0, 1.1, 2.2],
         [],
         [3.3, 4.4],
         [5.5],
         [6.6, 7.7, 8.8, 9.9]]

        >>> ak.flatten(array).show()
        [0,
         1.1,
         2.2,
         3.3,
         4.4,
         5.5,
         6.6,
         7.7,
         8.8,
         9.9]

        >>> ak.Array(array.layout.content).show()
        [999,
         6.6,
         7.7,
         8.8,
         9.9,
         3.3,
         4.4,
         999,
         5.5,
         0,
         1.1,
         2.2,
         999]
    )Ú_impl)ÚarrayÚaxisr
   r   r   © r   ú`/home/yuhw/wc/wire-cell-python/wcpy/lib/python3.9/site-packages/awkward/operations/ak_flatten.pyr      s     r   c                   sÔ   t |ƒ}t||d�� }|j| ddd�}W d   ƒ n1 s:0    Y  |d u rŠtjj|dd�}t|tƒrxtdd„ |D ƒƒs|J ‚tj 	|¡}n<|d	ks¢t
||d
ƒd	kr¸‡ fdd„‰ ˆ |ƒ}ntj ||¡}|j||d�S )N)r   r   FÚerror)Zallow_recordZprimitive_policyz
ak.flatten)Zfunction_namec                 s  s   | ]}t |tjjƒV  qd S ©N)Ú
isinstanceÚakÚcontentsZContent©Ú.0Úxr   r   r   Ú	<genexpr>¶   s   z_impl.<locals>.<genexpr>r   r	   c                   s*  | j r ˆ tj | jj g ¡¡ƒS | jr2ˆ |  ¡ ƒS | j	�rt
dd„ | jD ƒƒsR| S | jj}| jjj| jjdd�}| jjj| jjtjd�}t| jƒD ]L\}}|jr’t|tjjƒs’d|d d …< |jdd� tj¡|||k< d||< q’|d	k}tj tj || ¡tj || ¡| j¡S | j�r"|  ¡ S | S d S )
Nc                 s  s$   | ]}|j ot|tjjƒ V  qd S r   )Ú	is_optionr   r   r   ÚUnmaskedArrayr   r   r   r   r   Æ   s   ÿz'_impl.<locals>.apply.<locals>.<genexpr>T)Úcopy)ZdtypeF)Z
valid_whenéÿÿÿÿr   )Z
is_unknownr   r   Z
NumpyArrayÚbackendZnplikeZasarrayZ
is_indexedÚprojectZis_unionÚanyÚtagsÚdataZindex_nplikeÚindexÚemptyÚlengthÚnpZbool_Ú	enumerater   r   r   Zmask_as_boolÚviewZ
UnionArrayZIndex8ZIndex64)Úlayoutr"   r$   Zbig_maskÚtagÚcontentZgood©Úapplyr   r   r.   ¾   sH    þÿ
ÿÿÿþ
ýz_impl.<locals>.apply)r
   )r   r   Úunwrapr   Z_doZremove_structurer   ÚtupleÚallZ	mergemanyr   r   Úwrap)r   r   r
   r   r   Úctxr*   Úoutr   r-   r   r   ¯   s    .ÿ,
r   )r	   )Ú
__future__r   Zawkwardr   Zawkward._dispatchr   Zawkward._layoutr   r   Zawkward._nplikes.numpy_liker   Zawkward._regularizer   Ú__all__Úinstancer'   r   r   r   r   r   r   Ú<module>   s    