{bgRdZddlmZddlZddlmZmZddlmZm Z ddl m Z ddl m Z mZmZmZddlZddlZddlmZdd lmZmZdd lmZdd lmZdd lmZm Z dd l!m"Z"ddl#m$Z$ddl%m&Z&m'Z'ddl(m)Z)ddl*m+Z+ddl,m-Z-m.Z.m/Z/m0Z0m1Z1m2Z2ddl3m4Z4ddl5m6Z6gdZ7dZ8edGddZ9GddeZ:Gdde:Z;eGdd e:Zd(d&Z? d) d*d'Z@y)+z This module provides Grouper objects that encapsulate the "factorization" process - conversion of value we are grouping by to integer codes (one per group). ) annotationsN)ABCabstractmethod) dataclassfield)pairwise) TYPE_CHECKINGAnyLiteralcast) ArrayLike)BaseCFTimeOffset_new_to_legacy_freq)duck_array_ops apply_ufunc) Coordinates_coordinates_from_variable) DataArray)isnull)T_Group _DummyGroup)safe_cast_to_index CFTimeGrouper)Bins DatetimeLike GroupIndicesResampleCompatibleSelf SideOptions)Variable)is_chunked_array) BinGrouper EncodedGroupsGrouper Resampler TimeResampler UniqueGrouper__resample_dim__F)initcfeZdZUdZded<ded<ded<ded <d ed < d dd Zy )r%a> Dataclass for storing intermediate values for GroupBy operation. Returned by the ``factorize`` method on Grouper objects. Attributes ---------- codes : DataArray Same shape as the DataArray to group by. Values consist of a unique integer code for each group. full_index : pd.Index Pandas Index for the group coordinate containing unique group labels. This can differ from ``unique_coord`` in the case of resampling and binning, where certain groups in the output need not be present in the input. group_indices : tuple of int or slice or list of int, optional List of indices of array elements belonging to each group. Inferred if not provided. unique_coord : Variable, optional Unique group values present in dataset. Inferred if not provided rcodespd.Index full_indexr group_indiceszVariable | _DummyGroup unique_coordrcoordsNc ddlm}t|tsJ|j t d||_t|tjsJ||_ |et|js@td||jjt|D|_nt|_n||_|@|t!j"|}t%|j||j&|_n||_|7t|j(t*rJt-|j(|_y||_y)Nr)_codes_to_group_indicesz3Please set a name on the array you are grouping by.c3$K|]}|r| ywN).0gs /lib/python3.12/site-packages/xarray/groupers.py z)EncodedGroups.__init__..`s!+ sdimsdataattrs)xarray.core.groupbyr4 isinstancername ValueErrorr-pdIndexr/r#r>tupleravellenr0npuniquer"r?r1rrr2)selfr-r/r0r1r2r4 unique_valuess r:__init__zEncodedGroups.__init__Ms @%+++ :: RS S *bhh///$  #EJJ/%*+4 ((*C O+&"&+W"!.D   &ryy'78M (ZZm5;;!D !-D  >!$"3"3[A AA4T5F5FGDK DK)NNN) r-rr/r.r0zGroupIndices | Noner1zVariable | _DummyGroup | Noner2zCoordinates | None)__name__ __module__ __qualname____doc____annotations__rMr7rNr:r%r%3sg$ ((  .26:%) ,!,!,!+ ,! 4 ,! # ,!rNr%c4eZdZdZeddZeddZy)r&zUAbstract base class for Grouper objects that allow specializing GroupBy instructions.cy)z Creates intermediates necessary for GroupBy. Parameters ---------- group : DataArray DataArray we are grouping by. Returns ------- EncodedGroups Nr7)rKgroups r: factorizezGrouper.factorizes rNcy)zL Creates a new version of this Grouper clearing any caches. Nr7rKs r:resetz Grouper.resets rNNrVrreturnr%r\r )rOrPrQrRrrWrZr7rNr:r&r&|s+_      rNr&ceZdZdZy)r'z Abstract base class for Grouper objects that allow specializing resampling-type GroupBy instructions. Currently only used for TimeResampler, but could be used for SpaceResampler in the future. N)rOrPrQrRr7rNr:r'r's   rNr'ceZdZUdZeddZded<edZded <edd Z dd Z dd Z dd Z ddZ ddZy)r)a Grouper object for grouping by a categorical variable. Parameters ---------- labels: array-like, optional Group labels to aggregate on. This is required when grouping by a chunked array type (e.g. dask or cubed) since it is used to construct the coordinate on the output. Grouped operations will only be run on the specified group labels. Any group that is not present in ``labels`` will be ignored. NF)defaultreprzpd.Index | None_group_as_indexr`zArrayLike | NonelabelscD|j|jjdk(r+|jj|_|jSt j t j|jj|_|jS)z-Caches the group DataArray as a pandas Index.) rbrVndimto_indexrDrErIarrayrGrYs r:group_as_indexzUniqueGrouper.group_as_indexsx    'zz!#'+zz':':'<$###(*xx0D0J0J0L'M$###rNc"t|Sr6)typerYs r:rZzUniqueGrouper.resetstDz|rNc||_t|jr|j t d|j|j |S|j }t|jtxs(|jxr|jxs |j}|jj|jjfk(}|xr|}|r|jS|jS)NzTWhen grouping by a dask array, `labels` must be passed using a UniqueGrouper object.)rVr#r>rdrC_factorize_given_labelsrjrAr is_uniqueis_monotonic_increasingis_monotonic_decreasingr=rB_factorize_dummy_factorize_unique)rKrVindexis_unique_and_monotonic is_dimension can_squeezes r:rWzUniqueGrouper.factorizes EJJ 'DKK,?*  ;; "//6 6##",TZZ"E# OO Q..O%2O2O zz4::??*<< ">'> ((* *))+ +rNc  tt|d|jidtjgd}t |t j|jt|j|j|jjS)Nrd parallelizedT)kwargsdask output_dtypes keep_attrsr<)r-r/r1) rrnrdrIint64r%rDrEr"rBrVr?)rKrVr-s r:rnz%UniqueGrouper._factorize_given_labelssr # dkk*88*  xx ,!ZZ[[jj&&  rNct|jtj }t |j|\}}|dk(j r t d|jj|j|jjd}t|j||jj}tj|}t|||t!|S)NsortzEFailed to group data. Are you grouping by a variable that is all NaN?Fr>deepr<r-r/r1r2)rArjrD MultiIndexunique_value_groupsallrCrVcopyreshapeshaper"rBr?rEr%r)rKrrLcodes_r-r1r/s r:rszUniqueGrouper._factorize_uniquesd112==AA 3D4G4Gd S v bL   W  V^^DJJ4D4D%EER-tzz7G7G XXm, !%-l;   rNc"|jj}tdt|D}t j |}t |jtrj|jjj|}|j}tj|jj}t}n|jj|d}|jjj}|j}t |tj r,tj"||jj$}n#t&rt |t(sJt+|}t-|||||S)Nc3:K|]}t||dzyw)rfN)slice)r8is r:r;z1UniqueGrouper._factorize_dummy..s+Q[E!QUO[s)r>Fr)dimr-r0r/r1r2)rVsizerFrangerIarangerAr to_dataarrayrrD RangeIndexrvariableto_base_variablerjrfrom_pandas_multiindexrBr r"rr%)rKrr0 size_ranger-r1r/r2s r:rrzUniqueGrouper._factorize_dummys'zz',+QU4[+Q&Q YYt_  djj+ .JJ++-22 2CE::Ltzz7J ]FJJOO%O@E::..??AL,,J*bmm4$;;DJJOO!%lH===3LA'!%   rN)r\r.r]r[)r\r%)rOrPrQrRrrbrSrdpropertyrjrZrWrnrsrrr7rNr:r)r)sU (-T'FO_F$T2F 2 $$,0 & *! rNr)ceZdZUdZded<dZded<dZded <d Zd ed <d Zded<dZ ded<ddZ ddZ dZ ddZ ddZy)r$a Grouper object for binning numeric data. Attributes ---------- bins : int, sequence of scalars, or IntervalIndex The criteria to bin by. * int : Defines the number of equal-width bins in the range of `x`. The range of `x` is extended by .1% on each side to include the minimum and maximum values of `x`. * sequence of scalars : Defines the bin edges allowing for non-uniform width. No extension of the range of `x` is done. * IntervalIndex : Defines the exact bins to be used. Note that IntervalIndex for `bins` must be non-overlapping. right : bool, default True Indicates whether `bins` includes the rightmost edge or not. If ``right == True`` (the default), then the `bins` ``[1, 2, 3, 4]`` indicate (1,2], (2,3], (3,4]. This argument is ignored when `bins` is an IntervalIndex. labels : array or False, default None Specifies the labels for the returned bins. Must be the same length as the resulting bins. If False, returns only integer indicators of the bins. This affects the type of the output container (see below). This argument is ignored when `bins` is an IntervalIndex. If True, raises an error. When `ordered=False`, labels must be provided. retbins : bool, default False Whether to return the bins or not. Useful when bins is provided as a scalar. precision : int, default 3 The precision at which to store and display the bins labels. include_lowest : bool, default False Whether the first interval should be left-inclusive or not. duplicates : {"raise", "drop"}, default: "raise" If bin edges are not unique, raise ValueError or drop non-uniques. rbinsTboolrightNr rdint precisionFinclude_lowestraisezLiteral['raise', 'drop'] duplicatesct||j|j|j|j|j |j S)N)rrrdrrr)rlrrrdrrrrYs r:rZzBinGrouper.resetSsAtDz**;;nn..   rNcttj|jjr t dy)NzAll bin edges are NaN.)rrrrrCrYs r: __post_init__zBinGrouper.__post_init__]s.   + / / 156 6 2rNc tjtj|j |j |j |j|j|j|jdS)NT)rrrdrrrretbins) rDcutrIasarrayrGrrrdrrr)rKr>s r:_cutzBinGrouper._cutasWvv JJt  " " $**;;nn..  rNc,fd}t||ddS)Ncj|\}}tjtr|_|jj |j Sr6)rrArrr-rr)r>rzbinnedrrKs r:_wrapperz,BinGrouper._factorize_lazy.._wrappernsB99T?LFD$))S)  <<'' 3 3rNryT)r{r}r)rKrVrs` r:_factorize_lazyzBinGrouper._factorize_lazyms 48UDQQrNcPt|tr,t|j|j|j }t |j}t|jtr|rtd|jd|j|}|s+|dk(jrtd|j|j d}||_|jtjdgj|j \}}|j"}|sLtj$t'j(|jj+}|||dk7} n|} t-|| |j.} t1||| t3|  S) N)r=rBzOBin edges must be provided when grouping by chunked arrays. Received self.bins=z insteadrz.None of the data falls within bins with edges _binsrr<r)rArrr>r=rBr#rrrCrrrrIriastypedtype categoriesrrDrJrGr"r?r%r) rKrV by_is_chunkedr- new_dim_namedummy_r/uniquesrLr1s r:rWzBinGrouper.factorizewsj e[ )ejjuzz KE(4 dii %-bX\XaXaWeemn $$U+%2+!2!2!4@ N  **U+ ! 99RXXqc]11%++>?q%% ggbii (8(8(:;M&MM !%-l;   rNr])r\None)rVrr\rr[)rOrPrQrRrSrrdrrrrZrrrrWr7rNr:r$r$#s\$L JE4FCIs ND +2J(2 7  R# rNr$)raceZdZUdZded<edZded<edZded<ed Zd ed <edZ d ed <eddZ ded<eddZ ded<ddZ ddZ ddZddZddZy)r(aF Grouper object specialized to resampling the time coordinate. Attributes ---------- freq : str, datetime.timedelta, pandas.Timestamp, or pandas.DateOffset Frequency to resample to. See `Pandas frequency aliases `_ for a list of possible values. closed : {"left", "right"}, optional Side of each interval to treat as closed. label : {"left", "right"}, optional Side of each interval to use for labeling. origin : {'epoch', 'start', 'start_day', 'end', 'end_day'}, pandas.Timestamp, datetime.datetime, numpy.datetime64, or cftime.datetime, default 'start_day' The datetime on which to adjust the grouping. The timezone of origin must match the timezone of the index. If a datetime is not used, these values are also supported: - 'epoch': `origin` is 1970-01-01 - 'start': `origin` is the first value of the timeseries - 'start_day': `origin` is the first day at midnight of the timeseries - 'end': `origin` is the last value of the timeseries - 'end_day': `origin` is the ceiling midnight of the last day offset : pd.Timedelta, datetime.timedelta, or str, default is None An offset timedelta added to the origin. rfreqNrczSideOptions | Noneclosedlabel start_dayzstr | DatetimeLikeoriginz.pd.Timedelta | datetime.timedelta | str | NoneoffsetF)r+razCFTimeGrouper | pd.Grouper index_grouperr.rjct||j|j|j|j|j S)Nrrrrr)rlrrrrrrYs r:rZzTimeResampler.resets8tDz;;**;;;;   rNc ddlm}t|}|j}|js t dt ||rHddlm}||j|j|j|j||_ ||_yt |jtr t dtj t#|j|j|j|j||_ ||_y)Nr CFTimeIndexz&Index must be monotonic for resamplingrrzZ'BaseCFTimeOffset' resample frequencies are only supported when resampling a 'CFTimeIndex')xarrayrrrrprCrAxarray.core.resample_cftimerrrrrrrrDr&rrj)rKrVrrjrrs r:_init_propertieszTimeResampler._init_propertiess&+E255EF F nk 2 A!.YY{{jj{{ "D ,-$))%56 6 "$(3{{jj{{ "D -rNc|j\}}|j}|jjr|j }|j d}|||fS)Nr*) first_itemsrtranydropnarename)rKrr-r/s r:_get_index_and_itemsz"TimeResampler._get_index_and_itemssa!--/ U &&     # # %%,,.K&&'9: ;--rNcddlm}ddlm}t |j |r/|j j t||jStjtj|jj|j}|j|j }|j}|j!}tj"tjt%||}||fS)Nrrr)xarray.coding.cftimeindexrrrrArrr rjrDSeriesrIrrgroupbyfirstcountrepeatrH)rKrrsgroupedrcountsr-s r:rzTimeResampler.first_itemss9= d((- 8%%11[$"5"56  "))D$7$7$<$<=t?R?RSAii 2 23G!--/K]]_FIIbiiK(896BE% %rNc |j||j\}}}|jjtj }t t|Dcgc]\}}t||c}}t|ddgz}t|j|j|j} |j|j|jd} t!| ||| t#| Scc}}w)Nrr<Frr)rrvaluesrrIr~rFrrr"rBrtr?rrrr%r) rKrVr/rrsbinsrjr0r1r-s r:rWzTimeResampler.factorize s e$*.*C*C*E' K""))"((3&+%-e_ 5_TQU1a[_ 5uRy$9O8P P'  +"3"35;;  u{{ ;% H'!%-l;    6s"D r])rVrr\r)r\z&tuple[pd.Index, pd.Series, np.ndarray])r\ztuple[pd.Series, np.ndarray]r[)rOrPrQrRrSrrrrrrrjrZrrrrWr7rNr:r(r(s6 !&t!4F 4 %d 3E 3!&{!;F ;=B4=PF :P055u0MM-M$%erdr is_sortedr-masks r:rnrn#s ZZ F299V[[11668I OOFD 8E GGD& ! !F4L 0ES[4H ID &(es6{"#x E$K LrNctj||\}}t|tjr|j|_||fS)aGroup an array by its unique values. Parameters ---------- ar : array-like Input array. This will be flattened if it is not already 1-D. sort : bool, default: True Whether or not to sort unique values. Returns ------- values : np.ndarray Sorted, unique values as returned by `np.unique`. indices : list of lists of int Each element provides the integer indices in `ar` with values given by the corresponding value in `unique_values`. r)rDrWrArnames)arrinversers r:rr2s;(ll2D1OGV&"--(xx 7?rN)r> np.ndarrayrdrr\r)T)rrr\z(tuple[np.ndarray | pd.Index, np.ndarray])ArR __future__rdatetimeabcrr dataclassesrr itertoolsrtypingr r r r numpyrIpandasrD numpy.typingr xarray.coding.cftime_offsetsrr xarray.corerxarray.core.computationrxarray.core.coordinatesrrxarray.core.dataarrayrxarray.core.duck_array_opsrr@rrxarray.core.indexesrrrxarray.core.typesrrrrr r!xarray.core.variabler"xarray.namedarray.pycompatr#__all__ RESAMPLE_DIMr%r&r'r)r$r(rnrr7rNr:rs  ##(44"N&/K+-425*7 "  E!E!E!P c 6   ~ G~  ~ B v v  v r B IB B J  -rN