core.py 258 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184
  1. """
  2. numpy.ma : a package to handle missing or invalid values.
  3. This package was initially written for numarray by Paul F. Dubois
  4. at Lawrence Livermore National Laboratory.
  5. In 2006, the package was completely rewritten by Pierre Gerard-Marchant
  6. (University of Georgia) to make the MaskedArray class a subclass of ndarray,
  7. and to improve support of structured arrays.
  8. Copyright 1999, 2000, 2001 Regents of the University of California.
  9. Released for unlimited redistribution.
  10. * Adapted for numpy_core 2005 by Travis Oliphant and (mainly) Paul Dubois.
  11. * Subclassing of the base `ndarray` 2006 by Pierre Gerard-Marchant
  12. (pgmdevlist_AT_gmail_DOT_com)
  13. * Improvements suggested by Reggie Dugard (reggie_AT_merfinllc_DOT_com)
  14. .. moduleauthor:: Pierre Gerard-Marchant
  15. """
  16. # pylint: disable-msg=E1002
  17. import builtins
  18. import inspect
  19. import operator
  20. import warnings
  21. import textwrap
  22. import re
  23. from functools import reduce
  24. import numpy as np
  25. import numpy.core.umath as umath
  26. import numpy.core.numerictypes as ntypes
  27. from numpy import ndarray, amax, amin, iscomplexobj, bool_, _NoValue
  28. from numpy import array as narray
  29. from numpy.lib.function_base import angle
  30. from numpy.compat import (
  31. getargspec, formatargspec, long, unicode, bytes
  32. )
  33. from numpy import expand_dims
  34. from numpy.core.numeric import normalize_axis_tuple
  35. from numpy.core._internal import recursive
  36. from numpy.compat import pickle
  37. __all__ = [
  38. 'MAError', 'MaskError', 'MaskType', 'MaskedArray', 'abs', 'absolute',
  39. 'add', 'all', 'allclose', 'allequal', 'alltrue', 'amax', 'amin',
  40. 'angle', 'anom', 'anomalies', 'any', 'append', 'arange', 'arccos',
  41. 'arccosh', 'arcsin', 'arcsinh', 'arctan', 'arctan2', 'arctanh',
  42. 'argmax', 'argmin', 'argsort', 'around', 'array', 'asanyarray',
  43. 'asarray', 'bitwise_and', 'bitwise_or', 'bitwise_xor', 'bool_', 'ceil',
  44. 'choose', 'clip', 'common_fill_value', 'compress', 'compressed',
  45. 'concatenate', 'conjugate', 'convolve', 'copy', 'correlate', 'cos', 'cosh',
  46. 'count', 'cumprod', 'cumsum', 'default_fill_value', 'diag', 'diagonal',
  47. 'diff', 'divide', 'empty', 'empty_like', 'equal', 'exp',
  48. 'expand_dims', 'fabs', 'filled', 'fix_invalid', 'flatten_mask',
  49. 'flatten_structured_array', 'floor', 'floor_divide', 'fmod',
  50. 'frombuffer', 'fromflex', 'fromfunction', 'getdata', 'getmask',
  51. 'getmaskarray', 'greater', 'greater_equal', 'harden_mask', 'hypot',
  52. 'identity', 'ids', 'indices', 'inner', 'innerproduct', 'isMA',
  53. 'isMaskedArray', 'is_mask', 'is_masked', 'isarray', 'left_shift',
  54. 'less', 'less_equal', 'log', 'log10', 'log2',
  55. 'logical_and', 'logical_not', 'logical_or', 'logical_xor', 'make_mask',
  56. 'make_mask_descr', 'make_mask_none', 'mask_or', 'masked',
  57. 'masked_array', 'masked_equal', 'masked_greater',
  58. 'masked_greater_equal', 'masked_inside', 'masked_invalid',
  59. 'masked_less', 'masked_less_equal', 'masked_not_equal',
  60. 'masked_object', 'masked_outside', 'masked_print_option',
  61. 'masked_singleton', 'masked_values', 'masked_where', 'max', 'maximum',
  62. 'maximum_fill_value', 'mean', 'min', 'minimum', 'minimum_fill_value',
  63. 'mod', 'multiply', 'mvoid', 'ndim', 'negative', 'nomask', 'nonzero',
  64. 'not_equal', 'ones', 'outer', 'outerproduct', 'power', 'prod',
  65. 'product', 'ptp', 'put', 'putmask', 'ravel', 'remainder',
  66. 'repeat', 'reshape', 'resize', 'right_shift', 'round', 'round_',
  67. 'set_fill_value', 'shape', 'sin', 'sinh', 'size', 'soften_mask',
  68. 'sometrue', 'sort', 'sqrt', 'squeeze', 'std', 'subtract', 'sum',
  69. 'swapaxes', 'take', 'tan', 'tanh', 'trace', 'transpose', 'true_divide',
  70. 'var', 'where', 'zeros',
  71. ]
  72. MaskType = np.bool_
  73. nomask = MaskType(0)
  74. class MaskedArrayFutureWarning(FutureWarning):
  75. pass
  76. def _deprecate_argsort_axis(arr):
  77. """
  78. Adjust the axis passed to argsort, warning if necessary
  79. Parameters
  80. ----------
  81. arr
  82. The array which argsort was called on
  83. np.ma.argsort has a long-term bug where the default of the axis argument
  84. is wrong (gh-8701), which now must be kept for backwards compatibility.
  85. Thankfully, this only makes a difference when arrays are 2- or more-
  86. dimensional, so we only need a warning then.
  87. """
  88. if arr.ndim <= 1:
  89. # no warning needed - but switch to -1 anyway, to avoid surprising
  90. # subclasses, which are more likely to implement scalar axes.
  91. return -1
  92. else:
  93. # 2017-04-11, Numpy 1.13.0, gh-8701: warn on axis default
  94. warnings.warn(
  95. "In the future the default for argsort will be axis=-1, not the "
  96. "current None, to match its documentation and np.argsort. "
  97. "Explicitly pass -1 or None to silence this warning.",
  98. MaskedArrayFutureWarning, stacklevel=3)
  99. return None
  100. def doc_note(initialdoc, note):
  101. """
  102. Adds a Notes section to an existing docstring.
  103. """
  104. if initialdoc is None:
  105. return
  106. if note is None:
  107. return initialdoc
  108. notesplit = re.split(r'\n\s*?Notes\n\s*?-----', inspect.cleandoc(initialdoc))
  109. notedoc = "\n\nNotes\n-----\n%s\n" % inspect.cleandoc(note)
  110. return ''.join(notesplit[:1] + [notedoc] + notesplit[1:])
  111. def get_object_signature(obj):
  112. """
  113. Get the signature from obj
  114. """
  115. try:
  116. sig = formatargspec(*getargspec(obj))
  117. except TypeError:
  118. sig = ''
  119. return sig
  120. ###############################################################################
  121. # Exceptions #
  122. ###############################################################################
  123. class MAError(Exception):
  124. """
  125. Class for masked array related errors.
  126. """
  127. pass
  128. class MaskError(MAError):
  129. """
  130. Class for mask related errors.
  131. """
  132. pass
  133. ###############################################################################
  134. # Filling options #
  135. ###############################################################################
  136. # b: boolean - c: complex - f: floats - i: integer - O: object - S: string
  137. default_filler = {'b': True,
  138. 'c': 1.e20 + 0.0j,
  139. 'f': 1.e20,
  140. 'i': 999999,
  141. 'O': '?',
  142. 'S': b'N/A',
  143. 'u': 999999,
  144. 'V': b'???',
  145. 'U': u'N/A'
  146. }
  147. # Add datetime64 and timedelta64 types
  148. for v in ["Y", "M", "W", "D", "h", "m", "s", "ms", "us", "ns", "ps",
  149. "fs", "as"]:
  150. default_filler["M8[" + v + "]"] = np.datetime64("NaT", v)
  151. default_filler["m8[" + v + "]"] = np.timedelta64("NaT", v)
  152. float_types_list = [np.half, np.single, np.double, np.longdouble,
  153. np.csingle, np.cdouble, np.clongdouble]
  154. max_filler = ntypes._minvals
  155. max_filler.update([(k, -np.inf) for k in float_types_list[:4]])
  156. max_filler.update([(k, complex(-np.inf, -np.inf)) for k in float_types_list[-3:]])
  157. min_filler = ntypes._maxvals
  158. min_filler.update([(k, +np.inf) for k in float_types_list[:4]])
  159. min_filler.update([(k, complex(+np.inf, +np.inf)) for k in float_types_list[-3:]])
  160. del float_types_list
  161. def _recursive_fill_value(dtype, f):
  162. """
  163. Recursively produce a fill value for `dtype`, calling f on scalar dtypes
  164. """
  165. if dtype.names is not None:
  166. vals = tuple(_recursive_fill_value(dtype[name], f) for name in dtype.names)
  167. return np.array(vals, dtype=dtype)[()] # decay to void scalar from 0d
  168. elif dtype.subdtype:
  169. subtype, shape = dtype.subdtype
  170. subval = _recursive_fill_value(subtype, f)
  171. return np.full(shape, subval)
  172. else:
  173. return f(dtype)
  174. def _get_dtype_of(obj):
  175. """ Convert the argument for *_fill_value into a dtype """
  176. if isinstance(obj, np.dtype):
  177. return obj
  178. elif hasattr(obj, 'dtype'):
  179. return obj.dtype
  180. else:
  181. return np.asanyarray(obj).dtype
  182. def default_fill_value(obj):
  183. """
  184. Return the default fill value for the argument object.
  185. The default filling value depends on the datatype of the input
  186. array or the type of the input scalar:
  187. ======== ========
  188. datatype default
  189. ======== ========
  190. bool True
  191. int 999999
  192. float 1.e20
  193. complex 1.e20+0j
  194. object '?'
  195. string 'N/A'
  196. ======== ========
  197. For structured types, a structured scalar is returned, with each field the
  198. default fill value for its type.
  199. For subarray types, the fill value is an array of the same size containing
  200. the default scalar fill value.
  201. Parameters
  202. ----------
  203. obj : ndarray, dtype or scalar
  204. The array data-type or scalar for which the default fill value
  205. is returned.
  206. Returns
  207. -------
  208. fill_value : scalar
  209. The default fill value.
  210. Examples
  211. --------
  212. >>> np.ma.default_fill_value(1)
  213. 999999
  214. >>> np.ma.default_fill_value(np.array([1.1, 2., np.pi]))
  215. 1e+20
  216. >>> np.ma.default_fill_value(np.dtype(complex))
  217. (1e+20+0j)
  218. """
  219. def _scalar_fill_value(dtype):
  220. if dtype.kind in 'Mm':
  221. return default_filler.get(dtype.str[1:], '?')
  222. else:
  223. return default_filler.get(dtype.kind, '?')
  224. dtype = _get_dtype_of(obj)
  225. return _recursive_fill_value(dtype, _scalar_fill_value)
  226. def _extremum_fill_value(obj, extremum, extremum_name):
  227. def _scalar_fill_value(dtype):
  228. try:
  229. return extremum[dtype]
  230. except KeyError as e:
  231. raise TypeError(
  232. f"Unsuitable type {dtype} for calculating {extremum_name}."
  233. ) from None
  234. dtype = _get_dtype_of(obj)
  235. return _recursive_fill_value(dtype, _scalar_fill_value)
  236. def minimum_fill_value(obj):
  237. """
  238. Return the maximum value that can be represented by the dtype of an object.
  239. This function is useful for calculating a fill value suitable for
  240. taking the minimum of an array with a given dtype.
  241. Parameters
  242. ----------
  243. obj : ndarray, dtype or scalar
  244. An object that can be queried for it's numeric type.
  245. Returns
  246. -------
  247. val : scalar
  248. The maximum representable value.
  249. Raises
  250. ------
  251. TypeError
  252. If `obj` isn't a suitable numeric type.
  253. See Also
  254. --------
  255. maximum_fill_value : The inverse function.
  256. set_fill_value : Set the filling value of a masked array.
  257. MaskedArray.fill_value : Return current fill value.
  258. Examples
  259. --------
  260. >>> import numpy.ma as ma
  261. >>> a = np.int8()
  262. >>> ma.minimum_fill_value(a)
  263. 127
  264. >>> a = np.int32()
  265. >>> ma.minimum_fill_value(a)
  266. 2147483647
  267. An array of numeric data can also be passed.
  268. >>> a = np.array([1, 2, 3], dtype=np.int8)
  269. >>> ma.minimum_fill_value(a)
  270. 127
  271. >>> a = np.array([1, 2, 3], dtype=np.float32)
  272. >>> ma.minimum_fill_value(a)
  273. inf
  274. """
  275. return _extremum_fill_value(obj, min_filler, "minimum")
  276. def maximum_fill_value(obj):
  277. """
  278. Return the minimum value that can be represented by the dtype of an object.
  279. This function is useful for calculating a fill value suitable for
  280. taking the maximum of an array with a given dtype.
  281. Parameters
  282. ----------
  283. obj : ndarray, dtype or scalar
  284. An object that can be queried for it's numeric type.
  285. Returns
  286. -------
  287. val : scalar
  288. The minimum representable value.
  289. Raises
  290. ------
  291. TypeError
  292. If `obj` isn't a suitable numeric type.
  293. See Also
  294. --------
  295. minimum_fill_value : The inverse function.
  296. set_fill_value : Set the filling value of a masked array.
  297. MaskedArray.fill_value : Return current fill value.
  298. Examples
  299. --------
  300. >>> import numpy.ma as ma
  301. >>> a = np.int8()
  302. >>> ma.maximum_fill_value(a)
  303. -128
  304. >>> a = np.int32()
  305. >>> ma.maximum_fill_value(a)
  306. -2147483648
  307. An array of numeric data can also be passed.
  308. >>> a = np.array([1, 2, 3], dtype=np.int8)
  309. >>> ma.maximum_fill_value(a)
  310. -128
  311. >>> a = np.array([1, 2, 3], dtype=np.float32)
  312. >>> ma.maximum_fill_value(a)
  313. -inf
  314. """
  315. return _extremum_fill_value(obj, max_filler, "maximum")
  316. def _recursive_set_fill_value(fillvalue, dt):
  317. """
  318. Create a fill value for a structured dtype.
  319. Parameters
  320. ----------
  321. fillvalue: scalar or array_like
  322. Scalar or array representing the fill value. If it is of shorter
  323. length than the number of fields in dt, it will be resized.
  324. dt: dtype
  325. The structured dtype for which to create the fill value.
  326. Returns
  327. -------
  328. val: tuple
  329. A tuple of values corresponding to the structured fill value.
  330. """
  331. fillvalue = np.resize(fillvalue, len(dt.names))
  332. output_value = []
  333. for (fval, name) in zip(fillvalue, dt.names):
  334. cdtype = dt[name]
  335. if cdtype.subdtype:
  336. cdtype = cdtype.subdtype[0]
  337. if cdtype.names is not None:
  338. output_value.append(tuple(_recursive_set_fill_value(fval, cdtype)))
  339. else:
  340. output_value.append(np.array(fval, dtype=cdtype).item())
  341. return tuple(output_value)
  342. def _check_fill_value(fill_value, ndtype):
  343. """
  344. Private function validating the given `fill_value` for the given dtype.
  345. If fill_value is None, it is set to the default corresponding to the dtype.
  346. If fill_value is not None, its value is forced to the given dtype.
  347. The result is always a 0d array.
  348. """
  349. ndtype = np.dtype(ndtype)
  350. if fill_value is None:
  351. fill_value = default_fill_value(ndtype)
  352. elif ndtype.names is not None:
  353. if isinstance(fill_value, (ndarray, np.void)):
  354. try:
  355. fill_value = np.array(fill_value, copy=False, dtype=ndtype)
  356. except ValueError as e:
  357. err_msg = "Unable to transform %s to dtype %s"
  358. raise ValueError(err_msg % (fill_value, ndtype)) from e
  359. else:
  360. fill_value = np.asarray(fill_value, dtype=object)
  361. fill_value = np.array(_recursive_set_fill_value(fill_value, ndtype),
  362. dtype=ndtype)
  363. else:
  364. if isinstance(fill_value, str) and (ndtype.char not in 'OSVU'):
  365. # Note this check doesn't work if fill_value is not a scalar
  366. err_msg = "Cannot set fill value of string with array of dtype %s"
  367. raise TypeError(err_msg % ndtype)
  368. else:
  369. # In case we want to convert 1e20 to int.
  370. # Also in case of converting string arrays.
  371. try:
  372. fill_value = np.array(fill_value, copy=False, dtype=ndtype)
  373. except (OverflowError, ValueError) as e:
  374. # Raise TypeError instead of OverflowError or ValueError.
  375. # OverflowError is seldom used, and the real problem here is
  376. # that the passed fill_value is not compatible with the ndtype.
  377. err_msg = "Cannot convert fill_value %s to dtype %s"
  378. raise TypeError(err_msg % (fill_value, ndtype)) from e
  379. return np.array(fill_value)
  380. def set_fill_value(a, fill_value):
  381. """
  382. Set the filling value of a, if a is a masked array.
  383. This function changes the fill value of the masked array `a` in place.
  384. If `a` is not a masked array, the function returns silently, without
  385. doing anything.
  386. Parameters
  387. ----------
  388. a : array_like
  389. Input array.
  390. fill_value : dtype
  391. Filling value. A consistency test is performed to make sure
  392. the value is compatible with the dtype of `a`.
  393. Returns
  394. -------
  395. None
  396. Nothing returned by this function.
  397. See Also
  398. --------
  399. maximum_fill_value : Return the default fill value for a dtype.
  400. MaskedArray.fill_value : Return current fill value.
  401. MaskedArray.set_fill_value : Equivalent method.
  402. Examples
  403. --------
  404. >>> import numpy.ma as ma
  405. >>> a = np.arange(5)
  406. >>> a
  407. array([0, 1, 2, 3, 4])
  408. >>> a = ma.masked_where(a < 3, a)
  409. >>> a
  410. masked_array(data=[--, --, --, 3, 4],
  411. mask=[ True, True, True, False, False],
  412. fill_value=999999)
  413. >>> ma.set_fill_value(a, -999)
  414. >>> a
  415. masked_array(data=[--, --, --, 3, 4],
  416. mask=[ True, True, True, False, False],
  417. fill_value=-999)
  418. Nothing happens if `a` is not a masked array.
  419. >>> a = list(range(5))
  420. >>> a
  421. [0, 1, 2, 3, 4]
  422. >>> ma.set_fill_value(a, 100)
  423. >>> a
  424. [0, 1, 2, 3, 4]
  425. >>> a = np.arange(5)
  426. >>> a
  427. array([0, 1, 2, 3, 4])
  428. >>> ma.set_fill_value(a, 100)
  429. >>> a
  430. array([0, 1, 2, 3, 4])
  431. """
  432. if isinstance(a, MaskedArray):
  433. a.set_fill_value(fill_value)
  434. return
  435. def get_fill_value(a):
  436. """
  437. Return the filling value of a, if any. Otherwise, returns the
  438. default filling value for that type.
  439. """
  440. if isinstance(a, MaskedArray):
  441. result = a.fill_value
  442. else:
  443. result = default_fill_value(a)
  444. return result
  445. def common_fill_value(a, b):
  446. """
  447. Return the common filling value of two masked arrays, if any.
  448. If ``a.fill_value == b.fill_value``, return the fill value,
  449. otherwise return None.
  450. Parameters
  451. ----------
  452. a, b : MaskedArray
  453. The masked arrays for which to compare fill values.
  454. Returns
  455. -------
  456. fill_value : scalar or None
  457. The common fill value, or None.
  458. Examples
  459. --------
  460. >>> x = np.ma.array([0, 1.], fill_value=3)
  461. >>> y = np.ma.array([0, 1.], fill_value=3)
  462. >>> np.ma.common_fill_value(x, y)
  463. 3.0
  464. """
  465. t1 = get_fill_value(a)
  466. t2 = get_fill_value(b)
  467. if t1 == t2:
  468. return t1
  469. return None
  470. def filled(a, fill_value=None):
  471. """
  472. Return input as an array with masked data replaced by a fill value.
  473. If `a` is not a `MaskedArray`, `a` itself is returned.
  474. If `a` is a `MaskedArray` and `fill_value` is None, `fill_value` is set to
  475. ``a.fill_value``.
  476. Parameters
  477. ----------
  478. a : MaskedArray or array_like
  479. An input object.
  480. fill_value : array_like, optional.
  481. Can be scalar or non-scalar. If non-scalar, the
  482. resulting filled array should be broadcastable
  483. over input array. Default is None.
  484. Returns
  485. -------
  486. a : ndarray
  487. The filled array.
  488. See Also
  489. --------
  490. compressed
  491. Examples
  492. --------
  493. >>> x = np.ma.array(np.arange(9).reshape(3, 3), mask=[[1, 0, 0],
  494. ... [1, 0, 0],
  495. ... [0, 0, 0]])
  496. >>> x.filled()
  497. array([[999999, 1, 2],
  498. [999999, 4, 5],
  499. [ 6, 7, 8]])
  500. >>> x.filled(fill_value=333)
  501. array([[333, 1, 2],
  502. [333, 4, 5],
  503. [ 6, 7, 8]])
  504. >>> x.filled(fill_value=np.arange(3))
  505. array([[0, 1, 2],
  506. [0, 4, 5],
  507. [6, 7, 8]])
  508. """
  509. if hasattr(a, 'filled'):
  510. return a.filled(fill_value)
  511. elif isinstance(a, ndarray):
  512. # Should we check for contiguity ? and a.flags['CONTIGUOUS']:
  513. return a
  514. elif isinstance(a, dict):
  515. return np.array(a, 'O')
  516. else:
  517. return np.array(a)
  518. def get_masked_subclass(*arrays):
  519. """
  520. Return the youngest subclass of MaskedArray from a list of (masked) arrays.
  521. In case of siblings, the first listed takes over.
  522. """
  523. if len(arrays) == 1:
  524. arr = arrays[0]
  525. if isinstance(arr, MaskedArray):
  526. rcls = type(arr)
  527. else:
  528. rcls = MaskedArray
  529. else:
  530. arrcls = [type(a) for a in arrays]
  531. rcls = arrcls[0]
  532. if not issubclass(rcls, MaskedArray):
  533. rcls = MaskedArray
  534. for cls in arrcls[1:]:
  535. if issubclass(cls, rcls):
  536. rcls = cls
  537. # Don't return MaskedConstant as result: revert to MaskedArray
  538. if rcls.__name__ == 'MaskedConstant':
  539. return MaskedArray
  540. return rcls
  541. def getdata(a, subok=True):
  542. """
  543. Return the data of a masked array as an ndarray.
  544. Return the data of `a` (if any) as an ndarray if `a` is a ``MaskedArray``,
  545. else return `a` as a ndarray or subclass (depending on `subok`) if not.
  546. Parameters
  547. ----------
  548. a : array_like
  549. Input ``MaskedArray``, alternatively a ndarray or a subclass thereof.
  550. subok : bool
  551. Whether to force the output to be a `pure` ndarray (False) or to
  552. return a subclass of ndarray if appropriate (True, default).
  553. See Also
  554. --------
  555. getmask : Return the mask of a masked array, or nomask.
  556. getmaskarray : Return the mask of a masked array, or full array of False.
  557. Examples
  558. --------
  559. >>> import numpy.ma as ma
  560. >>> a = ma.masked_equal([[1,2],[3,4]], 2)
  561. >>> a
  562. masked_array(
  563. data=[[1, --],
  564. [3, 4]],
  565. mask=[[False, True],
  566. [False, False]],
  567. fill_value=2)
  568. >>> ma.getdata(a)
  569. array([[1, 2],
  570. [3, 4]])
  571. Equivalently use the ``MaskedArray`` `data` attribute.
  572. >>> a.data
  573. array([[1, 2],
  574. [3, 4]])
  575. """
  576. try:
  577. data = a._data
  578. except AttributeError:
  579. data = np.array(a, copy=False, subok=subok)
  580. if not subok:
  581. return data.view(ndarray)
  582. return data
  583. get_data = getdata
  584. def fix_invalid(a, mask=nomask, copy=True, fill_value=None):
  585. """
  586. Return input with invalid data masked and replaced by a fill value.
  587. Invalid data means values of `nan`, `inf`, etc.
  588. Parameters
  589. ----------
  590. a : array_like
  591. Input array, a (subclass of) ndarray.
  592. mask : sequence, optional
  593. Mask. Must be convertible to an array of booleans with the same
  594. shape as `data`. True indicates a masked (i.e. invalid) data.
  595. copy : bool, optional
  596. Whether to use a copy of `a` (True) or to fix `a` in place (False).
  597. Default is True.
  598. fill_value : scalar, optional
  599. Value used for fixing invalid data. Default is None, in which case
  600. the ``a.fill_value`` is used.
  601. Returns
  602. -------
  603. b : MaskedArray
  604. The input array with invalid entries fixed.
  605. Notes
  606. -----
  607. A copy is performed by default.
  608. Examples
  609. --------
  610. >>> x = np.ma.array([1., -1, np.nan, np.inf], mask=[1] + [0]*3)
  611. >>> x
  612. masked_array(data=[--, -1.0, nan, inf],
  613. mask=[ True, False, False, False],
  614. fill_value=1e+20)
  615. >>> np.ma.fix_invalid(x)
  616. masked_array(data=[--, -1.0, --, --],
  617. mask=[ True, False, True, True],
  618. fill_value=1e+20)
  619. >>> fixed = np.ma.fix_invalid(x)
  620. >>> fixed.data
  621. array([ 1.e+00, -1.e+00, 1.e+20, 1.e+20])
  622. >>> x.data
  623. array([ 1., -1., nan, inf])
  624. """
  625. a = masked_array(a, copy=copy, mask=mask, subok=True)
  626. invalid = np.logical_not(np.isfinite(a._data))
  627. if not invalid.any():
  628. return a
  629. a._mask |= invalid
  630. if fill_value is None:
  631. fill_value = a.fill_value
  632. a._data[invalid] = fill_value
  633. return a
  634. def is_string_or_list_of_strings(val):
  635. return (isinstance(val, str) or
  636. (isinstance(val, list) and val and
  637. builtins.all(isinstance(s, str) for s in val)))
  638. ###############################################################################
  639. # Ufuncs #
  640. ###############################################################################
  641. ufunc_domain = {}
  642. ufunc_fills = {}
  643. class _DomainCheckInterval:
  644. """
  645. Define a valid interval, so that :
  646. ``domain_check_interval(a,b)(x) == True`` where
  647. ``x < a`` or ``x > b``.
  648. """
  649. def __init__(self, a, b):
  650. "domain_check_interval(a,b)(x) = true where x < a or y > b"
  651. if a > b:
  652. (a, b) = (b, a)
  653. self.a = a
  654. self.b = b
  655. def __call__(self, x):
  656. "Execute the call behavior."
  657. # nans at masked positions cause RuntimeWarnings, even though
  658. # they are masked. To avoid this we suppress warnings.
  659. with np.errstate(invalid='ignore'):
  660. return umath.logical_or(umath.greater(x, self.b),
  661. umath.less(x, self.a))
  662. class _DomainTan:
  663. """
  664. Define a valid interval for the `tan` function, so that:
  665. ``domain_tan(eps) = True`` where ``abs(cos(x)) < eps``
  666. """
  667. def __init__(self, eps):
  668. "domain_tan(eps) = true where abs(cos(x)) < eps)"
  669. self.eps = eps
  670. def __call__(self, x):
  671. "Executes the call behavior."
  672. with np.errstate(invalid='ignore'):
  673. return umath.less(umath.absolute(umath.cos(x)), self.eps)
  674. class _DomainSafeDivide:
  675. """
  676. Define a domain for safe division.
  677. """
  678. def __init__(self, tolerance=None):
  679. self.tolerance = tolerance
  680. def __call__(self, a, b):
  681. # Delay the selection of the tolerance to here in order to reduce numpy
  682. # import times. The calculation of these parameters is a substantial
  683. # component of numpy's import time.
  684. if self.tolerance is None:
  685. self.tolerance = np.finfo(float).tiny
  686. # don't call ma ufuncs from __array_wrap__ which would fail for scalars
  687. a, b = np.asarray(a), np.asarray(b)
  688. with np.errstate(invalid='ignore'):
  689. return umath.absolute(a) * self.tolerance >= umath.absolute(b)
  690. class _DomainGreater:
  691. """
  692. DomainGreater(v)(x) is True where x <= v.
  693. """
  694. def __init__(self, critical_value):
  695. "DomainGreater(v)(x) = true where x <= v"
  696. self.critical_value = critical_value
  697. def __call__(self, x):
  698. "Executes the call behavior."
  699. with np.errstate(invalid='ignore'):
  700. return umath.less_equal(x, self.critical_value)
  701. class _DomainGreaterEqual:
  702. """
  703. DomainGreaterEqual(v)(x) is True where x < v.
  704. """
  705. def __init__(self, critical_value):
  706. "DomainGreaterEqual(v)(x) = true where x < v"
  707. self.critical_value = critical_value
  708. def __call__(self, x):
  709. "Executes the call behavior."
  710. with np.errstate(invalid='ignore'):
  711. return umath.less(x, self.critical_value)
  712. class _MaskedUFunc:
  713. def __init__(self, ufunc):
  714. self.f = ufunc
  715. self.__doc__ = ufunc.__doc__
  716. self.__name__ = ufunc.__name__
  717. def __str__(self):
  718. return f"Masked version of {self.f}"
  719. class _MaskedUnaryOperation(_MaskedUFunc):
  720. """
  721. Defines masked version of unary operations, where invalid values are
  722. pre-masked.
  723. Parameters
  724. ----------
  725. mufunc : callable
  726. The function for which to define a masked version. Made available
  727. as ``_MaskedUnaryOperation.f``.
  728. fill : scalar, optional
  729. Filling value, default is 0.
  730. domain : class instance
  731. Domain for the function. Should be one of the ``_Domain*``
  732. classes. Default is None.
  733. """
  734. def __init__(self, mufunc, fill=0, domain=None):
  735. super(_MaskedUnaryOperation, self).__init__(mufunc)
  736. self.fill = fill
  737. self.domain = domain
  738. ufunc_domain[mufunc] = domain
  739. ufunc_fills[mufunc] = fill
  740. def __call__(self, a, *args, **kwargs):
  741. """
  742. Execute the call behavior.
  743. """
  744. d = getdata(a)
  745. # Deal with domain
  746. if self.domain is not None:
  747. # Case 1.1. : Domained function
  748. # nans at masked positions cause RuntimeWarnings, even though
  749. # they are masked. To avoid this we suppress warnings.
  750. with np.errstate(divide='ignore', invalid='ignore'):
  751. result = self.f(d, *args, **kwargs)
  752. # Make a mask
  753. m = ~umath.isfinite(result)
  754. m |= self.domain(d)
  755. m |= getmask(a)
  756. else:
  757. # Case 1.2. : Function without a domain
  758. # Get the result and the mask
  759. with np.errstate(divide='ignore', invalid='ignore'):
  760. result = self.f(d, *args, **kwargs)
  761. m = getmask(a)
  762. if not result.ndim:
  763. # Case 2.1. : The result is scalarscalar
  764. if m:
  765. return masked
  766. return result
  767. if m is not nomask:
  768. # Case 2.2. The result is an array
  769. # We need to fill the invalid data back w/ the input Now,
  770. # that's plain silly: in C, we would just skip the element and
  771. # keep the original, but we do have to do it that way in Python
  772. # In case result has a lower dtype than the inputs (as in
  773. # equal)
  774. try:
  775. np.copyto(result, d, where=m)
  776. except TypeError:
  777. pass
  778. # Transform to
  779. masked_result = result.view(get_masked_subclass(a))
  780. masked_result._mask = m
  781. masked_result._update_from(a)
  782. return masked_result
  783. class _MaskedBinaryOperation(_MaskedUFunc):
  784. """
  785. Define masked version of binary operations, where invalid
  786. values are pre-masked.
  787. Parameters
  788. ----------
  789. mbfunc : function
  790. The function for which to define a masked version. Made available
  791. as ``_MaskedBinaryOperation.f``.
  792. domain : class instance
  793. Default domain for the function. Should be one of the ``_Domain*``
  794. classes. Default is None.
  795. fillx : scalar, optional
  796. Filling value for the first argument, default is 0.
  797. filly : scalar, optional
  798. Filling value for the second argument, default is 0.
  799. """
  800. def __init__(self, mbfunc, fillx=0, filly=0):
  801. """
  802. abfunc(fillx, filly) must be defined.
  803. abfunc(x, filly) = x for all x to enable reduce.
  804. """
  805. super(_MaskedBinaryOperation, self).__init__(mbfunc)
  806. self.fillx = fillx
  807. self.filly = filly
  808. ufunc_domain[mbfunc] = None
  809. ufunc_fills[mbfunc] = (fillx, filly)
  810. def __call__(self, a, b, *args, **kwargs):
  811. """
  812. Execute the call behavior.
  813. """
  814. # Get the data, as ndarray
  815. (da, db) = (getdata(a), getdata(b))
  816. # Get the result
  817. with np.errstate():
  818. np.seterr(divide='ignore', invalid='ignore')
  819. result = self.f(da, db, *args, **kwargs)
  820. # Get the mask for the result
  821. (ma, mb) = (getmask(a), getmask(b))
  822. if ma is nomask:
  823. if mb is nomask:
  824. m = nomask
  825. else:
  826. m = umath.logical_or(getmaskarray(a), mb)
  827. elif mb is nomask:
  828. m = umath.logical_or(ma, getmaskarray(b))
  829. else:
  830. m = umath.logical_or(ma, mb)
  831. # Case 1. : scalar
  832. if not result.ndim:
  833. if m:
  834. return masked
  835. return result
  836. # Case 2. : array
  837. # Revert result to da where masked
  838. if m is not nomask and m.any():
  839. # any errors, just abort; impossible to guarantee masked values
  840. try:
  841. np.copyto(result, da, casting='unsafe', where=m)
  842. except Exception:
  843. pass
  844. # Transforms to a (subclass of) MaskedArray
  845. masked_result = result.view(get_masked_subclass(a, b))
  846. masked_result._mask = m
  847. if isinstance(a, MaskedArray):
  848. masked_result._update_from(a)
  849. elif isinstance(b, MaskedArray):
  850. masked_result._update_from(b)
  851. return masked_result
  852. def reduce(self, target, axis=0, dtype=None):
  853. """
  854. Reduce `target` along the given `axis`.
  855. """
  856. tclass = get_masked_subclass(target)
  857. m = getmask(target)
  858. t = filled(target, self.filly)
  859. if t.shape == ():
  860. t = t.reshape(1)
  861. if m is not nomask:
  862. m = make_mask(m, copy=True)
  863. m.shape = (1,)
  864. if m is nomask:
  865. tr = self.f.reduce(t, axis)
  866. mr = nomask
  867. else:
  868. tr = self.f.reduce(t, axis, dtype=dtype or t.dtype)
  869. mr = umath.logical_and.reduce(m, axis)
  870. if not tr.shape:
  871. if mr:
  872. return masked
  873. else:
  874. return tr
  875. masked_tr = tr.view(tclass)
  876. masked_tr._mask = mr
  877. return masked_tr
  878. def outer(self, a, b):
  879. """
  880. Return the function applied to the outer product of a and b.
  881. """
  882. (da, db) = (getdata(a), getdata(b))
  883. d = self.f.outer(da, db)
  884. ma = getmask(a)
  885. mb = getmask(b)
  886. if ma is nomask and mb is nomask:
  887. m = nomask
  888. else:
  889. ma = getmaskarray(a)
  890. mb = getmaskarray(b)
  891. m = umath.logical_or.outer(ma, mb)
  892. if (not m.ndim) and m:
  893. return masked
  894. if m is not nomask:
  895. np.copyto(d, da, where=m)
  896. if not d.shape:
  897. return d
  898. masked_d = d.view(get_masked_subclass(a, b))
  899. masked_d._mask = m
  900. return masked_d
  901. def accumulate(self, target, axis=0):
  902. """Accumulate `target` along `axis` after filling with y fill
  903. value.
  904. """
  905. tclass = get_masked_subclass(target)
  906. t = filled(target, self.filly)
  907. result = self.f.accumulate(t, axis)
  908. masked_result = result.view(tclass)
  909. return masked_result
  910. class _DomainedBinaryOperation(_MaskedUFunc):
  911. """
  912. Define binary operations that have a domain, like divide.
  913. They have no reduce, outer or accumulate.
  914. Parameters
  915. ----------
  916. mbfunc : function
  917. The function for which to define a masked version. Made available
  918. as ``_DomainedBinaryOperation.f``.
  919. domain : class instance
  920. Default domain for the function. Should be one of the ``_Domain*``
  921. classes.
  922. fillx : scalar, optional
  923. Filling value for the first argument, default is 0.
  924. filly : scalar, optional
  925. Filling value for the second argument, default is 0.
  926. """
  927. def __init__(self, dbfunc, domain, fillx=0, filly=0):
  928. """abfunc(fillx, filly) must be defined.
  929. abfunc(x, filly) = x for all x to enable reduce.
  930. """
  931. super(_DomainedBinaryOperation, self).__init__(dbfunc)
  932. self.domain = domain
  933. self.fillx = fillx
  934. self.filly = filly
  935. ufunc_domain[dbfunc] = domain
  936. ufunc_fills[dbfunc] = (fillx, filly)
  937. def __call__(self, a, b, *args, **kwargs):
  938. "Execute the call behavior."
  939. # Get the data
  940. (da, db) = (getdata(a), getdata(b))
  941. # Get the result
  942. with np.errstate(divide='ignore', invalid='ignore'):
  943. result = self.f(da, db, *args, **kwargs)
  944. # Get the mask as a combination of the source masks and invalid
  945. m = ~umath.isfinite(result)
  946. m |= getmask(a)
  947. m |= getmask(b)
  948. # Apply the domain
  949. domain = ufunc_domain.get(self.f, None)
  950. if domain is not None:
  951. m |= domain(da, db)
  952. # Take care of the scalar case first
  953. if not m.ndim:
  954. if m:
  955. return masked
  956. else:
  957. return result
  958. # When the mask is True, put back da if possible
  959. # any errors, just abort; impossible to guarantee masked values
  960. try:
  961. np.copyto(result, 0, casting='unsafe', where=m)
  962. # avoid using "*" since this may be overlaid
  963. masked_da = umath.multiply(m, da)
  964. # only add back if it can be cast safely
  965. if np.can_cast(masked_da.dtype, result.dtype, casting='safe'):
  966. result += masked_da
  967. except Exception:
  968. pass
  969. # Transforms to a (subclass of) MaskedArray
  970. masked_result = result.view(get_masked_subclass(a, b))
  971. masked_result._mask = m
  972. if isinstance(a, MaskedArray):
  973. masked_result._update_from(a)
  974. elif isinstance(b, MaskedArray):
  975. masked_result._update_from(b)
  976. return masked_result
  977. # Unary ufuncs
  978. exp = _MaskedUnaryOperation(umath.exp)
  979. conjugate = _MaskedUnaryOperation(umath.conjugate)
  980. sin = _MaskedUnaryOperation(umath.sin)
  981. cos = _MaskedUnaryOperation(umath.cos)
  982. arctan = _MaskedUnaryOperation(umath.arctan)
  983. arcsinh = _MaskedUnaryOperation(umath.arcsinh)
  984. sinh = _MaskedUnaryOperation(umath.sinh)
  985. cosh = _MaskedUnaryOperation(umath.cosh)
  986. tanh = _MaskedUnaryOperation(umath.tanh)
  987. abs = absolute = _MaskedUnaryOperation(umath.absolute)
  988. angle = _MaskedUnaryOperation(angle) # from numpy.lib.function_base
  989. fabs = _MaskedUnaryOperation(umath.fabs)
  990. negative = _MaskedUnaryOperation(umath.negative)
  991. floor = _MaskedUnaryOperation(umath.floor)
  992. ceil = _MaskedUnaryOperation(umath.ceil)
  993. around = _MaskedUnaryOperation(np.round_)
  994. logical_not = _MaskedUnaryOperation(umath.logical_not)
  995. # Domained unary ufuncs
  996. sqrt = _MaskedUnaryOperation(umath.sqrt, 0.0,
  997. _DomainGreaterEqual(0.0))
  998. log = _MaskedUnaryOperation(umath.log, 1.0,
  999. _DomainGreater(0.0))
  1000. log2 = _MaskedUnaryOperation(umath.log2, 1.0,
  1001. _DomainGreater(0.0))
  1002. log10 = _MaskedUnaryOperation(umath.log10, 1.0,
  1003. _DomainGreater(0.0))
  1004. tan = _MaskedUnaryOperation(umath.tan, 0.0,
  1005. _DomainTan(1e-35))
  1006. arcsin = _MaskedUnaryOperation(umath.arcsin, 0.0,
  1007. _DomainCheckInterval(-1.0, 1.0))
  1008. arccos = _MaskedUnaryOperation(umath.arccos, 0.0,
  1009. _DomainCheckInterval(-1.0, 1.0))
  1010. arccosh = _MaskedUnaryOperation(umath.arccosh, 1.0,
  1011. _DomainGreaterEqual(1.0))
  1012. arctanh = _MaskedUnaryOperation(umath.arctanh, 0.0,
  1013. _DomainCheckInterval(-1.0 + 1e-15, 1.0 - 1e-15))
  1014. # Binary ufuncs
  1015. add = _MaskedBinaryOperation(umath.add)
  1016. subtract = _MaskedBinaryOperation(umath.subtract)
  1017. multiply = _MaskedBinaryOperation(umath.multiply, 1, 1)
  1018. arctan2 = _MaskedBinaryOperation(umath.arctan2, 0.0, 1.0)
  1019. equal = _MaskedBinaryOperation(umath.equal)
  1020. equal.reduce = None
  1021. not_equal = _MaskedBinaryOperation(umath.not_equal)
  1022. not_equal.reduce = None
  1023. less_equal = _MaskedBinaryOperation(umath.less_equal)
  1024. less_equal.reduce = None
  1025. greater_equal = _MaskedBinaryOperation(umath.greater_equal)
  1026. greater_equal.reduce = None
  1027. less = _MaskedBinaryOperation(umath.less)
  1028. less.reduce = None
  1029. greater = _MaskedBinaryOperation(umath.greater)
  1030. greater.reduce = None
  1031. logical_and = _MaskedBinaryOperation(umath.logical_and)
  1032. alltrue = _MaskedBinaryOperation(umath.logical_and, 1, 1).reduce
  1033. logical_or = _MaskedBinaryOperation(umath.logical_or)
  1034. sometrue = logical_or.reduce
  1035. logical_xor = _MaskedBinaryOperation(umath.logical_xor)
  1036. bitwise_and = _MaskedBinaryOperation(umath.bitwise_and)
  1037. bitwise_or = _MaskedBinaryOperation(umath.bitwise_or)
  1038. bitwise_xor = _MaskedBinaryOperation(umath.bitwise_xor)
  1039. hypot = _MaskedBinaryOperation(umath.hypot)
  1040. # Domained binary ufuncs
  1041. divide = _DomainedBinaryOperation(umath.divide, _DomainSafeDivide(), 0, 1)
  1042. true_divide = _DomainedBinaryOperation(umath.true_divide,
  1043. _DomainSafeDivide(), 0, 1)
  1044. floor_divide = _DomainedBinaryOperation(umath.floor_divide,
  1045. _DomainSafeDivide(), 0, 1)
  1046. remainder = _DomainedBinaryOperation(umath.remainder,
  1047. _DomainSafeDivide(), 0, 1)
  1048. fmod = _DomainedBinaryOperation(umath.fmod, _DomainSafeDivide(), 0, 1)
  1049. mod = _DomainedBinaryOperation(umath.mod, _DomainSafeDivide(), 0, 1)
  1050. ###############################################################################
  1051. # Mask creation functions #
  1052. ###############################################################################
  1053. def _replace_dtype_fields_recursive(dtype, primitive_dtype):
  1054. "Private function allowing recursion in _replace_dtype_fields."
  1055. _recurse = _replace_dtype_fields_recursive
  1056. # Do we have some name fields ?
  1057. if dtype.names is not None:
  1058. descr = []
  1059. for name in dtype.names:
  1060. field = dtype.fields[name]
  1061. if len(field) == 3:
  1062. # Prepend the title to the name
  1063. name = (field[-1], name)
  1064. descr.append((name, _recurse(field[0], primitive_dtype)))
  1065. new_dtype = np.dtype(descr)
  1066. # Is this some kind of composite a la (float,2)
  1067. elif dtype.subdtype:
  1068. descr = list(dtype.subdtype)
  1069. descr[0] = _recurse(dtype.subdtype[0], primitive_dtype)
  1070. new_dtype = np.dtype(tuple(descr))
  1071. # this is a primitive type, so do a direct replacement
  1072. else:
  1073. new_dtype = primitive_dtype
  1074. # preserve identity of dtypes
  1075. if new_dtype == dtype:
  1076. new_dtype = dtype
  1077. return new_dtype
  1078. def _replace_dtype_fields(dtype, primitive_dtype):
  1079. """
  1080. Construct a dtype description list from a given dtype.
  1081. Returns a new dtype object, with all fields and subtypes in the given type
  1082. recursively replaced with `primitive_dtype`.
  1083. Arguments are coerced to dtypes first.
  1084. """
  1085. dtype = np.dtype(dtype)
  1086. primitive_dtype = np.dtype(primitive_dtype)
  1087. return _replace_dtype_fields_recursive(dtype, primitive_dtype)
  1088. def make_mask_descr(ndtype):
  1089. """
  1090. Construct a dtype description list from a given dtype.
  1091. Returns a new dtype object, with the type of all fields in `ndtype` to a
  1092. boolean type. Field names are not altered.
  1093. Parameters
  1094. ----------
  1095. ndtype : dtype
  1096. The dtype to convert.
  1097. Returns
  1098. -------
  1099. result : dtype
  1100. A dtype that looks like `ndtype`, the type of all fields is boolean.
  1101. Examples
  1102. --------
  1103. >>> import numpy.ma as ma
  1104. >>> dtype = np.dtype({'names':['foo', 'bar'],
  1105. ... 'formats':[np.float32, np.int64]})
  1106. >>> dtype
  1107. dtype([('foo', '<f4'), ('bar', '<i8')])
  1108. >>> ma.make_mask_descr(dtype)
  1109. dtype([('foo', '|b1'), ('bar', '|b1')])
  1110. >>> ma.make_mask_descr(np.float32)
  1111. dtype('bool')
  1112. """
  1113. return _replace_dtype_fields(ndtype, MaskType)
  1114. def getmask(a):
  1115. """
  1116. Return the mask of a masked array, or nomask.
  1117. Return the mask of `a` as an ndarray if `a` is a `MaskedArray` and the
  1118. mask is not `nomask`, else return `nomask`. To guarantee a full array
  1119. of booleans of the same shape as a, use `getmaskarray`.
  1120. Parameters
  1121. ----------
  1122. a : array_like
  1123. Input `MaskedArray` for which the mask is required.
  1124. See Also
  1125. --------
  1126. getdata : Return the data of a masked array as an ndarray.
  1127. getmaskarray : Return the mask of a masked array, or full array of False.
  1128. Examples
  1129. --------
  1130. >>> import numpy.ma as ma
  1131. >>> a = ma.masked_equal([[1,2],[3,4]], 2)
  1132. >>> a
  1133. masked_array(
  1134. data=[[1, --],
  1135. [3, 4]],
  1136. mask=[[False, True],
  1137. [False, False]],
  1138. fill_value=2)
  1139. >>> ma.getmask(a)
  1140. array([[False, True],
  1141. [False, False]])
  1142. Equivalently use the `MaskedArray` `mask` attribute.
  1143. >>> a.mask
  1144. array([[False, True],
  1145. [False, False]])
  1146. Result when mask == `nomask`
  1147. >>> b = ma.masked_array([[1,2],[3,4]])
  1148. >>> b
  1149. masked_array(
  1150. data=[[1, 2],
  1151. [3, 4]],
  1152. mask=False,
  1153. fill_value=999999)
  1154. >>> ma.nomask
  1155. False
  1156. >>> ma.getmask(b) == ma.nomask
  1157. True
  1158. >>> b.mask == ma.nomask
  1159. True
  1160. """
  1161. return getattr(a, '_mask', nomask)
  1162. get_mask = getmask
  1163. def getmaskarray(arr):
  1164. """
  1165. Return the mask of a masked array, or full boolean array of False.
  1166. Return the mask of `arr` as an ndarray if `arr` is a `MaskedArray` and
  1167. the mask is not `nomask`, else return a full boolean array of False of
  1168. the same shape as `arr`.
  1169. Parameters
  1170. ----------
  1171. arr : array_like
  1172. Input `MaskedArray` for which the mask is required.
  1173. See Also
  1174. --------
  1175. getmask : Return the mask of a masked array, or nomask.
  1176. getdata : Return the data of a masked array as an ndarray.
  1177. Examples
  1178. --------
  1179. >>> import numpy.ma as ma
  1180. >>> a = ma.masked_equal([[1,2],[3,4]], 2)
  1181. >>> a
  1182. masked_array(
  1183. data=[[1, --],
  1184. [3, 4]],
  1185. mask=[[False, True],
  1186. [False, False]],
  1187. fill_value=2)
  1188. >>> ma.getmaskarray(a)
  1189. array([[False, True],
  1190. [False, False]])
  1191. Result when mask == ``nomask``
  1192. >>> b = ma.masked_array([[1,2],[3,4]])
  1193. >>> b
  1194. masked_array(
  1195. data=[[1, 2],
  1196. [3, 4]],
  1197. mask=False,
  1198. fill_value=999999)
  1199. >>> ma.getmaskarray(b)
  1200. array([[False, False],
  1201. [False, False]])
  1202. """
  1203. mask = getmask(arr)
  1204. if mask is nomask:
  1205. mask = make_mask_none(np.shape(arr), getattr(arr, 'dtype', None))
  1206. return mask
  1207. def is_mask(m):
  1208. """
  1209. Return True if m is a valid, standard mask.
  1210. This function does not check the contents of the input, only that the
  1211. type is MaskType. In particular, this function returns False if the
  1212. mask has a flexible dtype.
  1213. Parameters
  1214. ----------
  1215. m : array_like
  1216. Array to test.
  1217. Returns
  1218. -------
  1219. result : bool
  1220. True if `m.dtype.type` is MaskType, False otherwise.
  1221. See Also
  1222. --------
  1223. ma.isMaskedArray : Test whether input is an instance of MaskedArray.
  1224. Examples
  1225. --------
  1226. >>> import numpy.ma as ma
  1227. >>> m = ma.masked_equal([0, 1, 0, 2, 3], 0)
  1228. >>> m
  1229. masked_array(data=[--, 1, --, 2, 3],
  1230. mask=[ True, False, True, False, False],
  1231. fill_value=0)
  1232. >>> ma.is_mask(m)
  1233. False
  1234. >>> ma.is_mask(m.mask)
  1235. True
  1236. Input must be an ndarray (or have similar attributes)
  1237. for it to be considered a valid mask.
  1238. >>> m = [False, True, False]
  1239. >>> ma.is_mask(m)
  1240. False
  1241. >>> m = np.array([False, True, False])
  1242. >>> m
  1243. array([False, True, False])
  1244. >>> ma.is_mask(m)
  1245. True
  1246. Arrays with complex dtypes don't return True.
  1247. >>> dtype = np.dtype({'names':['monty', 'pithon'],
  1248. ... 'formats':[bool, bool]})
  1249. >>> dtype
  1250. dtype([('monty', '|b1'), ('pithon', '|b1')])
  1251. >>> m = np.array([(True, False), (False, True), (True, False)],
  1252. ... dtype=dtype)
  1253. >>> m
  1254. array([( True, False), (False, True), ( True, False)],
  1255. dtype=[('monty', '?'), ('pithon', '?')])
  1256. >>> ma.is_mask(m)
  1257. False
  1258. """
  1259. try:
  1260. return m.dtype.type is MaskType
  1261. except AttributeError:
  1262. return False
  1263. def _shrink_mask(m):
  1264. """
  1265. Shrink a mask to nomask if possible
  1266. """
  1267. if m.dtype.names is None and not m.any():
  1268. return nomask
  1269. else:
  1270. return m
  1271. def make_mask(m, copy=False, shrink=True, dtype=MaskType):
  1272. """
  1273. Create a boolean mask from an array.
  1274. Return `m` as a boolean mask, creating a copy if necessary or requested.
  1275. The function can accept any sequence that is convertible to integers,
  1276. or ``nomask``. Does not require that contents must be 0s and 1s, values
  1277. of 0 are interpreted as False, everything else as True.
  1278. Parameters
  1279. ----------
  1280. m : array_like
  1281. Potential mask.
  1282. copy : bool, optional
  1283. Whether to return a copy of `m` (True) or `m` itself (False).
  1284. shrink : bool, optional
  1285. Whether to shrink `m` to ``nomask`` if all its values are False.
  1286. dtype : dtype, optional
  1287. Data-type of the output mask. By default, the output mask has a
  1288. dtype of MaskType (bool). If the dtype is flexible, each field has
  1289. a boolean dtype. This is ignored when `m` is ``nomask``, in which
  1290. case ``nomask`` is always returned.
  1291. Returns
  1292. -------
  1293. result : ndarray
  1294. A boolean mask derived from `m`.
  1295. Examples
  1296. --------
  1297. >>> import numpy.ma as ma
  1298. >>> m = [True, False, True, True]
  1299. >>> ma.make_mask(m)
  1300. array([ True, False, True, True])
  1301. >>> m = [1, 0, 1, 1]
  1302. >>> ma.make_mask(m)
  1303. array([ True, False, True, True])
  1304. >>> m = [1, 0, 2, -3]
  1305. >>> ma.make_mask(m)
  1306. array([ True, False, True, True])
  1307. Effect of the `shrink` parameter.
  1308. >>> m = np.zeros(4)
  1309. >>> m
  1310. array([0., 0., 0., 0.])
  1311. >>> ma.make_mask(m)
  1312. False
  1313. >>> ma.make_mask(m, shrink=False)
  1314. array([False, False, False, False])
  1315. Using a flexible `dtype`.
  1316. >>> m = [1, 0, 1, 1]
  1317. >>> n = [0, 1, 0, 0]
  1318. >>> arr = []
  1319. >>> for man, mouse in zip(m, n):
  1320. ... arr.append((man, mouse))
  1321. >>> arr
  1322. [(1, 0), (0, 1), (1, 0), (1, 0)]
  1323. >>> dtype = np.dtype({'names':['man', 'mouse'],
  1324. ... 'formats':[np.int64, np.int64]})
  1325. >>> arr = np.array(arr, dtype=dtype)
  1326. >>> arr
  1327. array([(1, 0), (0, 1), (1, 0), (1, 0)],
  1328. dtype=[('man', '<i8'), ('mouse', '<i8')])
  1329. >>> ma.make_mask(arr, dtype=dtype)
  1330. array([(True, False), (False, True), (True, False), (True, False)],
  1331. dtype=[('man', '|b1'), ('mouse', '|b1')])
  1332. """
  1333. if m is nomask:
  1334. return nomask
  1335. # Make sure the input dtype is valid.
  1336. dtype = make_mask_descr(dtype)
  1337. # legacy boolean special case: "existence of fields implies true"
  1338. if isinstance(m, ndarray) and m.dtype.fields and dtype == np.bool_:
  1339. return np.ones(m.shape, dtype=dtype)
  1340. # Fill the mask in case there are missing data; turn it into an ndarray.
  1341. result = np.array(filled(m, True), copy=copy, dtype=dtype, subok=True)
  1342. # Bas les masques !
  1343. if shrink:
  1344. result = _shrink_mask(result)
  1345. return result
  1346. def make_mask_none(newshape, dtype=None):
  1347. """
  1348. Return a boolean mask of the given shape, filled with False.
  1349. This function returns a boolean ndarray with all entries False, that can
  1350. be used in common mask manipulations. If a complex dtype is specified, the
  1351. type of each field is converted to a boolean type.
  1352. Parameters
  1353. ----------
  1354. newshape : tuple
  1355. A tuple indicating the shape of the mask.
  1356. dtype : {None, dtype}, optional
  1357. If None, use a MaskType instance. Otherwise, use a new datatype with
  1358. the same fields as `dtype`, converted to boolean types.
  1359. Returns
  1360. -------
  1361. result : ndarray
  1362. An ndarray of appropriate shape and dtype, filled with False.
  1363. See Also
  1364. --------
  1365. make_mask : Create a boolean mask from an array.
  1366. make_mask_descr : Construct a dtype description list from a given dtype.
  1367. Examples
  1368. --------
  1369. >>> import numpy.ma as ma
  1370. >>> ma.make_mask_none((3,))
  1371. array([False, False, False])
  1372. Defining a more complex dtype.
  1373. >>> dtype = np.dtype({'names':['foo', 'bar'],
  1374. ... 'formats':[np.float32, np.int64]})
  1375. >>> dtype
  1376. dtype([('foo', '<f4'), ('bar', '<i8')])
  1377. >>> ma.make_mask_none((3,), dtype=dtype)
  1378. array([(False, False), (False, False), (False, False)],
  1379. dtype=[('foo', '|b1'), ('bar', '|b1')])
  1380. """
  1381. if dtype is None:
  1382. result = np.zeros(newshape, dtype=MaskType)
  1383. else:
  1384. result = np.zeros(newshape, dtype=make_mask_descr(dtype))
  1385. return result
  1386. def mask_or(m1, m2, copy=False, shrink=True):
  1387. """
  1388. Combine two masks with the ``logical_or`` operator.
  1389. The result may be a view on `m1` or `m2` if the other is `nomask`
  1390. (i.e. False).
  1391. Parameters
  1392. ----------
  1393. m1, m2 : array_like
  1394. Input masks.
  1395. copy : bool, optional
  1396. If copy is False and one of the inputs is `nomask`, return a view
  1397. of the other input mask. Defaults to False.
  1398. shrink : bool, optional
  1399. Whether to shrink the output to `nomask` if all its values are
  1400. False. Defaults to True.
  1401. Returns
  1402. -------
  1403. mask : output mask
  1404. The result masks values that are masked in either `m1` or `m2`.
  1405. Raises
  1406. ------
  1407. ValueError
  1408. If `m1` and `m2` have different flexible dtypes.
  1409. Examples
  1410. --------
  1411. >>> m1 = np.ma.make_mask([0, 1, 1, 0])
  1412. >>> m2 = np.ma.make_mask([1, 0, 0, 0])
  1413. >>> np.ma.mask_or(m1, m2)
  1414. array([ True, True, True, False])
  1415. """
  1416. @recursive
  1417. def _recursive_mask_or(self, m1, m2, newmask):
  1418. names = m1.dtype.names
  1419. for name in names:
  1420. current1 = m1[name]
  1421. if current1.dtype.names is not None:
  1422. self(current1, m2[name], newmask[name])
  1423. else:
  1424. umath.logical_or(current1, m2[name], newmask[name])
  1425. return
  1426. if (m1 is nomask) or (m1 is False):
  1427. dtype = getattr(m2, 'dtype', MaskType)
  1428. return make_mask(m2, copy=copy, shrink=shrink, dtype=dtype)
  1429. if (m2 is nomask) or (m2 is False):
  1430. dtype = getattr(m1, 'dtype', MaskType)
  1431. return make_mask(m1, copy=copy, shrink=shrink, dtype=dtype)
  1432. if m1 is m2 and is_mask(m1):
  1433. return m1
  1434. (dtype1, dtype2) = (getattr(m1, 'dtype', None), getattr(m2, 'dtype', None))
  1435. if dtype1 != dtype2:
  1436. raise ValueError("Incompatible dtypes '%s'<>'%s'" % (dtype1, dtype2))
  1437. if dtype1.names is not None:
  1438. # Allocate an output mask array with the properly broadcast shape.
  1439. newmask = np.empty(np.broadcast(m1, m2).shape, dtype1)
  1440. _recursive_mask_or(m1, m2, newmask)
  1441. return newmask
  1442. return make_mask(umath.logical_or(m1, m2), copy=copy, shrink=shrink)
  1443. def flatten_mask(mask):
  1444. """
  1445. Returns a completely flattened version of the mask, where nested fields
  1446. are collapsed.
  1447. Parameters
  1448. ----------
  1449. mask : array_like
  1450. Input array, which will be interpreted as booleans.
  1451. Returns
  1452. -------
  1453. flattened_mask : ndarray of bools
  1454. The flattened input.
  1455. Examples
  1456. --------
  1457. >>> mask = np.array([0, 0, 1])
  1458. >>> np.ma.flatten_mask(mask)
  1459. array([False, False, True])
  1460. >>> mask = np.array([(0, 0), (0, 1)], dtype=[('a', bool), ('b', bool)])
  1461. >>> np.ma.flatten_mask(mask)
  1462. array([False, False, False, True])
  1463. >>> mdtype = [('a', bool), ('b', [('ba', bool), ('bb', bool)])]
  1464. >>> mask = np.array([(0, (0, 0)), (0, (0, 1))], dtype=mdtype)
  1465. >>> np.ma.flatten_mask(mask)
  1466. array([False, False, False, False, False, True])
  1467. """
  1468. def _flatmask(mask):
  1469. "Flatten the mask and returns a (maybe nested) sequence of booleans."
  1470. mnames = mask.dtype.names
  1471. if mnames is not None:
  1472. return [flatten_mask(mask[name]) for name in mnames]
  1473. else:
  1474. return mask
  1475. def _flatsequence(sequence):
  1476. "Generates a flattened version of the sequence."
  1477. try:
  1478. for element in sequence:
  1479. if hasattr(element, '__iter__'):
  1480. yield from _flatsequence(element)
  1481. else:
  1482. yield element
  1483. except TypeError:
  1484. yield sequence
  1485. mask = np.asarray(mask)
  1486. flattened = _flatsequence(_flatmask(mask))
  1487. return np.array([_ for _ in flattened], dtype=bool)
  1488. def _check_mask_axis(mask, axis, keepdims=np._NoValue):
  1489. "Check whether there are masked values along the given axis"
  1490. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  1491. if mask is not nomask:
  1492. return mask.all(axis=axis, **kwargs)
  1493. return nomask
  1494. ###############################################################################
  1495. # Masking functions #
  1496. ###############################################################################
  1497. def masked_where(condition, a, copy=True):
  1498. """
  1499. Mask an array where a condition is met.
  1500. Return `a` as an array masked where `condition` is True.
  1501. Any masked values of `a` or `condition` are also masked in the output.
  1502. Parameters
  1503. ----------
  1504. condition : array_like
  1505. Masking condition. When `condition` tests floating point values for
  1506. equality, consider using ``masked_values`` instead.
  1507. a : array_like
  1508. Array to mask.
  1509. copy : bool
  1510. If True (default) make a copy of `a` in the result. If False modify
  1511. `a` in place and return a view.
  1512. Returns
  1513. -------
  1514. result : MaskedArray
  1515. The result of masking `a` where `condition` is True.
  1516. See Also
  1517. --------
  1518. masked_values : Mask using floating point equality.
  1519. masked_equal : Mask where equal to a given value.
  1520. masked_not_equal : Mask where `not` equal to a given value.
  1521. masked_less_equal : Mask where less than or equal to a given value.
  1522. masked_greater_equal : Mask where greater than or equal to a given value.
  1523. masked_less : Mask where less than a given value.
  1524. masked_greater : Mask where greater than a given value.
  1525. masked_inside : Mask inside a given interval.
  1526. masked_outside : Mask outside a given interval.
  1527. masked_invalid : Mask invalid values (NaNs or infs).
  1528. Examples
  1529. --------
  1530. >>> import numpy.ma as ma
  1531. >>> a = np.arange(4)
  1532. >>> a
  1533. array([0, 1, 2, 3])
  1534. >>> ma.masked_where(a <= 2, a)
  1535. masked_array(data=[--, --, --, 3],
  1536. mask=[ True, True, True, False],
  1537. fill_value=999999)
  1538. Mask array `b` conditional on `a`.
  1539. >>> b = ['a', 'b', 'c', 'd']
  1540. >>> ma.masked_where(a == 2, b)
  1541. masked_array(data=['a', 'b', --, 'd'],
  1542. mask=[False, False, True, False],
  1543. fill_value='N/A',
  1544. dtype='<U1')
  1545. Effect of the `copy` argument.
  1546. >>> c = ma.masked_where(a <= 2, a)
  1547. >>> c
  1548. masked_array(data=[--, --, --, 3],
  1549. mask=[ True, True, True, False],
  1550. fill_value=999999)
  1551. >>> c[0] = 99
  1552. >>> c
  1553. masked_array(data=[99, --, --, 3],
  1554. mask=[False, True, True, False],
  1555. fill_value=999999)
  1556. >>> a
  1557. array([0, 1, 2, 3])
  1558. >>> c = ma.masked_where(a <= 2, a, copy=False)
  1559. >>> c[0] = 99
  1560. >>> c
  1561. masked_array(data=[99, --, --, 3],
  1562. mask=[False, True, True, False],
  1563. fill_value=999999)
  1564. >>> a
  1565. array([99, 1, 2, 3])
  1566. When `condition` or `a` contain masked values.
  1567. >>> a = np.arange(4)
  1568. >>> a = ma.masked_where(a == 2, a)
  1569. >>> a
  1570. masked_array(data=[0, 1, --, 3],
  1571. mask=[False, False, True, False],
  1572. fill_value=999999)
  1573. >>> b = np.arange(4)
  1574. >>> b = ma.masked_where(b == 0, b)
  1575. >>> b
  1576. masked_array(data=[--, 1, 2, 3],
  1577. mask=[ True, False, False, False],
  1578. fill_value=999999)
  1579. >>> ma.masked_where(a == 3, b)
  1580. masked_array(data=[--, 1, --, --],
  1581. mask=[ True, False, True, True],
  1582. fill_value=999999)
  1583. """
  1584. # Make sure that condition is a valid standard-type mask.
  1585. cond = make_mask(condition, shrink=False)
  1586. a = np.array(a, copy=copy, subok=True)
  1587. (cshape, ashape) = (cond.shape, a.shape)
  1588. if cshape and cshape != ashape:
  1589. raise IndexError("Inconsistent shape between the condition and the input"
  1590. " (got %s and %s)" % (cshape, ashape))
  1591. if hasattr(a, '_mask'):
  1592. cond = mask_or(cond, a._mask)
  1593. cls = type(a)
  1594. else:
  1595. cls = MaskedArray
  1596. result = a.view(cls)
  1597. # Assign to *.mask so that structured masks are handled correctly.
  1598. result.mask = _shrink_mask(cond)
  1599. return result
  1600. def masked_greater(x, value, copy=True):
  1601. """
  1602. Mask an array where greater than a given value.
  1603. This function is a shortcut to ``masked_where``, with
  1604. `condition` = (x > value).
  1605. See Also
  1606. --------
  1607. masked_where : Mask where a condition is met.
  1608. Examples
  1609. --------
  1610. >>> import numpy.ma as ma
  1611. >>> a = np.arange(4)
  1612. >>> a
  1613. array([0, 1, 2, 3])
  1614. >>> ma.masked_greater(a, 2)
  1615. masked_array(data=[0, 1, 2, --],
  1616. mask=[False, False, False, True],
  1617. fill_value=999999)
  1618. """
  1619. return masked_where(greater(x, value), x, copy=copy)
  1620. def masked_greater_equal(x, value, copy=True):
  1621. """
  1622. Mask an array where greater than or equal to a given value.
  1623. This function is a shortcut to ``masked_where``, with
  1624. `condition` = (x >= value).
  1625. See Also
  1626. --------
  1627. masked_where : Mask where a condition is met.
  1628. Examples
  1629. --------
  1630. >>> import numpy.ma as ma
  1631. >>> a = np.arange(4)
  1632. >>> a
  1633. array([0, 1, 2, 3])
  1634. >>> ma.masked_greater_equal(a, 2)
  1635. masked_array(data=[0, 1, --, --],
  1636. mask=[False, False, True, True],
  1637. fill_value=999999)
  1638. """
  1639. return masked_where(greater_equal(x, value), x, copy=copy)
  1640. def masked_less(x, value, copy=True):
  1641. """
  1642. Mask an array where less than a given value.
  1643. This function is a shortcut to ``masked_where``, with
  1644. `condition` = (x < value).
  1645. See Also
  1646. --------
  1647. masked_where : Mask where a condition is met.
  1648. Examples
  1649. --------
  1650. >>> import numpy.ma as ma
  1651. >>> a = np.arange(4)
  1652. >>> a
  1653. array([0, 1, 2, 3])
  1654. >>> ma.masked_less(a, 2)
  1655. masked_array(data=[--, --, 2, 3],
  1656. mask=[ True, True, False, False],
  1657. fill_value=999999)
  1658. """
  1659. return masked_where(less(x, value), x, copy=copy)
  1660. def masked_less_equal(x, value, copy=True):
  1661. """
  1662. Mask an array where less than or equal to a given value.
  1663. This function is a shortcut to ``masked_where``, with
  1664. `condition` = (x <= value).
  1665. See Also
  1666. --------
  1667. masked_where : Mask where a condition is met.
  1668. Examples
  1669. --------
  1670. >>> import numpy.ma as ma
  1671. >>> a = np.arange(4)
  1672. >>> a
  1673. array([0, 1, 2, 3])
  1674. >>> ma.masked_less_equal(a, 2)
  1675. masked_array(data=[--, --, --, 3],
  1676. mask=[ True, True, True, False],
  1677. fill_value=999999)
  1678. """
  1679. return masked_where(less_equal(x, value), x, copy=copy)
  1680. def masked_not_equal(x, value, copy=True):
  1681. """
  1682. Mask an array where `not` equal to a given value.
  1683. This function is a shortcut to ``masked_where``, with
  1684. `condition` = (x != value).
  1685. See Also
  1686. --------
  1687. masked_where : Mask where a condition is met.
  1688. Examples
  1689. --------
  1690. >>> import numpy.ma as ma
  1691. >>> a = np.arange(4)
  1692. >>> a
  1693. array([0, 1, 2, 3])
  1694. >>> ma.masked_not_equal(a, 2)
  1695. masked_array(data=[--, --, 2, --],
  1696. mask=[ True, True, False, True],
  1697. fill_value=999999)
  1698. """
  1699. return masked_where(not_equal(x, value), x, copy=copy)
  1700. def masked_equal(x, value, copy=True):
  1701. """
  1702. Mask an array where equal to a given value.
  1703. This function is a shortcut to ``masked_where``, with
  1704. `condition` = (x == value). For floating point arrays,
  1705. consider using ``masked_values(x, value)``.
  1706. See Also
  1707. --------
  1708. masked_where : Mask where a condition is met.
  1709. masked_values : Mask using floating point equality.
  1710. Examples
  1711. --------
  1712. >>> import numpy.ma as ma
  1713. >>> a = np.arange(4)
  1714. >>> a
  1715. array([0, 1, 2, 3])
  1716. >>> ma.masked_equal(a, 2)
  1717. masked_array(data=[0, 1, --, 3],
  1718. mask=[False, False, True, False],
  1719. fill_value=2)
  1720. """
  1721. output = masked_where(equal(x, value), x, copy=copy)
  1722. output.fill_value = value
  1723. return output
  1724. def masked_inside(x, v1, v2, copy=True):
  1725. """
  1726. Mask an array inside a given interval.
  1727. Shortcut to ``masked_where``, where `condition` is True for `x` inside
  1728. the interval [v1,v2] (v1 <= x <= v2). The boundaries `v1` and `v2`
  1729. can be given in either order.
  1730. See Also
  1731. --------
  1732. masked_where : Mask where a condition is met.
  1733. Notes
  1734. -----
  1735. The array `x` is prefilled with its filling value.
  1736. Examples
  1737. --------
  1738. >>> import numpy.ma as ma
  1739. >>> x = [0.31, 1.2, 0.01, 0.2, -0.4, -1.1]
  1740. >>> ma.masked_inside(x, -0.3, 0.3)
  1741. masked_array(data=[0.31, 1.2, --, --, -0.4, -1.1],
  1742. mask=[False, False, True, True, False, False],
  1743. fill_value=1e+20)
  1744. The order of `v1` and `v2` doesn't matter.
  1745. >>> ma.masked_inside(x, 0.3, -0.3)
  1746. masked_array(data=[0.31, 1.2, --, --, -0.4, -1.1],
  1747. mask=[False, False, True, True, False, False],
  1748. fill_value=1e+20)
  1749. """
  1750. if v2 < v1:
  1751. (v1, v2) = (v2, v1)
  1752. xf = filled(x)
  1753. condition = (xf >= v1) & (xf <= v2)
  1754. return masked_where(condition, x, copy=copy)
  1755. def masked_outside(x, v1, v2, copy=True):
  1756. """
  1757. Mask an array outside a given interval.
  1758. Shortcut to ``masked_where``, where `condition` is True for `x` outside
  1759. the interval [v1,v2] (x < v1)|(x > v2).
  1760. The boundaries `v1` and `v2` can be given in either order.
  1761. See Also
  1762. --------
  1763. masked_where : Mask where a condition is met.
  1764. Notes
  1765. -----
  1766. The array `x` is prefilled with its filling value.
  1767. Examples
  1768. --------
  1769. >>> import numpy.ma as ma
  1770. >>> x = [0.31, 1.2, 0.01, 0.2, -0.4, -1.1]
  1771. >>> ma.masked_outside(x, -0.3, 0.3)
  1772. masked_array(data=[--, --, 0.01, 0.2, --, --],
  1773. mask=[ True, True, False, False, True, True],
  1774. fill_value=1e+20)
  1775. The order of `v1` and `v2` doesn't matter.
  1776. >>> ma.masked_outside(x, 0.3, -0.3)
  1777. masked_array(data=[--, --, 0.01, 0.2, --, --],
  1778. mask=[ True, True, False, False, True, True],
  1779. fill_value=1e+20)
  1780. """
  1781. if v2 < v1:
  1782. (v1, v2) = (v2, v1)
  1783. xf = filled(x)
  1784. condition = (xf < v1) | (xf > v2)
  1785. return masked_where(condition, x, copy=copy)
  1786. def masked_object(x, value, copy=True, shrink=True):
  1787. """
  1788. Mask the array `x` where the data are exactly equal to value.
  1789. This function is similar to `masked_values`, but only suitable
  1790. for object arrays: for floating point, use `masked_values` instead.
  1791. Parameters
  1792. ----------
  1793. x : array_like
  1794. Array to mask
  1795. value : object
  1796. Comparison value
  1797. copy : {True, False}, optional
  1798. Whether to return a copy of `x`.
  1799. shrink : {True, False}, optional
  1800. Whether to collapse a mask full of False to nomask
  1801. Returns
  1802. -------
  1803. result : MaskedArray
  1804. The result of masking `x` where equal to `value`.
  1805. See Also
  1806. --------
  1807. masked_where : Mask where a condition is met.
  1808. masked_equal : Mask where equal to a given value (integers).
  1809. masked_values : Mask using floating point equality.
  1810. Examples
  1811. --------
  1812. >>> import numpy.ma as ma
  1813. >>> food = np.array(['green_eggs', 'ham'], dtype=object)
  1814. >>> # don't eat spoiled food
  1815. >>> eat = ma.masked_object(food, 'green_eggs')
  1816. >>> eat
  1817. masked_array(data=[--, 'ham'],
  1818. mask=[ True, False],
  1819. fill_value='green_eggs',
  1820. dtype=object)
  1821. >>> # plain ol` ham is boring
  1822. >>> fresh_food = np.array(['cheese', 'ham', 'pineapple'], dtype=object)
  1823. >>> eat = ma.masked_object(fresh_food, 'green_eggs')
  1824. >>> eat
  1825. masked_array(data=['cheese', 'ham', 'pineapple'],
  1826. mask=False,
  1827. fill_value='green_eggs',
  1828. dtype=object)
  1829. Note that `mask` is set to ``nomask`` if possible.
  1830. >>> eat
  1831. masked_array(data=['cheese', 'ham', 'pineapple'],
  1832. mask=False,
  1833. fill_value='green_eggs',
  1834. dtype=object)
  1835. """
  1836. if isMaskedArray(x):
  1837. condition = umath.equal(x._data, value)
  1838. mask = x._mask
  1839. else:
  1840. condition = umath.equal(np.asarray(x), value)
  1841. mask = nomask
  1842. mask = mask_or(mask, make_mask(condition, shrink=shrink))
  1843. return masked_array(x, mask=mask, copy=copy, fill_value=value)
  1844. def masked_values(x, value, rtol=1e-5, atol=1e-8, copy=True, shrink=True):
  1845. """
  1846. Mask using floating point equality.
  1847. Return a MaskedArray, masked where the data in array `x` are approximately
  1848. equal to `value`, determined using `isclose`. The default tolerances for
  1849. `masked_values` are the same as those for `isclose`.
  1850. For integer types, exact equality is used, in the same way as
  1851. `masked_equal`.
  1852. The fill_value is set to `value` and the mask is set to ``nomask`` if
  1853. possible.
  1854. Parameters
  1855. ----------
  1856. x : array_like
  1857. Array to mask.
  1858. value : float
  1859. Masking value.
  1860. rtol, atol : float, optional
  1861. Tolerance parameters passed on to `isclose`
  1862. copy : bool, optional
  1863. Whether to return a copy of `x`.
  1864. shrink : bool, optional
  1865. Whether to collapse a mask full of False to ``nomask``.
  1866. Returns
  1867. -------
  1868. result : MaskedArray
  1869. The result of masking `x` where approximately equal to `value`.
  1870. See Also
  1871. --------
  1872. masked_where : Mask where a condition is met.
  1873. masked_equal : Mask where equal to a given value (integers).
  1874. Examples
  1875. --------
  1876. >>> import numpy.ma as ma
  1877. >>> x = np.array([1, 1.1, 2, 1.1, 3])
  1878. >>> ma.masked_values(x, 1.1)
  1879. masked_array(data=[1.0, --, 2.0, --, 3.0],
  1880. mask=[False, True, False, True, False],
  1881. fill_value=1.1)
  1882. Note that `mask` is set to ``nomask`` if possible.
  1883. >>> ma.masked_values(x, 1.5)
  1884. masked_array(data=[1. , 1.1, 2. , 1.1, 3. ],
  1885. mask=False,
  1886. fill_value=1.5)
  1887. For integers, the fill value will be different in general to the
  1888. result of ``masked_equal``.
  1889. >>> x = np.arange(5)
  1890. >>> x
  1891. array([0, 1, 2, 3, 4])
  1892. >>> ma.masked_values(x, 2)
  1893. masked_array(data=[0, 1, --, 3, 4],
  1894. mask=[False, False, True, False, False],
  1895. fill_value=2)
  1896. >>> ma.masked_equal(x, 2)
  1897. masked_array(data=[0, 1, --, 3, 4],
  1898. mask=[False, False, True, False, False],
  1899. fill_value=2)
  1900. """
  1901. xnew = filled(x, value)
  1902. if np.issubdtype(xnew.dtype, np.floating):
  1903. mask = np.isclose(xnew, value, atol=atol, rtol=rtol)
  1904. else:
  1905. mask = umath.equal(xnew, value)
  1906. ret = masked_array(xnew, mask=mask, copy=copy, fill_value=value)
  1907. if shrink:
  1908. ret.shrink_mask()
  1909. return ret
  1910. def masked_invalid(a, copy=True):
  1911. """
  1912. Mask an array where invalid values occur (NaNs or infs).
  1913. This function is a shortcut to ``masked_where``, with
  1914. `condition` = ~(np.isfinite(a)). Any pre-existing mask is conserved.
  1915. Only applies to arrays with a dtype where NaNs or infs make sense
  1916. (i.e. floating point types), but accepts any array_like object.
  1917. See Also
  1918. --------
  1919. masked_where : Mask where a condition is met.
  1920. Examples
  1921. --------
  1922. >>> import numpy.ma as ma
  1923. >>> a = np.arange(5, dtype=float)
  1924. >>> a[2] = np.NaN
  1925. >>> a[3] = np.PINF
  1926. >>> a
  1927. array([ 0., 1., nan, inf, 4.])
  1928. >>> ma.masked_invalid(a)
  1929. masked_array(data=[0.0, 1.0, --, --, 4.0],
  1930. mask=[False, False, True, True, False],
  1931. fill_value=1e+20)
  1932. """
  1933. a = np.array(a, copy=copy, subok=True)
  1934. mask = getattr(a, '_mask', None)
  1935. if mask is not None:
  1936. condition = ~(np.isfinite(getdata(a)))
  1937. if mask is not nomask:
  1938. condition |= mask
  1939. cls = type(a)
  1940. else:
  1941. condition = ~(np.isfinite(a))
  1942. cls = MaskedArray
  1943. result = a.view(cls)
  1944. result._mask = condition
  1945. return result
  1946. ###############################################################################
  1947. # Printing options #
  1948. ###############################################################################
  1949. class _MaskedPrintOption:
  1950. """
  1951. Handle the string used to represent missing data in a masked array.
  1952. """
  1953. def __init__(self, display):
  1954. """
  1955. Create the masked_print_option object.
  1956. """
  1957. self._display = display
  1958. self._enabled = True
  1959. def display(self):
  1960. """
  1961. Display the string to print for masked values.
  1962. """
  1963. return self._display
  1964. def set_display(self, s):
  1965. """
  1966. Set the string to print for masked values.
  1967. """
  1968. self._display = s
  1969. def enabled(self):
  1970. """
  1971. Is the use of the display value enabled?
  1972. """
  1973. return self._enabled
  1974. def enable(self, shrink=1):
  1975. """
  1976. Set the enabling shrink to `shrink`.
  1977. """
  1978. self._enabled = shrink
  1979. def __str__(self):
  1980. return str(self._display)
  1981. __repr__ = __str__
  1982. # if you single index into a masked location you get this object.
  1983. masked_print_option = _MaskedPrintOption('--')
  1984. def _recursive_printoption(result, mask, printopt):
  1985. """
  1986. Puts printoptions in result where mask is True.
  1987. Private function allowing for recursion
  1988. """
  1989. names = result.dtype.names
  1990. if names is not None:
  1991. for name in names:
  1992. curdata = result[name]
  1993. curmask = mask[name]
  1994. _recursive_printoption(curdata, curmask, printopt)
  1995. else:
  1996. np.copyto(result, printopt, where=mask)
  1997. return
  1998. # For better or worse, these end in a newline
  1999. _legacy_print_templates = dict(
  2000. long_std=textwrap.dedent("""\
  2001. masked_%(name)s(data =
  2002. %(data)s,
  2003. %(nlen)s mask =
  2004. %(mask)s,
  2005. %(nlen)s fill_value = %(fill)s)
  2006. """),
  2007. long_flx=textwrap.dedent("""\
  2008. masked_%(name)s(data =
  2009. %(data)s,
  2010. %(nlen)s mask =
  2011. %(mask)s,
  2012. %(nlen)s fill_value = %(fill)s,
  2013. %(nlen)s dtype = %(dtype)s)
  2014. """),
  2015. short_std=textwrap.dedent("""\
  2016. masked_%(name)s(data = %(data)s,
  2017. %(nlen)s mask = %(mask)s,
  2018. %(nlen)s fill_value = %(fill)s)
  2019. """),
  2020. short_flx=textwrap.dedent("""\
  2021. masked_%(name)s(data = %(data)s,
  2022. %(nlen)s mask = %(mask)s,
  2023. %(nlen)s fill_value = %(fill)s,
  2024. %(nlen)s dtype = %(dtype)s)
  2025. """)
  2026. )
  2027. ###############################################################################
  2028. # MaskedArray class #
  2029. ###############################################################################
  2030. def _recursive_filled(a, mask, fill_value):
  2031. """
  2032. Recursively fill `a` with `fill_value`.
  2033. """
  2034. names = a.dtype.names
  2035. for name in names:
  2036. current = a[name]
  2037. if current.dtype.names is not None:
  2038. _recursive_filled(current, mask[name], fill_value[name])
  2039. else:
  2040. np.copyto(current, fill_value[name], where=mask[name])
  2041. def flatten_structured_array(a):
  2042. """
  2043. Flatten a structured array.
  2044. The data type of the output is chosen such that it can represent all of the
  2045. (nested) fields.
  2046. Parameters
  2047. ----------
  2048. a : structured array
  2049. Returns
  2050. -------
  2051. output : masked array or ndarray
  2052. A flattened masked array if the input is a masked array, otherwise a
  2053. standard ndarray.
  2054. Examples
  2055. --------
  2056. >>> ndtype = [('a', int), ('b', float)]
  2057. >>> a = np.array([(1, 1), (2, 2)], dtype=ndtype)
  2058. >>> np.ma.flatten_structured_array(a)
  2059. array([[1., 1.],
  2060. [2., 2.]])
  2061. """
  2062. def flatten_sequence(iterable):
  2063. """
  2064. Flattens a compound of nested iterables.
  2065. """
  2066. for elm in iter(iterable):
  2067. if hasattr(elm, '__iter__'):
  2068. yield from flatten_sequence(elm)
  2069. else:
  2070. yield elm
  2071. a = np.asanyarray(a)
  2072. inishape = a.shape
  2073. a = a.ravel()
  2074. if isinstance(a, MaskedArray):
  2075. out = np.array([tuple(flatten_sequence(d.item())) for d in a._data])
  2076. out = out.view(MaskedArray)
  2077. out._mask = np.array([tuple(flatten_sequence(d.item()))
  2078. for d in getmaskarray(a)])
  2079. else:
  2080. out = np.array([tuple(flatten_sequence(d.item())) for d in a])
  2081. if len(inishape) > 1:
  2082. newshape = list(out.shape)
  2083. newshape[0] = inishape
  2084. out.shape = tuple(flatten_sequence(newshape))
  2085. return out
  2086. def _arraymethod(funcname, onmask=True):
  2087. """
  2088. Return a class method wrapper around a basic array method.
  2089. Creates a class method which returns a masked array, where the new
  2090. ``_data`` array is the output of the corresponding basic method called
  2091. on the original ``_data``.
  2092. If `onmask` is True, the new mask is the output of the method called
  2093. on the initial mask. Otherwise, the new mask is just a reference
  2094. to the initial mask.
  2095. Parameters
  2096. ----------
  2097. funcname : str
  2098. Name of the function to apply on data.
  2099. onmask : bool
  2100. Whether the mask must be processed also (True) or left
  2101. alone (False). Default is True. Make available as `_onmask`
  2102. attribute.
  2103. Returns
  2104. -------
  2105. method : instancemethod
  2106. Class method wrapper of the specified basic array method.
  2107. """
  2108. def wrapped_method(self, *args, **params):
  2109. result = getattr(self._data, funcname)(*args, **params)
  2110. result = result.view(type(self))
  2111. result._update_from(self)
  2112. mask = self._mask
  2113. if not onmask:
  2114. result.__setmask__(mask)
  2115. elif mask is not nomask:
  2116. # __setmask__ makes a copy, which we don't want
  2117. result._mask = getattr(mask, funcname)(*args, **params)
  2118. return result
  2119. methdoc = getattr(ndarray, funcname, None) or getattr(np, funcname, None)
  2120. if methdoc is not None:
  2121. wrapped_method.__doc__ = methdoc.__doc__
  2122. wrapped_method.__name__ = funcname
  2123. return wrapped_method
  2124. class MaskedIterator:
  2125. """
  2126. Flat iterator object to iterate over masked arrays.
  2127. A `MaskedIterator` iterator is returned by ``x.flat`` for any masked array
  2128. `x`. It allows iterating over the array as if it were a 1-D array,
  2129. either in a for-loop or by calling its `next` method.
  2130. Iteration is done in C-contiguous style, with the last index varying the
  2131. fastest. The iterator can also be indexed using basic slicing or
  2132. advanced indexing.
  2133. See Also
  2134. --------
  2135. MaskedArray.flat : Return a flat iterator over an array.
  2136. MaskedArray.flatten : Returns a flattened copy of an array.
  2137. Notes
  2138. -----
  2139. `MaskedIterator` is not exported by the `ma` module. Instead of
  2140. instantiating a `MaskedIterator` directly, use `MaskedArray.flat`.
  2141. Examples
  2142. --------
  2143. >>> x = np.ma.array(arange(6).reshape(2, 3))
  2144. >>> fl = x.flat
  2145. >>> type(fl)
  2146. <class 'numpy.ma.core.MaskedIterator'>
  2147. >>> for item in fl:
  2148. ... print(item)
  2149. ...
  2150. 0
  2151. 1
  2152. 2
  2153. 3
  2154. 4
  2155. 5
  2156. Extracting more than a single element b indexing the `MaskedIterator`
  2157. returns a masked array:
  2158. >>> fl[2:4]
  2159. masked_array(data = [2 3],
  2160. mask = False,
  2161. fill_value = 999999)
  2162. """
  2163. def __init__(self, ma):
  2164. self.ma = ma
  2165. self.dataiter = ma._data.flat
  2166. if ma._mask is nomask:
  2167. self.maskiter = None
  2168. else:
  2169. self.maskiter = ma._mask.flat
  2170. def __iter__(self):
  2171. return self
  2172. def __getitem__(self, indx):
  2173. result = self.dataiter.__getitem__(indx).view(type(self.ma))
  2174. if self.maskiter is not None:
  2175. _mask = self.maskiter.__getitem__(indx)
  2176. if isinstance(_mask, ndarray):
  2177. # set shape to match that of data; this is needed for matrices
  2178. _mask.shape = result.shape
  2179. result._mask = _mask
  2180. elif isinstance(_mask, np.void):
  2181. return mvoid(result, mask=_mask, hardmask=self.ma._hardmask)
  2182. elif _mask: # Just a scalar, masked
  2183. return masked
  2184. return result
  2185. # This won't work if ravel makes a copy
  2186. def __setitem__(self, index, value):
  2187. self.dataiter[index] = getdata(value)
  2188. if self.maskiter is not None:
  2189. self.maskiter[index] = getmaskarray(value)
  2190. def __next__(self):
  2191. """
  2192. Return the next value, or raise StopIteration.
  2193. Examples
  2194. --------
  2195. >>> x = np.ma.array([3, 2], mask=[0, 1])
  2196. >>> fl = x.flat
  2197. >>> next(fl)
  2198. 3
  2199. >>> next(fl)
  2200. masked
  2201. >>> next(fl)
  2202. Traceback (most recent call last):
  2203. ...
  2204. StopIteration
  2205. """
  2206. d = next(self.dataiter)
  2207. if self.maskiter is not None:
  2208. m = next(self.maskiter)
  2209. if isinstance(m, np.void):
  2210. return mvoid(d, mask=m, hardmask=self.ma._hardmask)
  2211. elif m: # Just a scalar, masked
  2212. return masked
  2213. return d
  2214. class MaskedArray(ndarray):
  2215. """
  2216. An array class with possibly masked values.
  2217. Masked values of True exclude the corresponding element from any
  2218. computation.
  2219. Construction::
  2220. x = MaskedArray(data, mask=nomask, dtype=None, copy=False, subok=True,
  2221. ndmin=0, fill_value=None, keep_mask=True, hard_mask=None,
  2222. shrink=True, order=None)
  2223. Parameters
  2224. ----------
  2225. data : array_like
  2226. Input data.
  2227. mask : sequence, optional
  2228. Mask. Must be convertible to an array of booleans with the same
  2229. shape as `data`. True indicates a masked (i.e. invalid) data.
  2230. dtype : dtype, optional
  2231. Data type of the output.
  2232. If `dtype` is None, the type of the data argument (``data.dtype``)
  2233. is used. If `dtype` is not None and different from ``data.dtype``,
  2234. a copy is performed.
  2235. copy : bool, optional
  2236. Whether to copy the input data (True), or to use a reference instead.
  2237. Default is False.
  2238. subok : bool, optional
  2239. Whether to return a subclass of `MaskedArray` if possible (True) or a
  2240. plain `MaskedArray`. Default is True.
  2241. ndmin : int, optional
  2242. Minimum number of dimensions. Default is 0.
  2243. fill_value : scalar, optional
  2244. Value used to fill in the masked values when necessary.
  2245. If None, a default based on the data-type is used.
  2246. keep_mask : bool, optional
  2247. Whether to combine `mask` with the mask of the input data, if any
  2248. (True), or to use only `mask` for the output (False). Default is True.
  2249. hard_mask : bool, optional
  2250. Whether to use a hard mask or not. With a hard mask, masked values
  2251. cannot be unmasked. Default is False.
  2252. shrink : bool, optional
  2253. Whether to force compression of an empty mask. Default is True.
  2254. order : {'C', 'F', 'A'}, optional
  2255. Specify the order of the array. If order is 'C', then the array
  2256. will be in C-contiguous order (last-index varies the fastest).
  2257. If order is 'F', then the returned array will be in
  2258. Fortran-contiguous order (first-index varies the fastest).
  2259. If order is 'A' (default), then the returned array may be
  2260. in any order (either C-, Fortran-contiguous, or even discontiguous),
  2261. unless a copy is required, in which case it will be C-contiguous.
  2262. Examples
  2263. --------
  2264. The ``mask`` can be initialized with an array of boolean values
  2265. with the same shape as ``data``.
  2266. >>> data = np.arange(6).reshape((2, 3))
  2267. >>> np.ma.MaskedArray(data, mask=[[False, True, False],
  2268. ... [False, False, True]])
  2269. masked_array(
  2270. data=[[0, --, 2],
  2271. [3, 4, --]],
  2272. mask=[[False, True, False],
  2273. [False, False, True]],
  2274. fill_value=999999)
  2275. Alternatively, the ``mask`` can be initialized to homogeneous boolean
  2276. array with the same shape as ``data`` by passing in a scalar
  2277. boolean value:
  2278. >>> np.ma.MaskedArray(data, mask=False)
  2279. masked_array(
  2280. data=[[0, 1, 2],
  2281. [3, 4, 5]],
  2282. mask=[[False, False, False],
  2283. [False, False, False]],
  2284. fill_value=999999)
  2285. >>> np.ma.MaskedArray(data, mask=True)
  2286. masked_array(
  2287. data=[[--, --, --],
  2288. [--, --, --]],
  2289. mask=[[ True, True, True],
  2290. [ True, True, True]],
  2291. fill_value=999999,
  2292. dtype=int64)
  2293. .. note::
  2294. The recommended practice for initializing ``mask`` with a scalar
  2295. boolean value is to use ``True``/``False`` rather than
  2296. ``np.True_``/``np.False_``. The reason is :attr:`nomask`
  2297. is represented internally as ``np.False_``.
  2298. >>> np.False_ is np.ma.nomask
  2299. True
  2300. """
  2301. __array_priority__ = 15
  2302. _defaultmask = nomask
  2303. _defaulthardmask = False
  2304. _baseclass = ndarray
  2305. # Maximum number of elements per axis used when printing an array. The
  2306. # 1d case is handled separately because we need more values in this case.
  2307. _print_width = 100
  2308. _print_width_1d = 1500
  2309. def __new__(cls, data=None, mask=nomask, dtype=None, copy=False,
  2310. subok=True, ndmin=0, fill_value=None, keep_mask=True,
  2311. hard_mask=None, shrink=True, order=None):
  2312. """
  2313. Create a new masked array from scratch.
  2314. Notes
  2315. -----
  2316. A masked array can also be created by taking a .view(MaskedArray).
  2317. """
  2318. # Process data.
  2319. _data = np.array(data, dtype=dtype, copy=copy,
  2320. order=order, subok=True, ndmin=ndmin)
  2321. _baseclass = getattr(data, '_baseclass', type(_data))
  2322. # Check that we're not erasing the mask.
  2323. if isinstance(data, MaskedArray) and (data.shape != _data.shape):
  2324. copy = True
  2325. # Here, we copy the _view_, so that we can attach new properties to it
  2326. # we must never do .view(MaskedConstant), as that would create a new
  2327. # instance of np.ma.masked, which make identity comparison fail
  2328. if isinstance(data, cls) and subok and not isinstance(data, MaskedConstant):
  2329. _data = ndarray.view(_data, type(data))
  2330. else:
  2331. _data = ndarray.view(_data, cls)
  2332. # Backwards compatibility w/ numpy.core.ma.
  2333. if hasattr(data, '_mask') and not isinstance(data, ndarray):
  2334. _data._mask = data._mask
  2335. # FIXME _sharedmask is never used.
  2336. _sharedmask = True
  2337. # Process mask.
  2338. # Type of the mask
  2339. mdtype = make_mask_descr(_data.dtype)
  2340. if mask is nomask:
  2341. # Case 1. : no mask in input.
  2342. # Erase the current mask ?
  2343. if not keep_mask:
  2344. # With a reduced version
  2345. if shrink:
  2346. _data._mask = nomask
  2347. # With full version
  2348. else:
  2349. _data._mask = np.zeros(_data.shape, dtype=mdtype)
  2350. # Check whether we missed something
  2351. elif isinstance(data, (tuple, list)):
  2352. try:
  2353. # If data is a sequence of masked array
  2354. mask = np.array(
  2355. [getmaskarray(np.asanyarray(m, dtype=_data.dtype))
  2356. for m in data], dtype=mdtype)
  2357. except ValueError:
  2358. # If data is nested
  2359. mask = nomask
  2360. # Force shrinking of the mask if needed (and possible)
  2361. if (mdtype == MaskType) and mask.any():
  2362. _data._mask = mask
  2363. _data._sharedmask = False
  2364. else:
  2365. _data._sharedmask = not copy
  2366. if copy:
  2367. _data._mask = _data._mask.copy()
  2368. # Reset the shape of the original mask
  2369. if getmask(data) is not nomask:
  2370. data._mask.shape = data.shape
  2371. else:
  2372. # Case 2. : With a mask in input.
  2373. # If mask is boolean, create an array of True or False
  2374. if mask is True and mdtype == MaskType:
  2375. mask = np.ones(_data.shape, dtype=mdtype)
  2376. elif mask is False and mdtype == MaskType:
  2377. mask = np.zeros(_data.shape, dtype=mdtype)
  2378. else:
  2379. # Read the mask with the current mdtype
  2380. try:
  2381. mask = np.array(mask, copy=copy, dtype=mdtype)
  2382. # Or assume it's a sequence of bool/int
  2383. except TypeError:
  2384. mask = np.array([tuple([m] * len(mdtype)) for m in mask],
  2385. dtype=mdtype)
  2386. # Make sure the mask and the data have the same shape
  2387. if mask.shape != _data.shape:
  2388. (nd, nm) = (_data.size, mask.size)
  2389. if nm == 1:
  2390. mask = np.resize(mask, _data.shape)
  2391. elif nm == nd:
  2392. mask = np.reshape(mask, _data.shape)
  2393. else:
  2394. msg = "Mask and data not compatible: data size is %i, " + \
  2395. "mask size is %i."
  2396. raise MaskError(msg % (nd, nm))
  2397. copy = True
  2398. # Set the mask to the new value
  2399. if _data._mask is nomask:
  2400. _data._mask = mask
  2401. _data._sharedmask = not copy
  2402. else:
  2403. if not keep_mask:
  2404. _data._mask = mask
  2405. _data._sharedmask = not copy
  2406. else:
  2407. if _data.dtype.names is not None:
  2408. def _recursive_or(a, b):
  2409. "do a|=b on each field of a, recursively"
  2410. for name in a.dtype.names:
  2411. (af, bf) = (a[name], b[name])
  2412. if af.dtype.names is not None:
  2413. _recursive_or(af, bf)
  2414. else:
  2415. af |= bf
  2416. _recursive_or(_data._mask, mask)
  2417. else:
  2418. _data._mask = np.logical_or(mask, _data._mask)
  2419. _data._sharedmask = False
  2420. # Update fill_value.
  2421. if fill_value is None:
  2422. fill_value = getattr(data, '_fill_value', None)
  2423. # But don't run the check unless we have something to check.
  2424. if fill_value is not None:
  2425. _data._fill_value = _check_fill_value(fill_value, _data.dtype)
  2426. # Process extra options ..
  2427. if hard_mask is None:
  2428. _data._hardmask = getattr(data, '_hardmask', False)
  2429. else:
  2430. _data._hardmask = hard_mask
  2431. _data._baseclass = _baseclass
  2432. return _data
  2433. def _update_from(self, obj):
  2434. """
  2435. Copies some attributes of obj to self.
  2436. """
  2437. if isinstance(obj, ndarray):
  2438. _baseclass = type(obj)
  2439. else:
  2440. _baseclass = ndarray
  2441. # We need to copy the _basedict to avoid backward propagation
  2442. _optinfo = {}
  2443. _optinfo.update(getattr(obj, '_optinfo', {}))
  2444. _optinfo.update(getattr(obj, '_basedict', {}))
  2445. if not isinstance(obj, MaskedArray):
  2446. _optinfo.update(getattr(obj, '__dict__', {}))
  2447. _dict = dict(_fill_value=getattr(obj, '_fill_value', None),
  2448. _hardmask=getattr(obj, '_hardmask', False),
  2449. _sharedmask=getattr(obj, '_sharedmask', False),
  2450. _isfield=getattr(obj, '_isfield', False),
  2451. _baseclass=getattr(obj, '_baseclass', _baseclass),
  2452. _optinfo=_optinfo,
  2453. _basedict=_optinfo)
  2454. self.__dict__.update(_dict)
  2455. self.__dict__.update(_optinfo)
  2456. return
  2457. def __array_finalize__(self, obj):
  2458. """
  2459. Finalizes the masked array.
  2460. """
  2461. # Get main attributes.
  2462. self._update_from(obj)
  2463. # We have to decide how to initialize self.mask, based on
  2464. # obj.mask. This is very difficult. There might be some
  2465. # correspondence between the elements in the array we are being
  2466. # created from (= obj) and us. Or there might not. This method can
  2467. # be called in all kinds of places for all kinds of reasons -- could
  2468. # be empty_like, could be slicing, could be a ufunc, could be a view.
  2469. # The numpy subclassing interface simply doesn't give us any way
  2470. # to know, which means that at best this method will be based on
  2471. # guesswork and heuristics. To make things worse, there isn't even any
  2472. # clear consensus about what the desired behavior is. For instance,
  2473. # most users think that np.empty_like(marr) -- which goes via this
  2474. # method -- should return a masked array with an empty mask (see
  2475. # gh-3404 and linked discussions), but others disagree, and they have
  2476. # existing code which depends on empty_like returning an array that
  2477. # matches the input mask.
  2478. #
  2479. # Historically our algorithm was: if the template object mask had the
  2480. # same *number of elements* as us, then we used *it's mask object
  2481. # itself* as our mask, so that writes to us would also write to the
  2482. # original array. This is horribly broken in multiple ways.
  2483. #
  2484. # Now what we do instead is, if the template object mask has the same
  2485. # number of elements as us, and we do not have the same base pointer
  2486. # as the template object (b/c views like arr[...] should keep the same
  2487. # mask), then we make a copy of the template object mask and use
  2488. # that. This is also horribly broken but somewhat less so. Maybe.
  2489. if isinstance(obj, ndarray):
  2490. # XX: This looks like a bug -- shouldn't it check self.dtype
  2491. # instead?
  2492. if obj.dtype.names is not None:
  2493. _mask = getmaskarray(obj)
  2494. else:
  2495. _mask = getmask(obj)
  2496. # If self and obj point to exactly the same data, then probably
  2497. # self is a simple view of obj (e.g., self = obj[...]), so they
  2498. # should share the same mask. (This isn't 100% reliable, e.g. self
  2499. # could be the first row of obj, or have strange strides, but as a
  2500. # heuristic it's not bad.) In all other cases, we make a copy of
  2501. # the mask, so that future modifications to 'self' do not end up
  2502. # side-effecting 'obj' as well.
  2503. if (_mask is not nomask and obj.__array_interface__["data"][0]
  2504. != self.__array_interface__["data"][0]):
  2505. # We should make a copy. But we could get here via astype,
  2506. # in which case the mask might need a new dtype as well
  2507. # (e.g., changing to or from a structured dtype), and the
  2508. # order could have changed. So, change the mask type if
  2509. # needed and use astype instead of copy.
  2510. if self.dtype == obj.dtype:
  2511. _mask_dtype = _mask.dtype
  2512. else:
  2513. _mask_dtype = make_mask_descr(self.dtype)
  2514. if self.flags.c_contiguous:
  2515. order = "C"
  2516. elif self.flags.f_contiguous:
  2517. order = "F"
  2518. else:
  2519. order = "K"
  2520. _mask = _mask.astype(_mask_dtype, order)
  2521. else:
  2522. # Take a view so shape changes, etc., do not propagate back.
  2523. _mask = _mask.view()
  2524. else:
  2525. _mask = nomask
  2526. self._mask = _mask
  2527. # Finalize the mask
  2528. if self._mask is not nomask:
  2529. try:
  2530. self._mask.shape = self.shape
  2531. except ValueError:
  2532. self._mask = nomask
  2533. except (TypeError, AttributeError):
  2534. # When _mask.shape is not writable (because it's a void)
  2535. pass
  2536. # Finalize the fill_value
  2537. if self._fill_value is not None:
  2538. self._fill_value = _check_fill_value(self._fill_value, self.dtype)
  2539. elif self.dtype.names is not None:
  2540. # Finalize the default fill_value for structured arrays
  2541. self._fill_value = _check_fill_value(None, self.dtype)
  2542. def __array_wrap__(self, obj, context=None):
  2543. """
  2544. Special hook for ufuncs.
  2545. Wraps the numpy array and sets the mask according to context.
  2546. """
  2547. if obj is self: # for in-place operations
  2548. result = obj
  2549. else:
  2550. result = obj.view(type(self))
  2551. result._update_from(self)
  2552. if context is not None:
  2553. result._mask = result._mask.copy()
  2554. func, args, out_i = context
  2555. # args sometimes contains outputs (gh-10459), which we don't want
  2556. input_args = args[:func.nin]
  2557. m = reduce(mask_or, [getmaskarray(arg) for arg in input_args])
  2558. # Get the domain mask
  2559. domain = ufunc_domain.get(func, None)
  2560. if domain is not None:
  2561. # Take the domain, and make sure it's a ndarray
  2562. with np.errstate(divide='ignore', invalid='ignore'):
  2563. d = filled(domain(*input_args), True)
  2564. if d.any():
  2565. # Fill the result where the domain is wrong
  2566. try:
  2567. # Binary domain: take the last value
  2568. fill_value = ufunc_fills[func][-1]
  2569. except TypeError:
  2570. # Unary domain: just use this one
  2571. fill_value = ufunc_fills[func]
  2572. except KeyError:
  2573. # Domain not recognized, use fill_value instead
  2574. fill_value = self.fill_value
  2575. np.copyto(result, fill_value, where=d)
  2576. # Update the mask
  2577. if m is nomask:
  2578. m = d
  2579. else:
  2580. # Don't modify inplace, we risk back-propagation
  2581. m = (m | d)
  2582. # Make sure the mask has the proper size
  2583. if result is not self and result.shape == () and m:
  2584. return masked
  2585. else:
  2586. result._mask = m
  2587. result._sharedmask = False
  2588. return result
  2589. def view(self, dtype=None, type=None, fill_value=None):
  2590. """
  2591. Return a view of the MaskedArray data.
  2592. Parameters
  2593. ----------
  2594. dtype : data-type or ndarray sub-class, optional
  2595. Data-type descriptor of the returned view, e.g., float32 or int16.
  2596. The default, None, results in the view having the same data-type
  2597. as `a`. As with ``ndarray.view``, dtype can also be specified as
  2598. an ndarray sub-class, which then specifies the type of the
  2599. returned object (this is equivalent to setting the ``type``
  2600. parameter).
  2601. type : Python type, optional
  2602. Type of the returned view, either ndarray or a subclass. The
  2603. default None results in type preservation.
  2604. fill_value : scalar, optional
  2605. The value to use for invalid entries (None by default).
  2606. If None, then this argument is inferred from the passed `dtype`, or
  2607. in its absence the original array, as discussed in the notes below.
  2608. See Also
  2609. --------
  2610. numpy.ndarray.view : Equivalent method on ndarray object.
  2611. Notes
  2612. -----
  2613. ``a.view()`` is used two different ways:
  2614. ``a.view(some_dtype)`` or ``a.view(dtype=some_dtype)`` constructs a view
  2615. of the array's memory with a different data-type. This can cause a
  2616. reinterpretation of the bytes of memory.
  2617. ``a.view(ndarray_subclass)`` or ``a.view(type=ndarray_subclass)`` just
  2618. returns an instance of `ndarray_subclass` that looks at the same array
  2619. (same shape, dtype, etc.) This does not cause a reinterpretation of the
  2620. memory.
  2621. If `fill_value` is not specified, but `dtype` is specified (and is not
  2622. an ndarray sub-class), the `fill_value` of the MaskedArray will be
  2623. reset. If neither `fill_value` nor `dtype` are specified (or if
  2624. `dtype` is an ndarray sub-class), then the fill value is preserved.
  2625. Finally, if `fill_value` is specified, but `dtype` is not, the fill
  2626. value is set to the specified value.
  2627. For ``a.view(some_dtype)``, if ``some_dtype`` has a different number of
  2628. bytes per entry than the previous dtype (for example, converting a
  2629. regular array to a structured array), then the behavior of the view
  2630. cannot be predicted just from the superficial appearance of ``a`` (shown
  2631. by ``print(a)``). It also depends on exactly how ``a`` is stored in
  2632. memory. Therefore if ``a`` is C-ordered versus fortran-ordered, versus
  2633. defined as a slice or transpose, etc., the view may give different
  2634. results.
  2635. """
  2636. if dtype is None:
  2637. if type is None:
  2638. output = ndarray.view(self)
  2639. else:
  2640. output = ndarray.view(self, type)
  2641. elif type is None:
  2642. try:
  2643. if issubclass(dtype, ndarray):
  2644. output = ndarray.view(self, dtype)
  2645. dtype = None
  2646. else:
  2647. output = ndarray.view(self, dtype)
  2648. except TypeError:
  2649. output = ndarray.view(self, dtype)
  2650. else:
  2651. output = ndarray.view(self, dtype, type)
  2652. # also make the mask be a view (so attr changes to the view's
  2653. # mask do no affect original object's mask)
  2654. # (especially important to avoid affecting np.masked singleton)
  2655. if getmask(output) is not nomask:
  2656. output._mask = output._mask.view()
  2657. # Make sure to reset the _fill_value if needed
  2658. if getattr(output, '_fill_value', None) is not None:
  2659. if fill_value is None:
  2660. if dtype is None:
  2661. pass # leave _fill_value as is
  2662. else:
  2663. output._fill_value = None
  2664. else:
  2665. output.fill_value = fill_value
  2666. return output
  2667. def __getitem__(self, indx):
  2668. """
  2669. x.__getitem__(y) <==> x[y]
  2670. Return the item described by i, as a masked array.
  2671. """
  2672. # We could directly use ndarray.__getitem__ on self.
  2673. # But then we would have to modify __array_finalize__ to prevent the
  2674. # mask of being reshaped if it hasn't been set up properly yet
  2675. # So it's easier to stick to the current version
  2676. dout = self.data[indx]
  2677. _mask = self._mask
  2678. def _is_scalar(m):
  2679. return not isinstance(m, np.ndarray)
  2680. def _scalar_heuristic(arr, elem):
  2681. """
  2682. Return whether `elem` is a scalar result of indexing `arr`, or None
  2683. if undecidable without promoting nomask to a full mask
  2684. """
  2685. # obviously a scalar
  2686. if not isinstance(elem, np.ndarray):
  2687. return True
  2688. # object array scalar indexing can return anything
  2689. elif arr.dtype.type is np.object_:
  2690. if arr.dtype is not elem.dtype:
  2691. # elem is an array, but dtypes do not match, so must be
  2692. # an element
  2693. return True
  2694. # well-behaved subclass that only returns 0d arrays when
  2695. # expected - this is not a scalar
  2696. elif type(arr).__getitem__ == ndarray.__getitem__:
  2697. return False
  2698. return None
  2699. if _mask is not nomask:
  2700. # _mask cannot be a subclass, so it tells us whether we should
  2701. # expect a scalar. It also cannot be of dtype object.
  2702. mout = _mask[indx]
  2703. scalar_expected = _is_scalar(mout)
  2704. else:
  2705. # attempt to apply the heuristic to avoid constructing a full mask
  2706. mout = nomask
  2707. scalar_expected = _scalar_heuristic(self.data, dout)
  2708. if scalar_expected is None:
  2709. # heuristics have failed
  2710. # construct a full array, so we can be certain. This is costly.
  2711. # we could also fall back on ndarray.__getitem__(self.data, indx)
  2712. scalar_expected = _is_scalar(getmaskarray(self)[indx])
  2713. # Did we extract a single item?
  2714. if scalar_expected:
  2715. # A record
  2716. if isinstance(dout, np.void):
  2717. # We should always re-cast to mvoid, otherwise users can
  2718. # change masks on rows that already have masked values, but not
  2719. # on rows that have no masked values, which is inconsistent.
  2720. return mvoid(dout, mask=mout, hardmask=self._hardmask)
  2721. # special case introduced in gh-5962
  2722. elif (self.dtype.type is np.object_ and
  2723. isinstance(dout, np.ndarray) and
  2724. dout is not masked):
  2725. # If masked, turn into a MaskedArray, with everything masked.
  2726. if mout:
  2727. return MaskedArray(dout, mask=True)
  2728. else:
  2729. return dout
  2730. # Just a scalar
  2731. else:
  2732. if mout:
  2733. return masked
  2734. else:
  2735. return dout
  2736. else:
  2737. # Force dout to MA
  2738. dout = dout.view(type(self))
  2739. # Inherit attributes from self
  2740. dout._update_from(self)
  2741. # Check the fill_value
  2742. if is_string_or_list_of_strings(indx):
  2743. if self._fill_value is not None:
  2744. dout._fill_value = self._fill_value[indx]
  2745. # Something like gh-15895 has happened if this check fails.
  2746. # _fill_value should always be an ndarray.
  2747. if not isinstance(dout._fill_value, np.ndarray):
  2748. raise RuntimeError('Internal NumPy error.')
  2749. # If we're indexing a multidimensional field in a
  2750. # structured array (such as dtype("(2,)i2,(2,)i1")),
  2751. # dimensionality goes up (M[field].ndim == M.ndim +
  2752. # M.dtype[field].ndim). That's fine for
  2753. # M[field] but problematic for M[field].fill_value
  2754. # which should have shape () to avoid breaking several
  2755. # methods. There is no great way out, so set to
  2756. # first element. See issue #6723.
  2757. if dout._fill_value.ndim > 0:
  2758. if not (dout._fill_value ==
  2759. dout._fill_value.flat[0]).all():
  2760. warnings.warn(
  2761. "Upon accessing multidimensional field "
  2762. f"{indx!s}, need to keep dimensionality "
  2763. "of fill_value at 0. Discarding "
  2764. "heterogeneous fill_value and setting "
  2765. f"all to {dout._fill_value[0]!s}.",
  2766. stacklevel=2)
  2767. # Need to use `.flat[0:1].squeeze(...)` instead of just
  2768. # `.flat[0]` to ensure the result is a 0d array and not
  2769. # a scalar.
  2770. dout._fill_value = dout._fill_value.flat[0:1].squeeze(axis=0)
  2771. dout._isfield = True
  2772. # Update the mask if needed
  2773. if mout is not nomask:
  2774. # set shape to match that of data; this is needed for matrices
  2775. dout._mask = reshape(mout, dout.shape)
  2776. dout._sharedmask = True
  2777. # Note: Don't try to check for m.any(), that'll take too long
  2778. return dout
  2779. def __setitem__(self, indx, value):
  2780. """
  2781. x.__setitem__(i, y) <==> x[i]=y
  2782. Set item described by index. If value is masked, masks those
  2783. locations.
  2784. """
  2785. if self is masked:
  2786. raise MaskError('Cannot alter the masked element.')
  2787. _data = self._data
  2788. _mask = self._mask
  2789. if isinstance(indx, str):
  2790. _data[indx] = value
  2791. if _mask is nomask:
  2792. self._mask = _mask = make_mask_none(self.shape, self.dtype)
  2793. _mask[indx] = getmask(value)
  2794. return
  2795. _dtype = _data.dtype
  2796. if value is masked:
  2797. # The mask wasn't set: create a full version.
  2798. if _mask is nomask:
  2799. _mask = self._mask = make_mask_none(self.shape, _dtype)
  2800. # Now, set the mask to its value.
  2801. if _dtype.names is not None:
  2802. _mask[indx] = tuple([True] * len(_dtype.names))
  2803. else:
  2804. _mask[indx] = True
  2805. return
  2806. # Get the _data part of the new value
  2807. dval = getattr(value, '_data', value)
  2808. # Get the _mask part of the new value
  2809. mval = getmask(value)
  2810. if _dtype.names is not None and mval is nomask:
  2811. mval = tuple([False] * len(_dtype.names))
  2812. if _mask is nomask:
  2813. # Set the data, then the mask
  2814. _data[indx] = dval
  2815. if mval is not nomask:
  2816. _mask = self._mask = make_mask_none(self.shape, _dtype)
  2817. _mask[indx] = mval
  2818. elif not self._hardmask:
  2819. # Set the data, then the mask
  2820. _data[indx] = dval
  2821. _mask[indx] = mval
  2822. elif hasattr(indx, 'dtype') and (indx.dtype == MaskType):
  2823. indx = indx * umath.logical_not(_mask)
  2824. _data[indx] = dval
  2825. else:
  2826. if _dtype.names is not None:
  2827. err_msg = "Flexible 'hard' masks are not yet supported."
  2828. raise NotImplementedError(err_msg)
  2829. mindx = mask_or(_mask[indx], mval, copy=True)
  2830. dindx = self._data[indx]
  2831. if dindx.size > 1:
  2832. np.copyto(dindx, dval, where=~mindx)
  2833. elif mindx is nomask:
  2834. dindx = dval
  2835. _data[indx] = dindx
  2836. _mask[indx] = mindx
  2837. return
  2838. # Define so that we can overwrite the setter.
  2839. @property
  2840. def dtype(self):
  2841. return super(MaskedArray, self).dtype
  2842. @dtype.setter
  2843. def dtype(self, dtype):
  2844. super(MaskedArray, type(self)).dtype.__set__(self, dtype)
  2845. if self._mask is not nomask:
  2846. self._mask = self._mask.view(make_mask_descr(dtype), ndarray)
  2847. # Try to reset the shape of the mask (if we don't have a void).
  2848. # This raises a ValueError if the dtype change won't work.
  2849. try:
  2850. self._mask.shape = self.shape
  2851. except (AttributeError, TypeError):
  2852. pass
  2853. @property
  2854. def shape(self):
  2855. return super(MaskedArray, self).shape
  2856. @shape.setter
  2857. def shape(self, shape):
  2858. super(MaskedArray, type(self)).shape.__set__(self, shape)
  2859. # Cannot use self._mask, since it may not (yet) exist when a
  2860. # masked matrix sets the shape.
  2861. if getmask(self) is not nomask:
  2862. self._mask.shape = self.shape
  2863. def __setmask__(self, mask, copy=False):
  2864. """
  2865. Set the mask.
  2866. """
  2867. idtype = self.dtype
  2868. current_mask = self._mask
  2869. if mask is masked:
  2870. mask = True
  2871. if current_mask is nomask:
  2872. # Make sure the mask is set
  2873. # Just don't do anything if there's nothing to do.
  2874. if mask is nomask:
  2875. return
  2876. current_mask = self._mask = make_mask_none(self.shape, idtype)
  2877. if idtype.names is None:
  2878. # No named fields.
  2879. # Hardmask: don't unmask the data
  2880. if self._hardmask:
  2881. current_mask |= mask
  2882. # Softmask: set everything to False
  2883. # If it's obviously a compatible scalar, use a quick update
  2884. # method.
  2885. elif isinstance(mask, (int, float, np.bool_, np.number)):
  2886. current_mask[...] = mask
  2887. # Otherwise fall back to the slower, general purpose way.
  2888. else:
  2889. current_mask.flat = mask
  2890. else:
  2891. # Named fields w/
  2892. mdtype = current_mask.dtype
  2893. mask = np.array(mask, copy=False)
  2894. # Mask is a singleton
  2895. if not mask.ndim:
  2896. # It's a boolean : make a record
  2897. if mask.dtype.kind == 'b':
  2898. mask = np.array(tuple([mask.item()] * len(mdtype)),
  2899. dtype=mdtype)
  2900. # It's a record: make sure the dtype is correct
  2901. else:
  2902. mask = mask.astype(mdtype)
  2903. # Mask is a sequence
  2904. else:
  2905. # Make sure the new mask is a ndarray with the proper dtype
  2906. try:
  2907. mask = np.array(mask, copy=copy, dtype=mdtype)
  2908. # Or assume it's a sequence of bool/int
  2909. except TypeError:
  2910. mask = np.array([tuple([m] * len(mdtype)) for m in mask],
  2911. dtype=mdtype)
  2912. # Hardmask: don't unmask the data
  2913. if self._hardmask:
  2914. for n in idtype.names:
  2915. current_mask[n] |= mask[n]
  2916. # Softmask: set everything to False
  2917. # If it's obviously a compatible scalar, use a quick update
  2918. # method.
  2919. elif isinstance(mask, (int, float, np.bool_, np.number)):
  2920. current_mask[...] = mask
  2921. # Otherwise fall back to the slower, general purpose way.
  2922. else:
  2923. current_mask.flat = mask
  2924. # Reshape if needed
  2925. if current_mask.shape:
  2926. current_mask.shape = self.shape
  2927. return
  2928. _set_mask = __setmask__
  2929. @property
  2930. def mask(self):
  2931. """ Current mask. """
  2932. # We could try to force a reshape, but that wouldn't work in some
  2933. # cases.
  2934. # Return a view so that the dtype and shape cannot be changed in place
  2935. # This still preserves nomask by identity
  2936. return self._mask.view()
  2937. @mask.setter
  2938. def mask(self, value):
  2939. self.__setmask__(value)
  2940. @property
  2941. def recordmask(self):
  2942. """
  2943. Get or set the mask of the array if it has no named fields. For
  2944. structured arrays, returns a ndarray of booleans where entries are
  2945. ``True`` if **all** the fields are masked, ``False`` otherwise:
  2946. >>> x = np.ma.array([(1, 1), (2, 2), (3, 3), (4, 4), (5, 5)],
  2947. ... mask=[(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)],
  2948. ... dtype=[('a', int), ('b', int)])
  2949. >>> x.recordmask
  2950. array([False, False, True, False, False])
  2951. """
  2952. _mask = self._mask.view(ndarray)
  2953. if _mask.dtype.names is None:
  2954. return _mask
  2955. return np.all(flatten_structured_array(_mask), axis=-1)
  2956. @recordmask.setter
  2957. def recordmask(self, mask):
  2958. raise NotImplementedError("Coming soon: setting the mask per records!")
  2959. def harden_mask(self):
  2960. """
  2961. Force the mask to hard.
  2962. Whether the mask of a masked array is hard or soft is determined by
  2963. its `~ma.MaskedArray.hardmask` property. `harden_mask` sets
  2964. `~ma.MaskedArray.hardmask` to ``True``.
  2965. See Also
  2966. --------
  2967. ma.MaskedArray.hardmask
  2968. """
  2969. self._hardmask = True
  2970. return self
  2971. def soften_mask(self):
  2972. """
  2973. Force the mask to soft.
  2974. Whether the mask of a masked array is hard or soft is determined by
  2975. its `~ma.MaskedArray.hardmask` property. `soften_mask` sets
  2976. `~ma.MaskedArray.hardmask` to ``False``.
  2977. See Also
  2978. --------
  2979. ma.MaskedArray.hardmask
  2980. """
  2981. self._hardmask = False
  2982. return self
  2983. @property
  2984. def hardmask(self):
  2985. """ Hardness of the mask """
  2986. return self._hardmask
  2987. def unshare_mask(self):
  2988. """
  2989. Copy the mask and set the sharedmask flag to False.
  2990. Whether the mask is shared between masked arrays can be seen from
  2991. the `sharedmask` property. `unshare_mask` ensures the mask is not shared.
  2992. A copy of the mask is only made if it was shared.
  2993. See Also
  2994. --------
  2995. sharedmask
  2996. """
  2997. if self._sharedmask:
  2998. self._mask = self._mask.copy()
  2999. self._sharedmask = False
  3000. return self
  3001. @property
  3002. def sharedmask(self):
  3003. """ Share status of the mask (read-only). """
  3004. return self._sharedmask
  3005. def shrink_mask(self):
  3006. """
  3007. Reduce a mask to nomask when possible.
  3008. Parameters
  3009. ----------
  3010. None
  3011. Returns
  3012. -------
  3013. None
  3014. Examples
  3015. --------
  3016. >>> x = np.ma.array([[1,2 ], [3, 4]], mask=[0]*4)
  3017. >>> x.mask
  3018. array([[False, False],
  3019. [False, False]])
  3020. >>> x.shrink_mask()
  3021. masked_array(
  3022. data=[[1, 2],
  3023. [3, 4]],
  3024. mask=False,
  3025. fill_value=999999)
  3026. >>> x.mask
  3027. False
  3028. """
  3029. self._mask = _shrink_mask(self._mask)
  3030. return self
  3031. @property
  3032. def baseclass(self):
  3033. """ Class of the underlying data (read-only). """
  3034. return self._baseclass
  3035. def _get_data(self):
  3036. """
  3037. Returns the underlying data, as a view of the masked array.
  3038. If the underlying data is a subclass of :class:`numpy.ndarray`, it is
  3039. returned as such.
  3040. >>> x = np.ma.array(np.matrix([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
  3041. >>> x.data
  3042. matrix([[1, 2],
  3043. [3, 4]])
  3044. The type of the data can be accessed through the :attr:`baseclass`
  3045. attribute.
  3046. """
  3047. return ndarray.view(self, self._baseclass)
  3048. _data = property(fget=_get_data)
  3049. data = property(fget=_get_data)
  3050. @property
  3051. def flat(self):
  3052. """ Return a flat iterator, or set a flattened version of self to value. """
  3053. return MaskedIterator(self)
  3054. @flat.setter
  3055. def flat(self, value):
  3056. y = self.ravel()
  3057. y[:] = value
  3058. @property
  3059. def fill_value(self):
  3060. """
  3061. The filling value of the masked array is a scalar. When setting, None
  3062. will set to a default based on the data type.
  3063. Examples
  3064. --------
  3065. >>> for dt in [np.int32, np.int64, np.float64, np.complex128]:
  3066. ... np.ma.array([0, 1], dtype=dt).get_fill_value()
  3067. ...
  3068. 999999
  3069. 999999
  3070. 1e+20
  3071. (1e+20+0j)
  3072. >>> x = np.ma.array([0, 1.], fill_value=-np.inf)
  3073. >>> x.fill_value
  3074. -inf
  3075. >>> x.fill_value = np.pi
  3076. >>> x.fill_value
  3077. 3.1415926535897931 # may vary
  3078. Reset to default:
  3079. >>> x.fill_value = None
  3080. >>> x.fill_value
  3081. 1e+20
  3082. """
  3083. if self._fill_value is None:
  3084. self._fill_value = _check_fill_value(None, self.dtype)
  3085. # Temporary workaround to account for the fact that str and bytes
  3086. # scalars cannot be indexed with (), whereas all other numpy
  3087. # scalars can. See issues #7259 and #7267.
  3088. # The if-block can be removed after #7267 has been fixed.
  3089. if isinstance(self._fill_value, ndarray):
  3090. return self._fill_value[()]
  3091. return self._fill_value
  3092. @fill_value.setter
  3093. def fill_value(self, value=None):
  3094. target = _check_fill_value(value, self.dtype)
  3095. if not target.ndim == 0:
  3096. # 2019-11-12, 1.18.0
  3097. warnings.warn(
  3098. "Non-scalar arrays for the fill value are deprecated. Use "
  3099. "arrays with scalar values instead. The filled function "
  3100. "still supports any array as `fill_value`.",
  3101. DeprecationWarning, stacklevel=2)
  3102. _fill_value = self._fill_value
  3103. if _fill_value is None:
  3104. # Create the attribute if it was undefined
  3105. self._fill_value = target
  3106. else:
  3107. # Don't overwrite the attribute, just fill it (for propagation)
  3108. _fill_value[()] = target
  3109. # kept for compatibility
  3110. get_fill_value = fill_value.fget
  3111. set_fill_value = fill_value.fset
  3112. def filled(self, fill_value=None):
  3113. """
  3114. Return a copy of self, with masked values filled with a given value.
  3115. **However**, if there are no masked values to fill, self will be
  3116. returned instead as an ndarray.
  3117. Parameters
  3118. ----------
  3119. fill_value : array_like, optional
  3120. The value to use for invalid entries. Can be scalar or non-scalar.
  3121. If non-scalar, the resulting ndarray must be broadcastable over
  3122. input array. Default is None, in which case, the `fill_value`
  3123. attribute of the array is used instead.
  3124. Returns
  3125. -------
  3126. filled_array : ndarray
  3127. A copy of ``self`` with invalid entries replaced by *fill_value*
  3128. (be it the function argument or the attribute of ``self``), or
  3129. ``self`` itself as an ndarray if there are no invalid entries to
  3130. be replaced.
  3131. Notes
  3132. -----
  3133. The result is **not** a MaskedArray!
  3134. Examples
  3135. --------
  3136. >>> x = np.ma.array([1,2,3,4,5], mask=[0,0,1,0,1], fill_value=-999)
  3137. >>> x.filled()
  3138. array([ 1, 2, -999, 4, -999])
  3139. >>> x.filled(fill_value=1000)
  3140. array([ 1, 2, 1000, 4, 1000])
  3141. >>> type(x.filled())
  3142. <class 'numpy.ndarray'>
  3143. Subclassing is preserved. This means that if, e.g., the data part of
  3144. the masked array is a recarray, `filled` returns a recarray:
  3145. >>> x = np.array([(-1, 2), (-3, 4)], dtype='i8,i8').view(np.recarray)
  3146. >>> m = np.ma.array(x, mask=[(True, False), (False, True)])
  3147. >>> m.filled()
  3148. rec.array([(999999, 2), ( -3, 999999)],
  3149. dtype=[('f0', '<i8'), ('f1', '<i8')])
  3150. """
  3151. m = self._mask
  3152. if m is nomask:
  3153. return self._data
  3154. if fill_value is None:
  3155. fill_value = self.fill_value
  3156. else:
  3157. fill_value = _check_fill_value(fill_value, self.dtype)
  3158. if self is masked_singleton:
  3159. return np.asanyarray(fill_value)
  3160. if m.dtype.names is not None:
  3161. result = self._data.copy('K')
  3162. _recursive_filled(result, self._mask, fill_value)
  3163. elif not m.any():
  3164. return self._data
  3165. else:
  3166. result = self._data.copy('K')
  3167. try:
  3168. np.copyto(result, fill_value, where=m)
  3169. except (TypeError, AttributeError):
  3170. fill_value = narray(fill_value, dtype=object)
  3171. d = result.astype(object)
  3172. result = np.choose(m, (d, fill_value))
  3173. except IndexError:
  3174. # ok, if scalar
  3175. if self._data.shape:
  3176. raise
  3177. elif m:
  3178. result = np.array(fill_value, dtype=self.dtype)
  3179. else:
  3180. result = self._data
  3181. return result
  3182. def compressed(self):
  3183. """
  3184. Return all the non-masked data as a 1-D array.
  3185. Returns
  3186. -------
  3187. data : ndarray
  3188. A new `ndarray` holding the non-masked data is returned.
  3189. Notes
  3190. -----
  3191. The result is **not** a MaskedArray!
  3192. Examples
  3193. --------
  3194. >>> x = np.ma.array(np.arange(5), mask=[0]*2 + [1]*3)
  3195. >>> x.compressed()
  3196. array([0, 1])
  3197. >>> type(x.compressed())
  3198. <class 'numpy.ndarray'>
  3199. """
  3200. data = ndarray.ravel(self._data)
  3201. if self._mask is not nomask:
  3202. data = data.compress(np.logical_not(ndarray.ravel(self._mask)))
  3203. return data
  3204. def compress(self, condition, axis=None, out=None):
  3205. """
  3206. Return `a` where condition is ``True``.
  3207. If condition is a `~ma.MaskedArray`, missing values are considered
  3208. as ``False``.
  3209. Parameters
  3210. ----------
  3211. condition : var
  3212. Boolean 1-d array selecting which entries to return. If len(condition)
  3213. is less than the size of a along the axis, then output is truncated
  3214. to length of condition array.
  3215. axis : {None, int}, optional
  3216. Axis along which the operation must be performed.
  3217. out : {None, ndarray}, optional
  3218. Alternative output array in which to place the result. It must have
  3219. the same shape as the expected output but the type will be cast if
  3220. necessary.
  3221. Returns
  3222. -------
  3223. result : MaskedArray
  3224. A :class:`~ma.MaskedArray` object.
  3225. Notes
  3226. -----
  3227. Please note the difference with :meth:`compressed` !
  3228. The output of :meth:`compress` has a mask, the output of
  3229. :meth:`compressed` does not.
  3230. Examples
  3231. --------
  3232. >>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
  3233. >>> x
  3234. masked_array(
  3235. data=[[1, --, 3],
  3236. [--, 5, --],
  3237. [7, --, 9]],
  3238. mask=[[False, True, False],
  3239. [ True, False, True],
  3240. [False, True, False]],
  3241. fill_value=999999)
  3242. >>> x.compress([1, 0, 1])
  3243. masked_array(data=[1, 3],
  3244. mask=[False, False],
  3245. fill_value=999999)
  3246. >>> x.compress([1, 0, 1], axis=1)
  3247. masked_array(
  3248. data=[[1, 3],
  3249. [--, --],
  3250. [7, 9]],
  3251. mask=[[False, False],
  3252. [ True, True],
  3253. [False, False]],
  3254. fill_value=999999)
  3255. """
  3256. # Get the basic components
  3257. (_data, _mask) = (self._data, self._mask)
  3258. # Force the condition to a regular ndarray and forget the missing
  3259. # values.
  3260. condition = np.array(condition, copy=False, subok=False)
  3261. _new = _data.compress(condition, axis=axis, out=out).view(type(self))
  3262. _new._update_from(self)
  3263. if _mask is not nomask:
  3264. _new._mask = _mask.compress(condition, axis=axis)
  3265. return _new
  3266. def _insert_masked_print(self):
  3267. """
  3268. Replace masked values with masked_print_option, casting all innermost
  3269. dtypes to object.
  3270. """
  3271. if masked_print_option.enabled():
  3272. mask = self._mask
  3273. if mask is nomask:
  3274. res = self._data
  3275. else:
  3276. # convert to object array to make filled work
  3277. data = self._data
  3278. # For big arrays, to avoid a costly conversion to the
  3279. # object dtype, extract the corners before the conversion.
  3280. print_width = (self._print_width if self.ndim > 1
  3281. else self._print_width_1d)
  3282. for axis in range(self.ndim):
  3283. if data.shape[axis] > print_width:
  3284. ind = print_width // 2
  3285. arr = np.split(data, (ind, -ind), axis=axis)
  3286. data = np.concatenate((arr[0], arr[2]), axis=axis)
  3287. arr = np.split(mask, (ind, -ind), axis=axis)
  3288. mask = np.concatenate((arr[0], arr[2]), axis=axis)
  3289. rdtype = _replace_dtype_fields(self.dtype, "O")
  3290. res = data.astype(rdtype)
  3291. _recursive_printoption(res, mask, masked_print_option)
  3292. else:
  3293. res = self.filled(self.fill_value)
  3294. return res
  3295. def __str__(self):
  3296. return str(self._insert_masked_print())
  3297. def __repr__(self):
  3298. """
  3299. Literal string representation.
  3300. """
  3301. if self._baseclass is np.ndarray:
  3302. name = 'array'
  3303. else:
  3304. name = self._baseclass.__name__
  3305. # 2016-11-19: Demoted to legacy format
  3306. if np.get_printoptions()['legacy'] == '1.13':
  3307. is_long = self.ndim > 1
  3308. parameters = dict(
  3309. name=name,
  3310. nlen=" " * len(name),
  3311. data=str(self),
  3312. mask=str(self._mask),
  3313. fill=str(self.fill_value),
  3314. dtype=str(self.dtype)
  3315. )
  3316. is_structured = bool(self.dtype.names)
  3317. key = '{}_{}'.format(
  3318. 'long' if is_long else 'short',
  3319. 'flx' if is_structured else 'std'
  3320. )
  3321. return _legacy_print_templates[key] % parameters
  3322. prefix = f"masked_{name}("
  3323. dtype_needed = (
  3324. not np.core.arrayprint.dtype_is_implied(self.dtype) or
  3325. np.all(self.mask) or
  3326. self.size == 0
  3327. )
  3328. # determine which keyword args need to be shown
  3329. keys = ['data', 'mask', 'fill_value']
  3330. if dtype_needed:
  3331. keys.append('dtype')
  3332. # array has only one row (non-column)
  3333. is_one_row = builtins.all(dim == 1 for dim in self.shape[:-1])
  3334. # choose what to indent each keyword with
  3335. min_indent = 2
  3336. if is_one_row:
  3337. # first key on the same line as the type, remaining keys
  3338. # aligned by equals
  3339. indents = {}
  3340. indents[keys[0]] = prefix
  3341. for k in keys[1:]:
  3342. n = builtins.max(min_indent, len(prefix + keys[0]) - len(k))
  3343. indents[k] = ' ' * n
  3344. prefix = '' # absorbed into the first indent
  3345. else:
  3346. # each key on its own line, indented by two spaces
  3347. indents = {k: ' ' * min_indent for k in keys}
  3348. prefix = prefix + '\n' # first key on the next line
  3349. # format the field values
  3350. reprs = {}
  3351. reprs['data'] = np.array2string(
  3352. self._insert_masked_print(),
  3353. separator=", ",
  3354. prefix=indents['data'] + 'data=',
  3355. suffix=',')
  3356. reprs['mask'] = np.array2string(
  3357. self._mask,
  3358. separator=", ",
  3359. prefix=indents['mask'] + 'mask=',
  3360. suffix=',')
  3361. reprs['fill_value'] = repr(self.fill_value)
  3362. if dtype_needed:
  3363. reprs['dtype'] = np.core.arrayprint.dtype_short_repr(self.dtype)
  3364. # join keys with values and indentations
  3365. result = ',\n'.join(
  3366. '{}{}={}'.format(indents[k], k, reprs[k])
  3367. for k in keys
  3368. )
  3369. return prefix + result + ')'
  3370. def _delegate_binop(self, other):
  3371. # This emulates the logic in
  3372. # private/binop_override.h:forward_binop_should_defer
  3373. if isinstance(other, type(self)):
  3374. return False
  3375. array_ufunc = getattr(other, "__array_ufunc__", False)
  3376. if array_ufunc is False:
  3377. other_priority = getattr(other, "__array_priority__", -1000000)
  3378. return self.__array_priority__ < other_priority
  3379. else:
  3380. # If array_ufunc is not None, it will be called inside the ufunc;
  3381. # None explicitly tells us to not call the ufunc, i.e., defer.
  3382. return array_ufunc is None
  3383. def _comparison(self, other, compare):
  3384. """Compare self with other using operator.eq or operator.ne.
  3385. When either of the elements is masked, the result is masked as well,
  3386. but the underlying boolean data are still set, with self and other
  3387. considered equal if both are masked, and unequal otherwise.
  3388. For structured arrays, all fields are combined, with masked values
  3389. ignored. The result is masked if all fields were masked, with self
  3390. and other considered equal only if both were fully masked.
  3391. """
  3392. omask = getmask(other)
  3393. smask = self.mask
  3394. mask = mask_or(smask, omask, copy=True)
  3395. odata = getdata(other)
  3396. if mask.dtype.names is not None:
  3397. # For possibly masked structured arrays we need to be careful,
  3398. # since the standard structured array comparison will use all
  3399. # fields, masked or not. To avoid masked fields influencing the
  3400. # outcome, we set all masked fields in self to other, so they'll
  3401. # count as equal. To prepare, we ensure we have the right shape.
  3402. broadcast_shape = np.broadcast(self, odata).shape
  3403. sbroadcast = np.broadcast_to(self, broadcast_shape, subok=True)
  3404. sbroadcast._mask = mask
  3405. sdata = sbroadcast.filled(odata)
  3406. # Now take care of the mask; the merged mask should have an item
  3407. # masked if all fields were masked (in one and/or other).
  3408. mask = (mask == np.ones((), mask.dtype))
  3409. else:
  3410. # For regular arrays, just use the data as they come.
  3411. sdata = self.data
  3412. check = compare(sdata, odata)
  3413. if isinstance(check, (np.bool_, bool)):
  3414. return masked if mask else check
  3415. if mask is not nomask:
  3416. # Adjust elements that were masked, which should be treated
  3417. # as equal if masked in both, unequal if masked in one.
  3418. # Note that this works automatically for structured arrays too.
  3419. check = np.where(mask, compare(smask, omask), check)
  3420. if mask.shape != check.shape:
  3421. # Guarantee consistency of the shape, making a copy since the
  3422. # the mask may need to get written to later.
  3423. mask = np.broadcast_to(mask, check.shape).copy()
  3424. check = check.view(type(self))
  3425. check._update_from(self)
  3426. check._mask = mask
  3427. # Cast fill value to bool_ if needed. If it cannot be cast, the
  3428. # default boolean fill value is used.
  3429. if check._fill_value is not None:
  3430. try:
  3431. fill = _check_fill_value(check._fill_value, np.bool_)
  3432. except (TypeError, ValueError):
  3433. fill = _check_fill_value(None, np.bool_)
  3434. check._fill_value = fill
  3435. return check
  3436. def __eq__(self, other):
  3437. """Check whether other equals self elementwise.
  3438. When either of the elements is masked, the result is masked as well,
  3439. but the underlying boolean data are still set, with self and other
  3440. considered equal if both are masked, and unequal otherwise.
  3441. For structured arrays, all fields are combined, with masked values
  3442. ignored. The result is masked if all fields were masked, with self
  3443. and other considered equal only if both were fully masked.
  3444. """
  3445. return self._comparison(other, operator.eq)
  3446. def __ne__(self, other):
  3447. """Check whether other does not equal self elementwise.
  3448. When either of the elements is masked, the result is masked as well,
  3449. but the underlying boolean data are still set, with self and other
  3450. considered equal if both are masked, and unequal otherwise.
  3451. For structured arrays, all fields are combined, with masked values
  3452. ignored. The result is masked if all fields were masked, with self
  3453. and other considered equal only if both were fully masked.
  3454. """
  3455. return self._comparison(other, operator.ne)
  3456. def __add__(self, other):
  3457. """
  3458. Add self to other, and return a new masked array.
  3459. """
  3460. if self._delegate_binop(other):
  3461. return NotImplemented
  3462. return add(self, other)
  3463. def __radd__(self, other):
  3464. """
  3465. Add other to self, and return a new masked array.
  3466. """
  3467. # In analogy with __rsub__ and __rdiv__, use original order:
  3468. # we get here from `other + self`.
  3469. return add(other, self)
  3470. def __sub__(self, other):
  3471. """
  3472. Subtract other from self, and return a new masked array.
  3473. """
  3474. if self._delegate_binop(other):
  3475. return NotImplemented
  3476. return subtract(self, other)
  3477. def __rsub__(self, other):
  3478. """
  3479. Subtract self from other, and return a new masked array.
  3480. """
  3481. return subtract(other, self)
  3482. def __mul__(self, other):
  3483. "Multiply self by other, and return a new masked array."
  3484. if self._delegate_binop(other):
  3485. return NotImplemented
  3486. return multiply(self, other)
  3487. def __rmul__(self, other):
  3488. """
  3489. Multiply other by self, and return a new masked array.
  3490. """
  3491. # In analogy with __rsub__ and __rdiv__, use original order:
  3492. # we get here from `other * self`.
  3493. return multiply(other, self)
  3494. def __div__(self, other):
  3495. """
  3496. Divide other into self, and return a new masked array.
  3497. """
  3498. if self._delegate_binop(other):
  3499. return NotImplemented
  3500. return divide(self, other)
  3501. def __truediv__(self, other):
  3502. """
  3503. Divide other into self, and return a new masked array.
  3504. """
  3505. if self._delegate_binop(other):
  3506. return NotImplemented
  3507. return true_divide(self, other)
  3508. def __rtruediv__(self, other):
  3509. """
  3510. Divide self into other, and return a new masked array.
  3511. """
  3512. return true_divide(other, self)
  3513. def __floordiv__(self, other):
  3514. """
  3515. Divide other into self, and return a new masked array.
  3516. """
  3517. if self._delegate_binop(other):
  3518. return NotImplemented
  3519. return floor_divide(self, other)
  3520. def __rfloordiv__(self, other):
  3521. """
  3522. Divide self into other, and return a new masked array.
  3523. """
  3524. return floor_divide(other, self)
  3525. def __pow__(self, other):
  3526. """
  3527. Raise self to the power other, masking the potential NaNs/Infs
  3528. """
  3529. if self._delegate_binop(other):
  3530. return NotImplemented
  3531. return power(self, other)
  3532. def __rpow__(self, other):
  3533. """
  3534. Raise other to the power self, masking the potential NaNs/Infs
  3535. """
  3536. return power(other, self)
  3537. def __iadd__(self, other):
  3538. """
  3539. Add other to self in-place.
  3540. """
  3541. m = getmask(other)
  3542. if self._mask is nomask:
  3543. if m is not nomask and m.any():
  3544. self._mask = make_mask_none(self.shape, self.dtype)
  3545. self._mask += m
  3546. else:
  3547. if m is not nomask:
  3548. self._mask += m
  3549. self._data.__iadd__(np.where(self._mask, self.dtype.type(0),
  3550. getdata(other)))
  3551. return self
  3552. def __isub__(self, other):
  3553. """
  3554. Subtract other from self in-place.
  3555. """
  3556. m = getmask(other)
  3557. if self._mask is nomask:
  3558. if m is not nomask and m.any():
  3559. self._mask = make_mask_none(self.shape, self.dtype)
  3560. self._mask += m
  3561. elif m is not nomask:
  3562. self._mask += m
  3563. self._data.__isub__(np.where(self._mask, self.dtype.type(0),
  3564. getdata(other)))
  3565. return self
  3566. def __imul__(self, other):
  3567. """
  3568. Multiply self by other in-place.
  3569. """
  3570. m = getmask(other)
  3571. if self._mask is nomask:
  3572. if m is not nomask and m.any():
  3573. self._mask = make_mask_none(self.shape, self.dtype)
  3574. self._mask += m
  3575. elif m is not nomask:
  3576. self._mask += m
  3577. self._data.__imul__(np.where(self._mask, self.dtype.type(1),
  3578. getdata(other)))
  3579. return self
  3580. def __idiv__(self, other):
  3581. """
  3582. Divide self by other in-place.
  3583. """
  3584. other_data = getdata(other)
  3585. dom_mask = _DomainSafeDivide().__call__(self._data, other_data)
  3586. other_mask = getmask(other)
  3587. new_mask = mask_or(other_mask, dom_mask)
  3588. # The following 3 lines control the domain filling
  3589. if dom_mask.any():
  3590. (_, fval) = ufunc_fills[np.divide]
  3591. other_data = np.where(dom_mask, fval, other_data)
  3592. self._mask |= new_mask
  3593. self._data.__idiv__(np.where(self._mask, self.dtype.type(1),
  3594. other_data))
  3595. return self
  3596. def __ifloordiv__(self, other):
  3597. """
  3598. Floor divide self by other in-place.
  3599. """
  3600. other_data = getdata(other)
  3601. dom_mask = _DomainSafeDivide().__call__(self._data, other_data)
  3602. other_mask = getmask(other)
  3603. new_mask = mask_or(other_mask, dom_mask)
  3604. # The following 3 lines control the domain filling
  3605. if dom_mask.any():
  3606. (_, fval) = ufunc_fills[np.floor_divide]
  3607. other_data = np.where(dom_mask, fval, other_data)
  3608. self._mask |= new_mask
  3609. self._data.__ifloordiv__(np.where(self._mask, self.dtype.type(1),
  3610. other_data))
  3611. return self
  3612. def __itruediv__(self, other):
  3613. """
  3614. True divide self by other in-place.
  3615. """
  3616. other_data = getdata(other)
  3617. dom_mask = _DomainSafeDivide().__call__(self._data, other_data)
  3618. other_mask = getmask(other)
  3619. new_mask = mask_or(other_mask, dom_mask)
  3620. # The following 3 lines control the domain filling
  3621. if dom_mask.any():
  3622. (_, fval) = ufunc_fills[np.true_divide]
  3623. other_data = np.where(dom_mask, fval, other_data)
  3624. self._mask |= new_mask
  3625. self._data.__itruediv__(np.where(self._mask, self.dtype.type(1),
  3626. other_data))
  3627. return self
  3628. def __ipow__(self, other):
  3629. """
  3630. Raise self to the power other, in place.
  3631. """
  3632. other_data = getdata(other)
  3633. other_mask = getmask(other)
  3634. with np.errstate(divide='ignore', invalid='ignore'):
  3635. self._data.__ipow__(np.where(self._mask, self.dtype.type(1),
  3636. other_data))
  3637. invalid = np.logical_not(np.isfinite(self._data))
  3638. if invalid.any():
  3639. if self._mask is not nomask:
  3640. self._mask |= invalid
  3641. else:
  3642. self._mask = invalid
  3643. np.copyto(self._data, self.fill_value, where=invalid)
  3644. new_mask = mask_or(other_mask, invalid)
  3645. self._mask = mask_or(self._mask, new_mask)
  3646. return self
  3647. def __float__(self):
  3648. """
  3649. Convert to float.
  3650. """
  3651. if self.size > 1:
  3652. raise TypeError("Only length-1 arrays can be converted "
  3653. "to Python scalars")
  3654. elif self._mask:
  3655. warnings.warn("Warning: converting a masked element to nan.", stacklevel=2)
  3656. return np.nan
  3657. return float(self.item())
  3658. def __int__(self):
  3659. """
  3660. Convert to int.
  3661. """
  3662. if self.size > 1:
  3663. raise TypeError("Only length-1 arrays can be converted "
  3664. "to Python scalars")
  3665. elif self._mask:
  3666. raise MaskError('Cannot convert masked element to a Python int.')
  3667. return int(self.item())
  3668. @property
  3669. def imag(self):
  3670. """
  3671. The imaginary part of the masked array.
  3672. This property is a view on the imaginary part of this `MaskedArray`.
  3673. See Also
  3674. --------
  3675. real
  3676. Examples
  3677. --------
  3678. >>> x = np.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
  3679. >>> x.imag
  3680. masked_array(data=[1.0, --, 1.6],
  3681. mask=[False, True, False],
  3682. fill_value=1e+20)
  3683. """
  3684. result = self._data.imag.view(type(self))
  3685. result.__setmask__(self._mask)
  3686. return result
  3687. # kept for compatibility
  3688. get_imag = imag.fget
  3689. @property
  3690. def real(self):
  3691. """
  3692. The real part of the masked array.
  3693. This property is a view on the real part of this `MaskedArray`.
  3694. See Also
  3695. --------
  3696. imag
  3697. Examples
  3698. --------
  3699. >>> x = np.ma.array([1+1.j, -2j, 3.45+1.6j], mask=[False, True, False])
  3700. >>> x.real
  3701. masked_array(data=[1.0, --, 3.45],
  3702. mask=[False, True, False],
  3703. fill_value=1e+20)
  3704. """
  3705. result = self._data.real.view(type(self))
  3706. result.__setmask__(self._mask)
  3707. return result
  3708. # kept for compatibility
  3709. get_real = real.fget
  3710. def count(self, axis=None, keepdims=np._NoValue):
  3711. """
  3712. Count the non-masked elements of the array along the given axis.
  3713. Parameters
  3714. ----------
  3715. axis : None or int or tuple of ints, optional
  3716. Axis or axes along which the count is performed.
  3717. The default, None, performs the count over all
  3718. the dimensions of the input array. `axis` may be negative, in
  3719. which case it counts from the last to the first axis.
  3720. .. versionadded:: 1.10.0
  3721. If this is a tuple of ints, the count is performed on multiple
  3722. axes, instead of a single axis or all the axes as before.
  3723. keepdims : bool, optional
  3724. If this is set to True, the axes which are reduced are left
  3725. in the result as dimensions with size one. With this option,
  3726. the result will broadcast correctly against the array.
  3727. Returns
  3728. -------
  3729. result : ndarray or scalar
  3730. An array with the same shape as the input array, with the specified
  3731. axis removed. If the array is a 0-d array, or if `axis` is None, a
  3732. scalar is returned.
  3733. See Also
  3734. --------
  3735. ma.count_masked : Count masked elements in array or along a given axis.
  3736. Examples
  3737. --------
  3738. >>> import numpy.ma as ma
  3739. >>> a = ma.arange(6).reshape((2, 3))
  3740. >>> a[1, :] = ma.masked
  3741. >>> a
  3742. masked_array(
  3743. data=[[0, 1, 2],
  3744. [--, --, --]],
  3745. mask=[[False, False, False],
  3746. [ True, True, True]],
  3747. fill_value=999999)
  3748. >>> a.count()
  3749. 3
  3750. When the `axis` keyword is specified an array of appropriate size is
  3751. returned.
  3752. >>> a.count(axis=0)
  3753. array([1, 1, 1])
  3754. >>> a.count(axis=1)
  3755. array([3, 0])
  3756. """
  3757. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  3758. m = self._mask
  3759. # special case for matrices (we assume no other subclasses modify
  3760. # their dimensions)
  3761. if isinstance(self.data, np.matrix):
  3762. if m is nomask:
  3763. m = np.zeros(self.shape, dtype=np.bool_)
  3764. m = m.view(type(self.data))
  3765. if m is nomask:
  3766. # compare to _count_reduce_items in _methods.py
  3767. if self.shape == ():
  3768. if axis not in (None, 0):
  3769. raise np.AxisError(axis=axis, ndim=self.ndim)
  3770. return 1
  3771. elif axis is None:
  3772. if kwargs.get('keepdims', False):
  3773. return np.array(self.size, dtype=np.intp, ndmin=self.ndim)
  3774. return self.size
  3775. axes = normalize_axis_tuple(axis, self.ndim)
  3776. items = 1
  3777. for ax in axes:
  3778. items *= self.shape[ax]
  3779. if kwargs.get('keepdims', False):
  3780. out_dims = list(self.shape)
  3781. for a in axes:
  3782. out_dims[a] = 1
  3783. else:
  3784. out_dims = [d for n, d in enumerate(self.shape)
  3785. if n not in axes]
  3786. # make sure to return a 0-d array if axis is supplied
  3787. return np.full(out_dims, items, dtype=np.intp)
  3788. # take care of the masked singleton
  3789. if self is masked:
  3790. return 0
  3791. return (~m).sum(axis=axis, dtype=np.intp, **kwargs)
  3792. def ravel(self, order='C'):
  3793. """
  3794. Returns a 1D version of self, as a view.
  3795. Parameters
  3796. ----------
  3797. order : {'C', 'F', 'A', 'K'}, optional
  3798. The elements of `a` are read using this index order. 'C' means to
  3799. index the elements in C-like order, with the last axis index
  3800. changing fastest, back to the first axis index changing slowest.
  3801. 'F' means to index the elements in Fortran-like index order, with
  3802. the first index changing fastest, and the last index changing
  3803. slowest. Note that the 'C' and 'F' options take no account of the
  3804. memory layout of the underlying array, and only refer to the order
  3805. of axis indexing. 'A' means to read the elements in Fortran-like
  3806. index order if `m` is Fortran *contiguous* in memory, C-like order
  3807. otherwise. 'K' means to read the elements in the order they occur
  3808. in memory, except for reversing the data when strides are negative.
  3809. By default, 'C' index order is used.
  3810. Returns
  3811. -------
  3812. MaskedArray
  3813. Output view is of shape ``(self.size,)`` (or
  3814. ``(np.ma.product(self.shape),)``).
  3815. Examples
  3816. --------
  3817. >>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
  3818. >>> x
  3819. masked_array(
  3820. data=[[1, --, 3],
  3821. [--, 5, --],
  3822. [7, --, 9]],
  3823. mask=[[False, True, False],
  3824. [ True, False, True],
  3825. [False, True, False]],
  3826. fill_value=999999)
  3827. >>> x.ravel()
  3828. masked_array(data=[1, --, 3, --, 5, --, 7, --, 9],
  3829. mask=[False, True, False, True, False, True, False, True,
  3830. False],
  3831. fill_value=999999)
  3832. """
  3833. r = ndarray.ravel(self._data, order=order).view(type(self))
  3834. r._update_from(self)
  3835. if self._mask is not nomask:
  3836. r._mask = ndarray.ravel(self._mask, order=order).reshape(r.shape)
  3837. else:
  3838. r._mask = nomask
  3839. return r
  3840. def reshape(self, *s, **kwargs):
  3841. """
  3842. Give a new shape to the array without changing its data.
  3843. Returns a masked array containing the same data, but with a new shape.
  3844. The result is a view on the original array; if this is not possible, a
  3845. ValueError is raised.
  3846. Parameters
  3847. ----------
  3848. shape : int or tuple of ints
  3849. The new shape should be compatible with the original shape. If an
  3850. integer is supplied, then the result will be a 1-D array of that
  3851. length.
  3852. order : {'C', 'F'}, optional
  3853. Determines whether the array data should be viewed as in C
  3854. (row-major) or FORTRAN (column-major) order.
  3855. Returns
  3856. -------
  3857. reshaped_array : array
  3858. A new view on the array.
  3859. See Also
  3860. --------
  3861. reshape : Equivalent function in the masked array module.
  3862. numpy.ndarray.reshape : Equivalent method on ndarray object.
  3863. numpy.reshape : Equivalent function in the NumPy module.
  3864. Notes
  3865. -----
  3866. The reshaping operation cannot guarantee that a copy will not be made,
  3867. to modify the shape in place, use ``a.shape = s``
  3868. Examples
  3869. --------
  3870. >>> x = np.ma.array([[1,2],[3,4]], mask=[1,0,0,1])
  3871. >>> x
  3872. masked_array(
  3873. data=[[--, 2],
  3874. [3, --]],
  3875. mask=[[ True, False],
  3876. [False, True]],
  3877. fill_value=999999)
  3878. >>> x = x.reshape((4,1))
  3879. >>> x
  3880. masked_array(
  3881. data=[[--],
  3882. [2],
  3883. [3],
  3884. [--]],
  3885. mask=[[ True],
  3886. [False],
  3887. [False],
  3888. [ True]],
  3889. fill_value=999999)
  3890. """
  3891. kwargs.update(order=kwargs.get('order', 'C'))
  3892. result = self._data.reshape(*s, **kwargs).view(type(self))
  3893. result._update_from(self)
  3894. mask = self._mask
  3895. if mask is not nomask:
  3896. result._mask = mask.reshape(*s, **kwargs)
  3897. return result
  3898. def resize(self, newshape, refcheck=True, order=False):
  3899. """
  3900. .. warning::
  3901. This method does nothing, except raise a ValueError exception. A
  3902. masked array does not own its data and therefore cannot safely be
  3903. resized in place. Use the `numpy.ma.resize` function instead.
  3904. This method is difficult to implement safely and may be deprecated in
  3905. future releases of NumPy.
  3906. """
  3907. # Note : the 'order' keyword looks broken, let's just drop it
  3908. errmsg = "A masked array does not own its data "\
  3909. "and therefore cannot be resized.\n" \
  3910. "Use the numpy.ma.resize function instead."
  3911. raise ValueError(errmsg)
  3912. def put(self, indices, values, mode='raise'):
  3913. """
  3914. Set storage-indexed locations to corresponding values.
  3915. Sets self._data.flat[n] = values[n] for each n in indices.
  3916. If `values` is shorter than `indices` then it will repeat.
  3917. If `values` has some masked values, the initial mask is updated
  3918. in consequence, else the corresponding values are unmasked.
  3919. Parameters
  3920. ----------
  3921. indices : 1-D array_like
  3922. Target indices, interpreted as integers.
  3923. values : array_like
  3924. Values to place in self._data copy at target indices.
  3925. mode : {'raise', 'wrap', 'clip'}, optional
  3926. Specifies how out-of-bounds indices will behave.
  3927. 'raise' : raise an error.
  3928. 'wrap' : wrap around.
  3929. 'clip' : clip to the range.
  3930. Notes
  3931. -----
  3932. `values` can be a scalar or length 1 array.
  3933. Examples
  3934. --------
  3935. >>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
  3936. >>> x
  3937. masked_array(
  3938. data=[[1, --, 3],
  3939. [--, 5, --],
  3940. [7, --, 9]],
  3941. mask=[[False, True, False],
  3942. [ True, False, True],
  3943. [False, True, False]],
  3944. fill_value=999999)
  3945. >>> x.put([0,4,8],[10,20,30])
  3946. >>> x
  3947. masked_array(
  3948. data=[[10, --, 3],
  3949. [--, 20, --],
  3950. [7, --, 30]],
  3951. mask=[[False, True, False],
  3952. [ True, False, True],
  3953. [False, True, False]],
  3954. fill_value=999999)
  3955. >>> x.put(4,999)
  3956. >>> x
  3957. masked_array(
  3958. data=[[10, --, 3],
  3959. [--, 999, --],
  3960. [7, --, 30]],
  3961. mask=[[False, True, False],
  3962. [ True, False, True],
  3963. [False, True, False]],
  3964. fill_value=999999)
  3965. """
  3966. # Hard mask: Get rid of the values/indices that fall on masked data
  3967. if self._hardmask and self._mask is not nomask:
  3968. mask = self._mask[indices]
  3969. indices = narray(indices, copy=False)
  3970. values = narray(values, copy=False, subok=True)
  3971. values.resize(indices.shape)
  3972. indices = indices[~mask]
  3973. values = values[~mask]
  3974. self._data.put(indices, values, mode=mode)
  3975. # short circuit if neither self nor values are masked
  3976. if self._mask is nomask and getmask(values) is nomask:
  3977. return
  3978. m = getmaskarray(self)
  3979. if getmask(values) is nomask:
  3980. m.put(indices, False, mode=mode)
  3981. else:
  3982. m.put(indices, values._mask, mode=mode)
  3983. m = make_mask(m, copy=False, shrink=True)
  3984. self._mask = m
  3985. return
  3986. def ids(self):
  3987. """
  3988. Return the addresses of the data and mask areas.
  3989. Parameters
  3990. ----------
  3991. None
  3992. Examples
  3993. --------
  3994. >>> x = np.ma.array([1, 2, 3], mask=[0, 1, 1])
  3995. >>> x.ids()
  3996. (166670640, 166659832) # may vary
  3997. If the array has no mask, the address of `nomask` is returned. This address
  3998. is typically not close to the data in memory:
  3999. >>> x = np.ma.array([1, 2, 3])
  4000. >>> x.ids()
  4001. (166691080, 3083169284) # may vary
  4002. """
  4003. if self._mask is nomask:
  4004. return (self.ctypes.data, id(nomask))
  4005. return (self.ctypes.data, self._mask.ctypes.data)
  4006. def iscontiguous(self):
  4007. """
  4008. Return a boolean indicating whether the data is contiguous.
  4009. Parameters
  4010. ----------
  4011. None
  4012. Examples
  4013. --------
  4014. >>> x = np.ma.array([1, 2, 3])
  4015. >>> x.iscontiguous()
  4016. True
  4017. `iscontiguous` returns one of the flags of the masked array:
  4018. >>> x.flags
  4019. C_CONTIGUOUS : True
  4020. F_CONTIGUOUS : True
  4021. OWNDATA : False
  4022. WRITEABLE : True
  4023. ALIGNED : True
  4024. WRITEBACKIFCOPY : False
  4025. UPDATEIFCOPY : False
  4026. """
  4027. return self.flags['CONTIGUOUS']
  4028. def all(self, axis=None, out=None, keepdims=np._NoValue):
  4029. """
  4030. Returns True if all elements evaluate to True.
  4031. The output array is masked where all the values along the given axis
  4032. are masked: if the output would have been a scalar and that all the
  4033. values are masked, then the output is `masked`.
  4034. Refer to `numpy.all` for full documentation.
  4035. See Also
  4036. --------
  4037. numpy.ndarray.all : corresponding function for ndarrays
  4038. numpy.all : equivalent function
  4039. Examples
  4040. --------
  4041. >>> np.ma.array([1,2,3]).all()
  4042. True
  4043. >>> a = np.ma.array([1,2,3], mask=True)
  4044. >>> (a.all() is np.ma.masked)
  4045. True
  4046. """
  4047. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  4048. mask = _check_mask_axis(self._mask, axis, **kwargs)
  4049. if out is None:
  4050. d = self.filled(True).all(axis=axis, **kwargs).view(type(self))
  4051. if d.ndim:
  4052. d.__setmask__(mask)
  4053. elif mask:
  4054. return masked
  4055. return d
  4056. self.filled(True).all(axis=axis, out=out, **kwargs)
  4057. if isinstance(out, MaskedArray):
  4058. if out.ndim or mask:
  4059. out.__setmask__(mask)
  4060. return out
  4061. def any(self, axis=None, out=None, keepdims=np._NoValue):
  4062. """
  4063. Returns True if any of the elements of `a` evaluate to True.
  4064. Masked values are considered as False during computation.
  4065. Refer to `numpy.any` for full documentation.
  4066. See Also
  4067. --------
  4068. numpy.ndarray.any : corresponding function for ndarrays
  4069. numpy.any : equivalent function
  4070. """
  4071. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  4072. mask = _check_mask_axis(self._mask, axis, **kwargs)
  4073. if out is None:
  4074. d = self.filled(False).any(axis=axis, **kwargs).view(type(self))
  4075. if d.ndim:
  4076. d.__setmask__(mask)
  4077. elif mask:
  4078. d = masked
  4079. return d
  4080. self.filled(False).any(axis=axis, out=out, **kwargs)
  4081. if isinstance(out, MaskedArray):
  4082. if out.ndim or mask:
  4083. out.__setmask__(mask)
  4084. return out
  4085. def nonzero(self):
  4086. """
  4087. Return the indices of unmasked elements that are not zero.
  4088. Returns a tuple of arrays, one for each dimension, containing the
  4089. indices of the non-zero elements in that dimension. The corresponding
  4090. non-zero values can be obtained with::
  4091. a[a.nonzero()]
  4092. To group the indices by element, rather than dimension, use
  4093. instead::
  4094. np.transpose(a.nonzero())
  4095. The result of this is always a 2d array, with a row for each non-zero
  4096. element.
  4097. Parameters
  4098. ----------
  4099. None
  4100. Returns
  4101. -------
  4102. tuple_of_arrays : tuple
  4103. Indices of elements that are non-zero.
  4104. See Also
  4105. --------
  4106. numpy.nonzero :
  4107. Function operating on ndarrays.
  4108. flatnonzero :
  4109. Return indices that are non-zero in the flattened version of the input
  4110. array.
  4111. numpy.ndarray.nonzero :
  4112. Equivalent ndarray method.
  4113. count_nonzero :
  4114. Counts the number of non-zero elements in the input array.
  4115. Examples
  4116. --------
  4117. >>> import numpy.ma as ma
  4118. >>> x = ma.array(np.eye(3))
  4119. >>> x
  4120. masked_array(
  4121. data=[[1., 0., 0.],
  4122. [0., 1., 0.],
  4123. [0., 0., 1.]],
  4124. mask=False,
  4125. fill_value=1e+20)
  4126. >>> x.nonzero()
  4127. (array([0, 1, 2]), array([0, 1, 2]))
  4128. Masked elements are ignored.
  4129. >>> x[1, 1] = ma.masked
  4130. >>> x
  4131. masked_array(
  4132. data=[[1.0, 0.0, 0.0],
  4133. [0.0, --, 0.0],
  4134. [0.0, 0.0, 1.0]],
  4135. mask=[[False, False, False],
  4136. [False, True, False],
  4137. [False, False, False]],
  4138. fill_value=1e+20)
  4139. >>> x.nonzero()
  4140. (array([0, 2]), array([0, 2]))
  4141. Indices can also be grouped by element.
  4142. >>> np.transpose(x.nonzero())
  4143. array([[0, 0],
  4144. [2, 2]])
  4145. A common use for ``nonzero`` is to find the indices of an array, where
  4146. a condition is True. Given an array `a`, the condition `a` > 3 is a
  4147. boolean array and since False is interpreted as 0, ma.nonzero(a > 3)
  4148. yields the indices of the `a` where the condition is true.
  4149. >>> a = ma.array([[1,2,3],[4,5,6],[7,8,9]])
  4150. >>> a > 3
  4151. masked_array(
  4152. data=[[False, False, False],
  4153. [ True, True, True],
  4154. [ True, True, True]],
  4155. mask=False,
  4156. fill_value=True)
  4157. >>> ma.nonzero(a > 3)
  4158. (array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))
  4159. The ``nonzero`` method of the condition array can also be called.
  4160. >>> (a > 3).nonzero()
  4161. (array([1, 1, 1, 2, 2, 2]), array([0, 1, 2, 0, 1, 2]))
  4162. """
  4163. return narray(self.filled(0), copy=False).nonzero()
  4164. def trace(self, offset=0, axis1=0, axis2=1, dtype=None, out=None):
  4165. """
  4166. (this docstring should be overwritten)
  4167. """
  4168. #!!!: implement out + test!
  4169. m = self._mask
  4170. if m is nomask:
  4171. result = super(MaskedArray, self).trace(offset=offset, axis1=axis1,
  4172. axis2=axis2, out=out)
  4173. return result.astype(dtype)
  4174. else:
  4175. D = self.diagonal(offset=offset, axis1=axis1, axis2=axis2)
  4176. return D.astype(dtype).filled(0).sum(axis=-1, out=out)
  4177. trace.__doc__ = ndarray.trace.__doc__
  4178. def dot(self, b, out=None, strict=False):
  4179. """
  4180. a.dot(b, out=None)
  4181. Masked dot product of two arrays. Note that `out` and `strict` are
  4182. located in different positions than in `ma.dot`. In order to
  4183. maintain compatibility with the functional version, it is
  4184. recommended that the optional arguments be treated as keyword only.
  4185. At some point that may be mandatory.
  4186. .. versionadded:: 1.10.0
  4187. Parameters
  4188. ----------
  4189. b : masked_array_like
  4190. Inputs array.
  4191. out : masked_array, optional
  4192. Output argument. This must have the exact kind that would be
  4193. returned if it was not used. In particular, it must have the
  4194. right type, must be C-contiguous, and its dtype must be the
  4195. dtype that would be returned for `ma.dot(a,b)`. This is a
  4196. performance feature. Therefore, if these conditions are not
  4197. met, an exception is raised, instead of attempting to be
  4198. flexible.
  4199. strict : bool, optional
  4200. Whether masked data are propagated (True) or set to 0 (False)
  4201. for the computation. Default is False. Propagating the mask
  4202. means that if a masked value appears in a row or column, the
  4203. whole row or column is considered masked.
  4204. .. versionadded:: 1.10.2
  4205. See Also
  4206. --------
  4207. numpy.ma.dot : equivalent function
  4208. """
  4209. return dot(self, b, out=out, strict=strict)
  4210. def sum(self, axis=None, dtype=None, out=None, keepdims=np._NoValue):
  4211. """
  4212. Return the sum of the array elements over the given axis.
  4213. Masked elements are set to 0 internally.
  4214. Refer to `numpy.sum` for full documentation.
  4215. See Also
  4216. --------
  4217. numpy.ndarray.sum : corresponding function for ndarrays
  4218. numpy.sum : equivalent function
  4219. Examples
  4220. --------
  4221. >>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
  4222. >>> x
  4223. masked_array(
  4224. data=[[1, --, 3],
  4225. [--, 5, --],
  4226. [7, --, 9]],
  4227. mask=[[False, True, False],
  4228. [ True, False, True],
  4229. [False, True, False]],
  4230. fill_value=999999)
  4231. >>> x.sum()
  4232. 25
  4233. >>> x.sum(axis=1)
  4234. masked_array(data=[4, 5, 16],
  4235. mask=[False, False, False],
  4236. fill_value=999999)
  4237. >>> x.sum(axis=0)
  4238. masked_array(data=[8, 5, 12],
  4239. mask=[False, False, False],
  4240. fill_value=999999)
  4241. >>> print(type(x.sum(axis=0, dtype=np.int64)[0]))
  4242. <class 'numpy.int64'>
  4243. """
  4244. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  4245. _mask = self._mask
  4246. newmask = _check_mask_axis(_mask, axis, **kwargs)
  4247. # No explicit output
  4248. if out is None:
  4249. result = self.filled(0).sum(axis, dtype=dtype, **kwargs)
  4250. rndim = getattr(result, 'ndim', 0)
  4251. if rndim:
  4252. result = result.view(type(self))
  4253. result.__setmask__(newmask)
  4254. elif newmask:
  4255. result = masked
  4256. return result
  4257. # Explicit output
  4258. result = self.filled(0).sum(axis, dtype=dtype, out=out, **kwargs)
  4259. if isinstance(out, MaskedArray):
  4260. outmask = getmask(out)
  4261. if outmask is nomask:
  4262. outmask = out._mask = make_mask_none(out.shape)
  4263. outmask.flat = newmask
  4264. return out
  4265. def cumsum(self, axis=None, dtype=None, out=None):
  4266. """
  4267. Return the cumulative sum of the array elements over the given axis.
  4268. Masked values are set to 0 internally during the computation.
  4269. However, their position is saved, and the result will be masked at
  4270. the same locations.
  4271. Refer to `numpy.cumsum` for full documentation.
  4272. Notes
  4273. -----
  4274. The mask is lost if `out` is not a valid :class:`ma.MaskedArray` !
  4275. Arithmetic is modular when using integer types, and no error is
  4276. raised on overflow.
  4277. See Also
  4278. --------
  4279. numpy.ndarray.cumsum : corresponding function for ndarrays
  4280. numpy.cumsum : equivalent function
  4281. Examples
  4282. --------
  4283. >>> marr = np.ma.array(np.arange(10), mask=[0,0,0,1,1,1,0,0,0,0])
  4284. >>> marr.cumsum()
  4285. masked_array(data=[0, 1, 3, --, --, --, 9, 16, 24, 33],
  4286. mask=[False, False, False, True, True, True, False, False,
  4287. False, False],
  4288. fill_value=999999)
  4289. """
  4290. result = self.filled(0).cumsum(axis=axis, dtype=dtype, out=out)
  4291. if out is not None:
  4292. if isinstance(out, MaskedArray):
  4293. out.__setmask__(self.mask)
  4294. return out
  4295. result = result.view(type(self))
  4296. result.__setmask__(self._mask)
  4297. return result
  4298. def prod(self, axis=None, dtype=None, out=None, keepdims=np._NoValue):
  4299. """
  4300. Return the product of the array elements over the given axis.
  4301. Masked elements are set to 1 internally for computation.
  4302. Refer to `numpy.prod` for full documentation.
  4303. Notes
  4304. -----
  4305. Arithmetic is modular when using integer types, and no error is raised
  4306. on overflow.
  4307. See Also
  4308. --------
  4309. numpy.ndarray.prod : corresponding function for ndarrays
  4310. numpy.prod : equivalent function
  4311. """
  4312. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  4313. _mask = self._mask
  4314. newmask = _check_mask_axis(_mask, axis, **kwargs)
  4315. # No explicit output
  4316. if out is None:
  4317. result = self.filled(1).prod(axis, dtype=dtype, **kwargs)
  4318. rndim = getattr(result, 'ndim', 0)
  4319. if rndim:
  4320. result = result.view(type(self))
  4321. result.__setmask__(newmask)
  4322. elif newmask:
  4323. result = masked
  4324. return result
  4325. # Explicit output
  4326. result = self.filled(1).prod(axis, dtype=dtype, out=out, **kwargs)
  4327. if isinstance(out, MaskedArray):
  4328. outmask = getmask(out)
  4329. if outmask is nomask:
  4330. outmask = out._mask = make_mask_none(out.shape)
  4331. outmask.flat = newmask
  4332. return out
  4333. product = prod
  4334. def cumprod(self, axis=None, dtype=None, out=None):
  4335. """
  4336. Return the cumulative product of the array elements over the given axis.
  4337. Masked values are set to 1 internally during the computation.
  4338. However, their position is saved, and the result will be masked at
  4339. the same locations.
  4340. Refer to `numpy.cumprod` for full documentation.
  4341. Notes
  4342. -----
  4343. The mask is lost if `out` is not a valid MaskedArray !
  4344. Arithmetic is modular when using integer types, and no error is
  4345. raised on overflow.
  4346. See Also
  4347. --------
  4348. numpy.ndarray.cumprod : corresponding function for ndarrays
  4349. numpy.cumprod : equivalent function
  4350. """
  4351. result = self.filled(1).cumprod(axis=axis, dtype=dtype, out=out)
  4352. if out is not None:
  4353. if isinstance(out, MaskedArray):
  4354. out.__setmask__(self._mask)
  4355. return out
  4356. result = result.view(type(self))
  4357. result.__setmask__(self._mask)
  4358. return result
  4359. def mean(self, axis=None, dtype=None, out=None, keepdims=np._NoValue):
  4360. """
  4361. Returns the average of the array elements along given axis.
  4362. Masked entries are ignored, and result elements which are not
  4363. finite will be masked.
  4364. Refer to `numpy.mean` for full documentation.
  4365. See Also
  4366. --------
  4367. numpy.ndarray.mean : corresponding function for ndarrays
  4368. numpy.mean : Equivalent function
  4369. numpy.ma.average: Weighted average.
  4370. Examples
  4371. --------
  4372. >>> a = np.ma.array([1,2,3], mask=[False, False, True])
  4373. >>> a
  4374. masked_array(data=[1, 2, --],
  4375. mask=[False, False, True],
  4376. fill_value=999999)
  4377. >>> a.mean()
  4378. 1.5
  4379. """
  4380. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  4381. if self._mask is nomask:
  4382. result = super(MaskedArray, self).mean(axis=axis,
  4383. dtype=dtype, **kwargs)[()]
  4384. else:
  4385. dsum = self.sum(axis=axis, dtype=dtype, **kwargs)
  4386. cnt = self.count(axis=axis, **kwargs)
  4387. if cnt.shape == () and (cnt == 0):
  4388. result = masked
  4389. else:
  4390. result = dsum * 1. / cnt
  4391. if out is not None:
  4392. out.flat = result
  4393. if isinstance(out, MaskedArray):
  4394. outmask = getmask(out)
  4395. if outmask is nomask:
  4396. outmask = out._mask = make_mask_none(out.shape)
  4397. outmask.flat = getmask(result)
  4398. return out
  4399. return result
  4400. def anom(self, axis=None, dtype=None):
  4401. """
  4402. Compute the anomalies (deviations from the arithmetic mean)
  4403. along the given axis.
  4404. Returns an array of anomalies, with the same shape as the input and
  4405. where the arithmetic mean is computed along the given axis.
  4406. Parameters
  4407. ----------
  4408. axis : int, optional
  4409. Axis over which the anomalies are taken.
  4410. The default is to use the mean of the flattened array as reference.
  4411. dtype : dtype, optional
  4412. Type to use in computing the variance. For arrays of integer type
  4413. the default is float32; for arrays of float types it is the same as
  4414. the array type.
  4415. See Also
  4416. --------
  4417. mean : Compute the mean of the array.
  4418. Examples
  4419. --------
  4420. >>> a = np.ma.array([1,2,3])
  4421. >>> a.anom()
  4422. masked_array(data=[-1., 0., 1.],
  4423. mask=False,
  4424. fill_value=1e+20)
  4425. """
  4426. m = self.mean(axis, dtype)
  4427. if m is masked:
  4428. return m
  4429. if not axis:
  4430. return self - m
  4431. else:
  4432. return self - expand_dims(m, axis)
  4433. def var(self, axis=None, dtype=None, out=None, ddof=0,
  4434. keepdims=np._NoValue):
  4435. """
  4436. Returns the variance of the array elements along given axis.
  4437. Masked entries are ignored, and result elements which are not
  4438. finite will be masked.
  4439. Refer to `numpy.var` for full documentation.
  4440. See Also
  4441. --------
  4442. numpy.ndarray.var : corresponding function for ndarrays
  4443. numpy.var : Equivalent function
  4444. """
  4445. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  4446. # Easy case: nomask, business as usual
  4447. if self._mask is nomask:
  4448. ret = super(MaskedArray, self).var(axis=axis, dtype=dtype, out=out,
  4449. ddof=ddof, **kwargs)[()]
  4450. if out is not None:
  4451. if isinstance(out, MaskedArray):
  4452. out.__setmask__(nomask)
  4453. return out
  4454. return ret
  4455. # Some data are masked, yay!
  4456. cnt = self.count(axis=axis, **kwargs) - ddof
  4457. danom = self - self.mean(axis, dtype, keepdims=True)
  4458. if iscomplexobj(self):
  4459. danom = umath.absolute(danom) ** 2
  4460. else:
  4461. danom *= danom
  4462. dvar = divide(danom.sum(axis, **kwargs), cnt).view(type(self))
  4463. # Apply the mask if it's not a scalar
  4464. if dvar.ndim:
  4465. dvar._mask = mask_or(self._mask.all(axis, **kwargs), (cnt <= 0))
  4466. dvar._update_from(self)
  4467. elif getmask(dvar):
  4468. # Make sure that masked is returned when the scalar is masked.
  4469. dvar = masked
  4470. if out is not None:
  4471. if isinstance(out, MaskedArray):
  4472. out.flat = 0
  4473. out.__setmask__(True)
  4474. elif out.dtype.kind in 'biu':
  4475. errmsg = "Masked data information would be lost in one or "\
  4476. "more location."
  4477. raise MaskError(errmsg)
  4478. else:
  4479. out.flat = np.nan
  4480. return out
  4481. # In case with have an explicit output
  4482. if out is not None:
  4483. # Set the data
  4484. out.flat = dvar
  4485. # Set the mask if needed
  4486. if isinstance(out, MaskedArray):
  4487. out.__setmask__(dvar.mask)
  4488. return out
  4489. return dvar
  4490. var.__doc__ = np.var.__doc__
  4491. def std(self, axis=None, dtype=None, out=None, ddof=0,
  4492. keepdims=np._NoValue):
  4493. """
  4494. Returns the standard deviation of the array elements along given axis.
  4495. Masked entries are ignored.
  4496. Refer to `numpy.std` for full documentation.
  4497. See Also
  4498. --------
  4499. numpy.ndarray.std : corresponding function for ndarrays
  4500. numpy.std : Equivalent function
  4501. """
  4502. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  4503. dvar = self.var(axis, dtype, out, ddof, **kwargs)
  4504. if dvar is not masked:
  4505. if out is not None:
  4506. np.power(out, 0.5, out=out, casting='unsafe')
  4507. return out
  4508. dvar = sqrt(dvar)
  4509. return dvar
  4510. def round(self, decimals=0, out=None):
  4511. """
  4512. Return each element rounded to the given number of decimals.
  4513. Refer to `numpy.around` for full documentation.
  4514. See Also
  4515. --------
  4516. numpy.ndarray.round : corresponding function for ndarrays
  4517. numpy.around : equivalent function
  4518. """
  4519. result = self._data.round(decimals=decimals, out=out).view(type(self))
  4520. if result.ndim > 0:
  4521. result._mask = self._mask
  4522. result._update_from(self)
  4523. elif self._mask:
  4524. # Return masked when the scalar is masked
  4525. result = masked
  4526. # No explicit output: we're done
  4527. if out is None:
  4528. return result
  4529. if isinstance(out, MaskedArray):
  4530. out.__setmask__(self._mask)
  4531. return out
  4532. def argsort(self, axis=np._NoValue, kind=None, order=None,
  4533. endwith=True, fill_value=None):
  4534. """
  4535. Return an ndarray of indices that sort the array along the
  4536. specified axis. Masked values are filled beforehand to
  4537. `fill_value`.
  4538. Parameters
  4539. ----------
  4540. axis : int, optional
  4541. Axis along which to sort. If None, the default, the flattened array
  4542. is used.
  4543. .. versionchanged:: 1.13.0
  4544. Previously, the default was documented to be -1, but that was
  4545. in error. At some future date, the default will change to -1, as
  4546. originally intended.
  4547. Until then, the axis should be given explicitly when
  4548. ``arr.ndim > 1``, to avoid a FutureWarning.
  4549. kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
  4550. The sorting algorithm used.
  4551. order : list, optional
  4552. When `a` is an array with fields defined, this argument specifies
  4553. which fields to compare first, second, etc. Not all fields need be
  4554. specified.
  4555. endwith : {True, False}, optional
  4556. Whether missing values (if any) should be treated as the largest values
  4557. (True) or the smallest values (False)
  4558. When the array contains unmasked values at the same extremes of the
  4559. datatype, the ordering of these values and the masked values is
  4560. undefined.
  4561. fill_value : {var}, optional
  4562. Value used internally for the masked values.
  4563. If ``fill_value`` is not None, it supersedes ``endwith``.
  4564. Returns
  4565. -------
  4566. index_array : ndarray, int
  4567. Array of indices that sort `a` along the specified axis.
  4568. In other words, ``a[index_array]`` yields a sorted `a`.
  4569. See Also
  4570. --------
  4571. ma.MaskedArray.sort : Describes sorting algorithms used.
  4572. lexsort : Indirect stable sort with multiple keys.
  4573. numpy.ndarray.sort : Inplace sort.
  4574. Notes
  4575. -----
  4576. See `sort` for notes on the different sorting algorithms.
  4577. Examples
  4578. --------
  4579. >>> a = np.ma.array([3,2,1], mask=[False, False, True])
  4580. >>> a
  4581. masked_array(data=[3, 2, --],
  4582. mask=[False, False, True],
  4583. fill_value=999999)
  4584. >>> a.argsort()
  4585. array([1, 0, 2])
  4586. """
  4587. # 2017-04-11, Numpy 1.13.0, gh-8701: warn on axis default
  4588. if axis is np._NoValue:
  4589. axis = _deprecate_argsort_axis(self)
  4590. if fill_value is None:
  4591. if endwith:
  4592. # nan > inf
  4593. if np.issubdtype(self.dtype, np.floating):
  4594. fill_value = np.nan
  4595. else:
  4596. fill_value = minimum_fill_value(self)
  4597. else:
  4598. fill_value = maximum_fill_value(self)
  4599. filled = self.filled(fill_value)
  4600. return filled.argsort(axis=axis, kind=kind, order=order)
  4601. def argmin(self, axis=None, fill_value=None, out=None):
  4602. """
  4603. Return array of indices to the minimum values along the given axis.
  4604. Parameters
  4605. ----------
  4606. axis : {None, integer}
  4607. If None, the index is into the flattened array, otherwise along
  4608. the specified axis
  4609. fill_value : {var}, optional
  4610. Value used to fill in the masked values. If None, the output of
  4611. minimum_fill_value(self._data) is used instead.
  4612. out : {None, array}, optional
  4613. Array into which the result can be placed. Its type is preserved
  4614. and it must be of the right shape to hold the output.
  4615. Returns
  4616. -------
  4617. ndarray or scalar
  4618. If multi-dimension input, returns a new ndarray of indices to the
  4619. minimum values along the given axis. Otherwise, returns a scalar
  4620. of index to the minimum values along the given axis.
  4621. Examples
  4622. --------
  4623. >>> x = np.ma.array(np.arange(4), mask=[1,1,0,0])
  4624. >>> x.shape = (2,2)
  4625. >>> x
  4626. masked_array(
  4627. data=[[--, --],
  4628. [2, 3]],
  4629. mask=[[ True, True],
  4630. [False, False]],
  4631. fill_value=999999)
  4632. >>> x.argmin(axis=0, fill_value=-1)
  4633. array([0, 0])
  4634. >>> x.argmin(axis=0, fill_value=9)
  4635. array([1, 1])
  4636. """
  4637. if fill_value is None:
  4638. fill_value = minimum_fill_value(self)
  4639. d = self.filled(fill_value).view(ndarray)
  4640. return d.argmin(axis, out=out)
  4641. def argmax(self, axis=None, fill_value=None, out=None):
  4642. """
  4643. Returns array of indices of the maximum values along the given axis.
  4644. Masked values are treated as if they had the value fill_value.
  4645. Parameters
  4646. ----------
  4647. axis : {None, integer}
  4648. If None, the index is into the flattened array, otherwise along
  4649. the specified axis
  4650. fill_value : {var}, optional
  4651. Value used to fill in the masked values. If None, the output of
  4652. maximum_fill_value(self._data) is used instead.
  4653. out : {None, array}, optional
  4654. Array into which the result can be placed. Its type is preserved
  4655. and it must be of the right shape to hold the output.
  4656. Returns
  4657. -------
  4658. index_array : {integer_array}
  4659. Examples
  4660. --------
  4661. >>> a = np.arange(6).reshape(2,3)
  4662. >>> a.argmax()
  4663. 5
  4664. >>> a.argmax(0)
  4665. array([1, 1, 1])
  4666. >>> a.argmax(1)
  4667. array([2, 2])
  4668. """
  4669. if fill_value is None:
  4670. fill_value = maximum_fill_value(self._data)
  4671. d = self.filled(fill_value).view(ndarray)
  4672. return d.argmax(axis, out=out)
  4673. def sort(self, axis=-1, kind=None, order=None,
  4674. endwith=True, fill_value=None):
  4675. """
  4676. Sort the array, in-place
  4677. Parameters
  4678. ----------
  4679. a : array_like
  4680. Array to be sorted.
  4681. axis : int, optional
  4682. Axis along which to sort. If None, the array is flattened before
  4683. sorting. The default is -1, which sorts along the last axis.
  4684. kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
  4685. The sorting algorithm used.
  4686. order : list, optional
  4687. When `a` is a structured array, this argument specifies which fields
  4688. to compare first, second, and so on. This list does not need to
  4689. include all of the fields.
  4690. endwith : {True, False}, optional
  4691. Whether missing values (if any) should be treated as the largest values
  4692. (True) or the smallest values (False)
  4693. When the array contains unmasked values sorting at the same extremes of the
  4694. datatype, the ordering of these values and the masked values is
  4695. undefined.
  4696. fill_value : {var}, optional
  4697. Value used internally for the masked values.
  4698. If ``fill_value`` is not None, it supersedes ``endwith``.
  4699. Returns
  4700. -------
  4701. sorted_array : ndarray
  4702. Array of the same type and shape as `a`.
  4703. See Also
  4704. --------
  4705. numpy.ndarray.sort : Method to sort an array in-place.
  4706. argsort : Indirect sort.
  4707. lexsort : Indirect stable sort on multiple keys.
  4708. searchsorted : Find elements in a sorted array.
  4709. Notes
  4710. -----
  4711. See ``sort`` for notes on the different sorting algorithms.
  4712. Examples
  4713. --------
  4714. >>> a = np.ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
  4715. >>> # Default
  4716. >>> a.sort()
  4717. >>> a
  4718. masked_array(data=[1, 3, 5, --, --],
  4719. mask=[False, False, False, True, True],
  4720. fill_value=999999)
  4721. >>> a = np.ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
  4722. >>> # Put missing values in the front
  4723. >>> a.sort(endwith=False)
  4724. >>> a
  4725. masked_array(data=[--, --, 1, 3, 5],
  4726. mask=[ True, True, False, False, False],
  4727. fill_value=999999)
  4728. >>> a = np.ma.array([1, 2, 5, 4, 3],mask=[0, 1, 0, 1, 0])
  4729. >>> # fill_value takes over endwith
  4730. >>> a.sort(endwith=False, fill_value=3)
  4731. >>> a
  4732. masked_array(data=[1, --, --, 3, 5],
  4733. mask=[False, True, True, False, False],
  4734. fill_value=999999)
  4735. """
  4736. if self._mask is nomask:
  4737. ndarray.sort(self, axis=axis, kind=kind, order=order)
  4738. return
  4739. if self is masked:
  4740. return
  4741. sidx = self.argsort(axis=axis, kind=kind, order=order,
  4742. fill_value=fill_value, endwith=endwith)
  4743. self[...] = np.take_along_axis(self, sidx, axis=axis)
  4744. def min(self, axis=None, out=None, fill_value=None, keepdims=np._NoValue):
  4745. """
  4746. Return the minimum along a given axis.
  4747. Parameters
  4748. ----------
  4749. axis : {None, int}, optional
  4750. Axis along which to operate. By default, ``axis`` is None and the
  4751. flattened input is used.
  4752. out : array_like, optional
  4753. Alternative output array in which to place the result. Must be of
  4754. the same shape and buffer length as the expected output.
  4755. fill_value : {var}, optional
  4756. Value used to fill in the masked values.
  4757. If None, use the output of `minimum_fill_value`.
  4758. keepdims : bool, optional
  4759. If this is set to True, the axes which are reduced are left
  4760. in the result as dimensions with size one. With this option,
  4761. the result will broadcast correctly against the array.
  4762. Returns
  4763. -------
  4764. amin : array_like
  4765. New array holding the result.
  4766. If ``out`` was specified, ``out`` is returned.
  4767. See Also
  4768. --------
  4769. ma.minimum_fill_value
  4770. Returns the minimum filling value for a given datatype.
  4771. """
  4772. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  4773. _mask = self._mask
  4774. newmask = _check_mask_axis(_mask, axis, **kwargs)
  4775. if fill_value is None:
  4776. fill_value = minimum_fill_value(self)
  4777. # No explicit output
  4778. if out is None:
  4779. result = self.filled(fill_value).min(
  4780. axis=axis, out=out, **kwargs).view(type(self))
  4781. if result.ndim:
  4782. # Set the mask
  4783. result.__setmask__(newmask)
  4784. # Get rid of Infs
  4785. if newmask.ndim:
  4786. np.copyto(result, result.fill_value, where=newmask)
  4787. elif newmask:
  4788. result = masked
  4789. return result
  4790. # Explicit output
  4791. result = self.filled(fill_value).min(axis=axis, out=out, **kwargs)
  4792. if isinstance(out, MaskedArray):
  4793. outmask = getmask(out)
  4794. if outmask is nomask:
  4795. outmask = out._mask = make_mask_none(out.shape)
  4796. outmask.flat = newmask
  4797. else:
  4798. if out.dtype.kind in 'biu':
  4799. errmsg = "Masked data information would be lost in one or more"\
  4800. " location."
  4801. raise MaskError(errmsg)
  4802. np.copyto(out, np.nan, where=newmask)
  4803. return out
  4804. # unique to masked arrays
  4805. def mini(self, axis=None):
  4806. """
  4807. Return the array minimum along the specified axis.
  4808. .. deprecated:: 1.13.0
  4809. This function is identical to both:
  4810. * ``self.min(keepdims=True, axis=axis).squeeze(axis=axis)``
  4811. * ``np.ma.minimum.reduce(self, axis=axis)``
  4812. Typically though, ``self.min(axis=axis)`` is sufficient.
  4813. Parameters
  4814. ----------
  4815. axis : int, optional
  4816. The axis along which to find the minima. Default is None, in which case
  4817. the minimum value in the whole array is returned.
  4818. Returns
  4819. -------
  4820. min : scalar or MaskedArray
  4821. If `axis` is None, the result is a scalar. Otherwise, if `axis` is
  4822. given and the array is at least 2-D, the result is a masked array with
  4823. dimension one smaller than the array on which `mini` is called.
  4824. Examples
  4825. --------
  4826. >>> x = np.ma.array(np.arange(6), mask=[0 ,1, 0, 0, 0 ,1]).reshape(3, 2)
  4827. >>> x
  4828. masked_array(
  4829. data=[[0, --],
  4830. [2, 3],
  4831. [4, --]],
  4832. mask=[[False, True],
  4833. [False, False],
  4834. [False, True]],
  4835. fill_value=999999)
  4836. >>> x.mini()
  4837. masked_array(data=0,
  4838. mask=False,
  4839. fill_value=999999)
  4840. >>> x.mini(axis=0)
  4841. masked_array(data=[0, 3],
  4842. mask=[False, False],
  4843. fill_value=999999)
  4844. >>> x.mini(axis=1)
  4845. masked_array(data=[0, 2, 4],
  4846. mask=[False, False, False],
  4847. fill_value=999999)
  4848. There is a small difference between `mini` and `min`:
  4849. >>> x[:,1].mini(axis=0)
  4850. masked_array(data=3,
  4851. mask=False,
  4852. fill_value=999999)
  4853. >>> x[:,1].min(axis=0)
  4854. 3
  4855. """
  4856. # 2016-04-13, 1.13.0, gh-8764
  4857. warnings.warn(
  4858. "`mini` is deprecated; use the `min` method or "
  4859. "`np.ma.minimum.reduce instead.",
  4860. DeprecationWarning, stacklevel=2)
  4861. return minimum.reduce(self, axis)
  4862. def max(self, axis=None, out=None, fill_value=None, keepdims=np._NoValue):
  4863. """
  4864. Return the maximum along a given axis.
  4865. Parameters
  4866. ----------
  4867. axis : {None, int}, optional
  4868. Axis along which to operate. By default, ``axis`` is None and the
  4869. flattened input is used.
  4870. out : array_like, optional
  4871. Alternative output array in which to place the result. Must
  4872. be of the same shape and buffer length as the expected output.
  4873. fill_value : {var}, optional
  4874. Value used to fill in the masked values.
  4875. If None, use the output of maximum_fill_value().
  4876. keepdims : bool, optional
  4877. If this is set to True, the axes which are reduced are left
  4878. in the result as dimensions with size one. With this option,
  4879. the result will broadcast correctly against the array.
  4880. Returns
  4881. -------
  4882. amax : array_like
  4883. New array holding the result.
  4884. If ``out`` was specified, ``out`` is returned.
  4885. See Also
  4886. --------
  4887. ma.maximum_fill_value
  4888. Returns the maximum filling value for a given datatype.
  4889. """
  4890. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  4891. _mask = self._mask
  4892. newmask = _check_mask_axis(_mask, axis, **kwargs)
  4893. if fill_value is None:
  4894. fill_value = maximum_fill_value(self)
  4895. # No explicit output
  4896. if out is None:
  4897. result = self.filled(fill_value).max(
  4898. axis=axis, out=out, **kwargs).view(type(self))
  4899. if result.ndim:
  4900. # Set the mask
  4901. result.__setmask__(newmask)
  4902. # Get rid of Infs
  4903. if newmask.ndim:
  4904. np.copyto(result, result.fill_value, where=newmask)
  4905. elif newmask:
  4906. result = masked
  4907. return result
  4908. # Explicit output
  4909. result = self.filled(fill_value).max(axis=axis, out=out, **kwargs)
  4910. if isinstance(out, MaskedArray):
  4911. outmask = getmask(out)
  4912. if outmask is nomask:
  4913. outmask = out._mask = make_mask_none(out.shape)
  4914. outmask.flat = newmask
  4915. else:
  4916. if out.dtype.kind in 'biu':
  4917. errmsg = "Masked data information would be lost in one or more"\
  4918. " location."
  4919. raise MaskError(errmsg)
  4920. np.copyto(out, np.nan, where=newmask)
  4921. return out
  4922. def ptp(self, axis=None, out=None, fill_value=None, keepdims=False):
  4923. """
  4924. Return (maximum - minimum) along the given dimension
  4925. (i.e. peak-to-peak value).
  4926. .. warning::
  4927. `ptp` preserves the data type of the array. This means the
  4928. return value for an input of signed integers with n bits
  4929. (e.g. `np.int8`, `np.int16`, etc) is also a signed integer
  4930. with n bits. In that case, peak-to-peak values greater than
  4931. ``2**(n-1)-1`` will be returned as negative values. An example
  4932. with a work-around is shown below.
  4933. Parameters
  4934. ----------
  4935. axis : {None, int}, optional
  4936. Axis along which to find the peaks. If None (default) the
  4937. flattened array is used.
  4938. out : {None, array_like}, optional
  4939. Alternative output array in which to place the result. It must
  4940. have the same shape and buffer length as the expected output
  4941. but the type will be cast if necessary.
  4942. fill_value : {var}, optional
  4943. Value used to fill in the masked values.
  4944. keepdims : bool, optional
  4945. If this is set to True, the axes which are reduced are left
  4946. in the result as dimensions with size one. With this option,
  4947. the result will broadcast correctly against the array.
  4948. Returns
  4949. -------
  4950. ptp : ndarray.
  4951. A new array holding the result, unless ``out`` was
  4952. specified, in which case a reference to ``out`` is returned.
  4953. Examples
  4954. --------
  4955. >>> x = np.ma.MaskedArray([[4, 9, 2, 10],
  4956. ... [6, 9, 7, 12]])
  4957. >>> x.ptp(axis=1)
  4958. masked_array(data=[8, 6],
  4959. mask=False,
  4960. fill_value=999999)
  4961. >>> x.ptp(axis=0)
  4962. masked_array(data=[2, 0, 5, 2],
  4963. mask=False,
  4964. fill_value=999999)
  4965. >>> x.ptp()
  4966. 10
  4967. This example shows that a negative value can be returned when
  4968. the input is an array of signed integers.
  4969. >>> y = np.ma.MaskedArray([[1, 127],
  4970. ... [0, 127],
  4971. ... [-1, 127],
  4972. ... [-2, 127]], dtype=np.int8)
  4973. >>> y.ptp(axis=1)
  4974. masked_array(data=[ 126, 127, -128, -127],
  4975. mask=False,
  4976. fill_value=999999,
  4977. dtype=int8)
  4978. A work-around is to use the `view()` method to view the result as
  4979. unsigned integers with the same bit width:
  4980. >>> y.ptp(axis=1).view(np.uint8)
  4981. masked_array(data=[126, 127, 128, 129],
  4982. mask=False,
  4983. fill_value=999999,
  4984. dtype=uint8)
  4985. """
  4986. if out is None:
  4987. result = self.max(axis=axis, fill_value=fill_value,
  4988. keepdims=keepdims)
  4989. result -= self.min(axis=axis, fill_value=fill_value,
  4990. keepdims=keepdims)
  4991. return result
  4992. out.flat = self.max(axis=axis, out=out, fill_value=fill_value,
  4993. keepdims=keepdims)
  4994. min_value = self.min(axis=axis, fill_value=fill_value,
  4995. keepdims=keepdims)
  4996. np.subtract(out, min_value, out=out, casting='unsafe')
  4997. return out
  4998. def partition(self, *args, **kwargs):
  4999. warnings.warn("Warning: 'partition' will ignore the 'mask' "
  5000. f"of the {self.__class__.__name__}.",
  5001. stacklevel=2)
  5002. return super(MaskedArray, self).partition(*args, **kwargs)
  5003. def argpartition(self, *args, **kwargs):
  5004. warnings.warn("Warning: 'argpartition' will ignore the 'mask' "
  5005. f"of the {self.__class__.__name__}.",
  5006. stacklevel=2)
  5007. return super(MaskedArray, self).argpartition(*args, **kwargs)
  5008. def take(self, indices, axis=None, out=None, mode='raise'):
  5009. """
  5010. """
  5011. (_data, _mask) = (self._data, self._mask)
  5012. cls = type(self)
  5013. # Make sure the indices are not masked
  5014. maskindices = getmask(indices)
  5015. if maskindices is not nomask:
  5016. indices = indices.filled(0)
  5017. # Get the data, promoting scalars to 0d arrays with [...] so that
  5018. # .view works correctly
  5019. if out is None:
  5020. out = _data.take(indices, axis=axis, mode=mode)[...].view(cls)
  5021. else:
  5022. np.take(_data, indices, axis=axis, mode=mode, out=out)
  5023. # Get the mask
  5024. if isinstance(out, MaskedArray):
  5025. if _mask is nomask:
  5026. outmask = maskindices
  5027. else:
  5028. outmask = _mask.take(indices, axis=axis, mode=mode)
  5029. outmask |= maskindices
  5030. out.__setmask__(outmask)
  5031. # demote 0d arrays back to scalars, for consistency with ndarray.take
  5032. return out[()]
  5033. # Array methods
  5034. copy = _arraymethod('copy')
  5035. diagonal = _arraymethod('diagonal')
  5036. flatten = _arraymethod('flatten')
  5037. repeat = _arraymethod('repeat')
  5038. squeeze = _arraymethod('squeeze')
  5039. swapaxes = _arraymethod('swapaxes')
  5040. T = property(fget=lambda self: self.transpose())
  5041. transpose = _arraymethod('transpose')
  5042. def tolist(self, fill_value=None):
  5043. """
  5044. Return the data portion of the masked array as a hierarchical Python list.
  5045. Data items are converted to the nearest compatible Python type.
  5046. Masked values are converted to `fill_value`. If `fill_value` is None,
  5047. the corresponding entries in the output list will be ``None``.
  5048. Parameters
  5049. ----------
  5050. fill_value : scalar, optional
  5051. The value to use for invalid entries. Default is None.
  5052. Returns
  5053. -------
  5054. result : list
  5055. The Python list representation of the masked array.
  5056. Examples
  5057. --------
  5058. >>> x = np.ma.array([[1,2,3], [4,5,6], [7,8,9]], mask=[0] + [1,0]*4)
  5059. >>> x.tolist()
  5060. [[1, None, 3], [None, 5, None], [7, None, 9]]
  5061. >>> x.tolist(-999)
  5062. [[1, -999, 3], [-999, 5, -999], [7, -999, 9]]
  5063. """
  5064. _mask = self._mask
  5065. # No mask ? Just return .data.tolist ?
  5066. if _mask is nomask:
  5067. return self._data.tolist()
  5068. # Explicit fill_value: fill the array and get the list
  5069. if fill_value is not None:
  5070. return self.filled(fill_value).tolist()
  5071. # Structured array.
  5072. names = self.dtype.names
  5073. if names:
  5074. result = self._data.astype([(_, object) for _ in names])
  5075. for n in names:
  5076. result[n][_mask[n]] = None
  5077. return result.tolist()
  5078. # Standard arrays.
  5079. if _mask is nomask:
  5080. return [None]
  5081. # Set temps to save time when dealing w/ marrays.
  5082. inishape = self.shape
  5083. result = np.array(self._data.ravel(), dtype=object)
  5084. result[_mask.ravel()] = None
  5085. result.shape = inishape
  5086. return result.tolist()
  5087. def tostring(self, fill_value=None, order='C'):
  5088. r"""
  5089. A compatibility alias for `tobytes`, with exactly the same behavior.
  5090. Despite its name, it returns `bytes` not `str`\ s.
  5091. .. deprecated:: 1.19.0
  5092. """
  5093. # 2020-03-30, Numpy 1.19.0
  5094. warnings.warn(
  5095. "tostring() is deprecated. Use tobytes() instead.",
  5096. DeprecationWarning, stacklevel=2)
  5097. return self.tobytes(fill_value, order=order)
  5098. def tobytes(self, fill_value=None, order='C'):
  5099. """
  5100. Return the array data as a string containing the raw bytes in the array.
  5101. The array is filled with a fill value before the string conversion.
  5102. .. versionadded:: 1.9.0
  5103. Parameters
  5104. ----------
  5105. fill_value : scalar, optional
  5106. Value used to fill in the masked values. Default is None, in which
  5107. case `MaskedArray.fill_value` is used.
  5108. order : {'C','F','A'}, optional
  5109. Order of the data item in the copy. Default is 'C'.
  5110. - 'C' -- C order (row major).
  5111. - 'F' -- Fortran order (column major).
  5112. - 'A' -- Any, current order of array.
  5113. - None -- Same as 'A'.
  5114. See Also
  5115. --------
  5116. numpy.ndarray.tobytes
  5117. tolist, tofile
  5118. Notes
  5119. -----
  5120. As for `ndarray.tobytes`, information about the shape, dtype, etc.,
  5121. but also about `fill_value`, will be lost.
  5122. Examples
  5123. --------
  5124. >>> x = np.ma.array(np.array([[1, 2], [3, 4]]), mask=[[0, 1], [1, 0]])
  5125. >>> x.tobytes()
  5126. b'\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00?B\\x0f\\x00\\x00\\x00\\x00\\x00?B\\x0f\\x00\\x00\\x00\\x00\\x00\\x04\\x00\\x00\\x00\\x00\\x00\\x00\\x00'
  5127. """
  5128. return self.filled(fill_value).tobytes(order=order)
  5129. def tofile(self, fid, sep="", format="%s"):
  5130. """
  5131. Save a masked array to a file in binary format.
  5132. .. warning::
  5133. This function is not implemented yet.
  5134. Raises
  5135. ------
  5136. NotImplementedError
  5137. When `tofile` is called.
  5138. """
  5139. raise NotImplementedError("MaskedArray.tofile() not implemented yet.")
  5140. def toflex(self):
  5141. """
  5142. Transforms a masked array into a flexible-type array.
  5143. The flexible type array that is returned will have two fields:
  5144. * the ``_data`` field stores the ``_data`` part of the array.
  5145. * the ``_mask`` field stores the ``_mask`` part of the array.
  5146. Parameters
  5147. ----------
  5148. None
  5149. Returns
  5150. -------
  5151. record : ndarray
  5152. A new flexible-type `ndarray` with two fields: the first element
  5153. containing a value, the second element containing the corresponding
  5154. mask boolean. The returned record shape matches self.shape.
  5155. Notes
  5156. -----
  5157. A side-effect of transforming a masked array into a flexible `ndarray` is
  5158. that meta information (``fill_value``, ...) will be lost.
  5159. Examples
  5160. --------
  5161. >>> x = np.ma.array([[1,2,3],[4,5,6],[7,8,9]], mask=[0] + [1,0]*4)
  5162. >>> x
  5163. masked_array(
  5164. data=[[1, --, 3],
  5165. [--, 5, --],
  5166. [7, --, 9]],
  5167. mask=[[False, True, False],
  5168. [ True, False, True],
  5169. [False, True, False]],
  5170. fill_value=999999)
  5171. >>> x.toflex()
  5172. array([[(1, False), (2, True), (3, False)],
  5173. [(4, True), (5, False), (6, True)],
  5174. [(7, False), (8, True), (9, False)]],
  5175. dtype=[('_data', '<i8'), ('_mask', '?')])
  5176. """
  5177. # Get the basic dtype.
  5178. ddtype = self.dtype
  5179. # Make sure we have a mask
  5180. _mask = self._mask
  5181. if _mask is None:
  5182. _mask = make_mask_none(self.shape, ddtype)
  5183. # And get its dtype
  5184. mdtype = self._mask.dtype
  5185. record = np.ndarray(shape=self.shape,
  5186. dtype=[('_data', ddtype), ('_mask', mdtype)])
  5187. record['_data'] = self._data
  5188. record['_mask'] = self._mask
  5189. return record
  5190. torecords = toflex
  5191. # Pickling
  5192. def __getstate__(self):
  5193. """Return the internal state of the masked array, for pickling
  5194. purposes.
  5195. """
  5196. cf = 'CF'[self.flags.fnc]
  5197. data_state = super(MaskedArray, self).__reduce__()[2]
  5198. return data_state + (getmaskarray(self).tobytes(cf), self._fill_value)
  5199. def __setstate__(self, state):
  5200. """Restore the internal state of the masked array, for
  5201. pickling purposes. ``state`` is typically the output of the
  5202. ``__getstate__`` output, and is a 5-tuple:
  5203. - class name
  5204. - a tuple giving the shape of the data
  5205. - a typecode for the data
  5206. - a binary string for the data
  5207. - a binary string for the mask.
  5208. """
  5209. (_, shp, typ, isf, raw, msk, flv) = state
  5210. super(MaskedArray, self).__setstate__((shp, typ, isf, raw))
  5211. self._mask.__setstate__((shp, make_mask_descr(typ), isf, msk))
  5212. self.fill_value = flv
  5213. def __reduce__(self):
  5214. """Return a 3-tuple for pickling a MaskedArray.
  5215. """
  5216. return (_mareconstruct,
  5217. (self.__class__, self._baseclass, (0,), 'b',),
  5218. self.__getstate__())
  5219. def __deepcopy__(self, memo=None):
  5220. from copy import deepcopy
  5221. copied = MaskedArray.__new__(type(self), self, copy=True)
  5222. if memo is None:
  5223. memo = {}
  5224. memo[id(self)] = copied
  5225. for (k, v) in self.__dict__.items():
  5226. copied.__dict__[k] = deepcopy(v, memo)
  5227. return copied
  5228. def _mareconstruct(subtype, baseclass, baseshape, basetype,):
  5229. """Internal function that builds a new MaskedArray from the
  5230. information stored in a pickle.
  5231. """
  5232. _data = ndarray.__new__(baseclass, baseshape, basetype)
  5233. _mask = ndarray.__new__(ndarray, baseshape, make_mask_descr(basetype))
  5234. return subtype.__new__(subtype, _data, mask=_mask, dtype=basetype,)
  5235. class mvoid(MaskedArray):
  5236. """
  5237. Fake a 'void' object to use for masked array with structured dtypes.
  5238. """
  5239. def __new__(self, data, mask=nomask, dtype=None, fill_value=None,
  5240. hardmask=False, copy=False, subok=True):
  5241. _data = np.array(data, copy=copy, subok=subok, dtype=dtype)
  5242. _data = _data.view(self)
  5243. _data._hardmask = hardmask
  5244. if mask is not nomask:
  5245. if isinstance(mask, np.void):
  5246. _data._mask = mask
  5247. else:
  5248. try:
  5249. # Mask is already a 0D array
  5250. _data._mask = np.void(mask)
  5251. except TypeError:
  5252. # Transform the mask to a void
  5253. mdtype = make_mask_descr(dtype)
  5254. _data._mask = np.array(mask, dtype=mdtype)[()]
  5255. if fill_value is not None:
  5256. _data.fill_value = fill_value
  5257. return _data
  5258. @property
  5259. def _data(self):
  5260. # Make sure that the _data part is a np.void
  5261. return super(mvoid, self)._data[()]
  5262. def __getitem__(self, indx):
  5263. """
  5264. Get the index.
  5265. """
  5266. m = self._mask
  5267. if isinstance(m[indx], ndarray):
  5268. # Can happen when indx is a multi-dimensional field:
  5269. # A = ma.masked_array(data=[([0,1],)], mask=[([True,
  5270. # False],)], dtype=[("A", ">i2", (2,))])
  5271. # x = A[0]; y = x["A"]; then y.mask["A"].size==2
  5272. # and we can not say masked/unmasked.
  5273. # The result is no longer mvoid!
  5274. # See also issue #6724.
  5275. return masked_array(
  5276. data=self._data[indx], mask=m[indx],
  5277. fill_value=self._fill_value[indx],
  5278. hard_mask=self._hardmask)
  5279. if m is not nomask and m[indx]:
  5280. return masked
  5281. return self._data[indx]
  5282. def __setitem__(self, indx, value):
  5283. self._data[indx] = value
  5284. if self._hardmask:
  5285. self._mask[indx] |= getattr(value, "_mask", False)
  5286. else:
  5287. self._mask[indx] = getattr(value, "_mask", False)
  5288. def __str__(self):
  5289. m = self._mask
  5290. if m is nomask:
  5291. return str(self._data)
  5292. rdtype = _replace_dtype_fields(self._data.dtype, "O")
  5293. data_arr = super(mvoid, self)._data
  5294. res = data_arr.astype(rdtype)
  5295. _recursive_printoption(res, self._mask, masked_print_option)
  5296. return str(res)
  5297. __repr__ = __str__
  5298. def __iter__(self):
  5299. "Defines an iterator for mvoid"
  5300. (_data, _mask) = (self._data, self._mask)
  5301. if _mask is nomask:
  5302. yield from _data
  5303. else:
  5304. for (d, m) in zip(_data, _mask):
  5305. if m:
  5306. yield masked
  5307. else:
  5308. yield d
  5309. def __len__(self):
  5310. return self._data.__len__()
  5311. def filled(self, fill_value=None):
  5312. """
  5313. Return a copy with masked fields filled with a given value.
  5314. Parameters
  5315. ----------
  5316. fill_value : array_like, optional
  5317. The value to use for invalid entries. Can be scalar or
  5318. non-scalar. If latter is the case, the filled array should
  5319. be broadcastable over input array. Default is None, in
  5320. which case the `fill_value` attribute is used instead.
  5321. Returns
  5322. -------
  5323. filled_void
  5324. A `np.void` object
  5325. See Also
  5326. --------
  5327. MaskedArray.filled
  5328. """
  5329. return asarray(self).filled(fill_value)[()]
  5330. def tolist(self):
  5331. """
  5332. Transforms the mvoid object into a tuple.
  5333. Masked fields are replaced by None.
  5334. Returns
  5335. -------
  5336. returned_tuple
  5337. Tuple of fields
  5338. """
  5339. _mask = self._mask
  5340. if _mask is nomask:
  5341. return self._data.tolist()
  5342. result = []
  5343. for (d, m) in zip(self._data, self._mask):
  5344. if m:
  5345. result.append(None)
  5346. else:
  5347. # .item() makes sure we return a standard Python object
  5348. result.append(d.item())
  5349. return tuple(result)
  5350. ##############################################################################
  5351. # Shortcuts #
  5352. ##############################################################################
  5353. def isMaskedArray(x):
  5354. """
  5355. Test whether input is an instance of MaskedArray.
  5356. This function returns True if `x` is an instance of MaskedArray
  5357. and returns False otherwise. Any object is accepted as input.
  5358. Parameters
  5359. ----------
  5360. x : object
  5361. Object to test.
  5362. Returns
  5363. -------
  5364. result : bool
  5365. True if `x` is a MaskedArray.
  5366. See Also
  5367. --------
  5368. isMA : Alias to isMaskedArray.
  5369. isarray : Alias to isMaskedArray.
  5370. Examples
  5371. --------
  5372. >>> import numpy.ma as ma
  5373. >>> a = np.eye(3, 3)
  5374. >>> a
  5375. array([[ 1., 0., 0.],
  5376. [ 0., 1., 0.],
  5377. [ 0., 0., 1.]])
  5378. >>> m = ma.masked_values(a, 0)
  5379. >>> m
  5380. masked_array(
  5381. data=[[1.0, --, --],
  5382. [--, 1.0, --],
  5383. [--, --, 1.0]],
  5384. mask=[[False, True, True],
  5385. [ True, False, True],
  5386. [ True, True, False]],
  5387. fill_value=0.0)
  5388. >>> ma.isMaskedArray(a)
  5389. False
  5390. >>> ma.isMaskedArray(m)
  5391. True
  5392. >>> ma.isMaskedArray([0, 1, 2])
  5393. False
  5394. """
  5395. return isinstance(x, MaskedArray)
  5396. isarray = isMaskedArray
  5397. isMA = isMaskedArray # backward compatibility
  5398. class MaskedConstant(MaskedArray):
  5399. # the lone np.ma.masked instance
  5400. __singleton = None
  5401. @classmethod
  5402. def __has_singleton(cls):
  5403. # second case ensures `cls.__singleton` is not just a view on the
  5404. # superclass singleton
  5405. return cls.__singleton is not None and type(cls.__singleton) is cls
  5406. def __new__(cls):
  5407. if not cls.__has_singleton():
  5408. # We define the masked singleton as a float for higher precedence.
  5409. # Note that it can be tricky sometimes w/ type comparison
  5410. data = np.array(0.)
  5411. mask = np.array(True)
  5412. # prevent any modifications
  5413. data.flags.writeable = False
  5414. mask.flags.writeable = False
  5415. # don't fall back on MaskedArray.__new__(MaskedConstant), since
  5416. # that might confuse it - this way, the construction is entirely
  5417. # within our control
  5418. cls.__singleton = MaskedArray(data, mask=mask).view(cls)
  5419. return cls.__singleton
  5420. def __array_finalize__(self, obj):
  5421. if not self.__has_singleton():
  5422. # this handles the `.view` in __new__, which we want to copy across
  5423. # properties normally
  5424. return super(MaskedConstant, self).__array_finalize__(obj)
  5425. elif self is self.__singleton:
  5426. # not clear how this can happen, play it safe
  5427. pass
  5428. else:
  5429. # everywhere else, we want to downcast to MaskedArray, to prevent a
  5430. # duplicate maskedconstant.
  5431. self.__class__ = MaskedArray
  5432. MaskedArray.__array_finalize__(self, obj)
  5433. def __array_prepare__(self, obj, context=None):
  5434. return self.view(MaskedArray).__array_prepare__(obj, context)
  5435. def __array_wrap__(self, obj, context=None):
  5436. return self.view(MaskedArray).__array_wrap__(obj, context)
  5437. def __str__(self):
  5438. return str(masked_print_option._display)
  5439. def __repr__(self):
  5440. if self is MaskedConstant.__singleton:
  5441. return 'masked'
  5442. else:
  5443. # it's a subclass, or something is wrong, make it obvious
  5444. return object.__repr__(self)
  5445. def __format__(self, format_spec):
  5446. # Replace ndarray.__format__ with the default, which supports no format characters.
  5447. # Supporting format characters is unwise here, because we do not know what type
  5448. # the user was expecting - better to not guess.
  5449. try:
  5450. return object.__format__(self, format_spec)
  5451. except TypeError:
  5452. # 2020-03-23, NumPy 1.19.0
  5453. warnings.warn(
  5454. "Format strings passed to MaskedConstant are ignored, but in future may "
  5455. "error or produce different behavior",
  5456. FutureWarning, stacklevel=2
  5457. )
  5458. return object.__format__(self, "")
  5459. def __reduce__(self):
  5460. """Override of MaskedArray's __reduce__.
  5461. """
  5462. return (self.__class__, ())
  5463. # inplace operations have no effect. We have to override them to avoid
  5464. # trying to modify the readonly data and mask arrays
  5465. def __iop__(self, other):
  5466. return self
  5467. __iadd__ = \
  5468. __isub__ = \
  5469. __imul__ = \
  5470. __ifloordiv__ = \
  5471. __itruediv__ = \
  5472. __ipow__ = \
  5473. __iop__
  5474. del __iop__ # don't leave this around
  5475. def copy(self, *args, **kwargs):
  5476. """ Copy is a no-op on the maskedconstant, as it is a scalar """
  5477. # maskedconstant is a scalar, so copy doesn't need to copy. There's
  5478. # precedent for this with `np.bool_` scalars.
  5479. return self
  5480. def __copy__(self):
  5481. return self
  5482. def __deepcopy__(self, memo):
  5483. return self
  5484. def __setattr__(self, attr, value):
  5485. if not self.__has_singleton():
  5486. # allow the singleton to be initialized
  5487. return super(MaskedConstant, self).__setattr__(attr, value)
  5488. elif self is self.__singleton:
  5489. raise AttributeError(
  5490. f"attributes of {self!r} are not writeable")
  5491. else:
  5492. # duplicate instance - we can end up here from __array_finalize__,
  5493. # where we set the __class__ attribute
  5494. return super(MaskedConstant, self).__setattr__(attr, value)
  5495. masked = masked_singleton = MaskedConstant()
  5496. masked_array = MaskedArray
  5497. def array(data, dtype=None, copy=False, order=None,
  5498. mask=nomask, fill_value=None, keep_mask=True,
  5499. hard_mask=False, shrink=True, subok=True, ndmin=0):
  5500. """
  5501. Shortcut to MaskedArray.
  5502. The options are in a different order for convenience and backwards
  5503. compatibility.
  5504. """
  5505. return MaskedArray(data, mask=mask, dtype=dtype, copy=copy,
  5506. subok=subok, keep_mask=keep_mask,
  5507. hard_mask=hard_mask, fill_value=fill_value,
  5508. ndmin=ndmin, shrink=shrink, order=order)
  5509. array.__doc__ = masked_array.__doc__
  5510. def is_masked(x):
  5511. """
  5512. Determine whether input has masked values.
  5513. Accepts any object as input, but always returns False unless the
  5514. input is a MaskedArray containing masked values.
  5515. Parameters
  5516. ----------
  5517. x : array_like
  5518. Array to check for masked values.
  5519. Returns
  5520. -------
  5521. result : bool
  5522. True if `x` is a MaskedArray with masked values, False otherwise.
  5523. Examples
  5524. --------
  5525. >>> import numpy.ma as ma
  5526. >>> x = ma.masked_equal([0, 1, 0, 2, 3], 0)
  5527. >>> x
  5528. masked_array(data=[--, 1, --, 2, 3],
  5529. mask=[ True, False, True, False, False],
  5530. fill_value=0)
  5531. >>> ma.is_masked(x)
  5532. True
  5533. >>> x = ma.masked_equal([0, 1, 0, 2, 3], 42)
  5534. >>> x
  5535. masked_array(data=[0, 1, 0, 2, 3],
  5536. mask=False,
  5537. fill_value=42)
  5538. >>> ma.is_masked(x)
  5539. False
  5540. Always returns False if `x` isn't a MaskedArray.
  5541. >>> x = [False, True, False]
  5542. >>> ma.is_masked(x)
  5543. False
  5544. >>> x = 'a string'
  5545. >>> ma.is_masked(x)
  5546. False
  5547. """
  5548. m = getmask(x)
  5549. if m is nomask:
  5550. return False
  5551. elif m.any():
  5552. return True
  5553. return False
  5554. ##############################################################################
  5555. # Extrema functions #
  5556. ##############################################################################
  5557. class _extrema_operation(_MaskedUFunc):
  5558. """
  5559. Generic class for maximum/minimum functions.
  5560. .. note::
  5561. This is the base class for `_maximum_operation` and
  5562. `_minimum_operation`.
  5563. """
  5564. def __init__(self, ufunc, compare, fill_value):
  5565. super(_extrema_operation, self).__init__(ufunc)
  5566. self.compare = compare
  5567. self.fill_value_func = fill_value
  5568. def __call__(self, a, b=None):
  5569. "Executes the call behavior."
  5570. if b is None:
  5571. # 2016-04-13, 1.13.0
  5572. warnings.warn(
  5573. f"Single-argument form of np.ma.{self.__name__} is deprecated. Use "
  5574. f"np.ma.{self.__name__}.reduce instead.",
  5575. DeprecationWarning, stacklevel=2)
  5576. return self.reduce(a)
  5577. return where(self.compare(a, b), a, b)
  5578. def reduce(self, target, axis=np._NoValue):
  5579. "Reduce target along the given axis."
  5580. target = narray(target, copy=False, subok=True)
  5581. m = getmask(target)
  5582. if axis is np._NoValue and target.ndim > 1:
  5583. # 2017-05-06, Numpy 1.13.0: warn on axis default
  5584. warnings.warn(
  5585. f"In the future the default for ma.{self.__name__}.reduce will be axis=0, "
  5586. f"not the current None, to match np.{self.__name__}.reduce. "
  5587. "Explicitly pass 0 or None to silence this warning.",
  5588. MaskedArrayFutureWarning, stacklevel=2)
  5589. axis = None
  5590. if axis is not np._NoValue:
  5591. kwargs = dict(axis=axis)
  5592. else:
  5593. kwargs = dict()
  5594. if m is nomask:
  5595. t = self.f.reduce(target, **kwargs)
  5596. else:
  5597. target = target.filled(
  5598. self.fill_value_func(target)).view(type(target))
  5599. t = self.f.reduce(target, **kwargs)
  5600. m = umath.logical_and.reduce(m, **kwargs)
  5601. if hasattr(t, '_mask'):
  5602. t._mask = m
  5603. elif m:
  5604. t = masked
  5605. return t
  5606. def outer(self, a, b):
  5607. "Return the function applied to the outer product of a and b."
  5608. ma = getmask(a)
  5609. mb = getmask(b)
  5610. if ma is nomask and mb is nomask:
  5611. m = nomask
  5612. else:
  5613. ma = getmaskarray(a)
  5614. mb = getmaskarray(b)
  5615. m = logical_or.outer(ma, mb)
  5616. result = self.f.outer(filled(a), filled(b))
  5617. if not isinstance(result, MaskedArray):
  5618. result = result.view(MaskedArray)
  5619. result._mask = m
  5620. return result
  5621. def min(obj, axis=None, out=None, fill_value=None, keepdims=np._NoValue):
  5622. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  5623. try:
  5624. return obj.min(axis=axis, fill_value=fill_value, out=out, **kwargs)
  5625. except (AttributeError, TypeError):
  5626. # If obj doesn't have a min method, or if the method doesn't accept a
  5627. # fill_value argument
  5628. return asanyarray(obj).min(axis=axis, fill_value=fill_value,
  5629. out=out, **kwargs)
  5630. min.__doc__ = MaskedArray.min.__doc__
  5631. def max(obj, axis=None, out=None, fill_value=None, keepdims=np._NoValue):
  5632. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  5633. try:
  5634. return obj.max(axis=axis, fill_value=fill_value, out=out, **kwargs)
  5635. except (AttributeError, TypeError):
  5636. # If obj doesn't have a max method, or if the method doesn't accept a
  5637. # fill_value argument
  5638. return asanyarray(obj).max(axis=axis, fill_value=fill_value,
  5639. out=out, **kwargs)
  5640. max.__doc__ = MaskedArray.max.__doc__
  5641. def ptp(obj, axis=None, out=None, fill_value=None, keepdims=np._NoValue):
  5642. kwargs = {} if keepdims is np._NoValue else {'keepdims': keepdims}
  5643. try:
  5644. return obj.ptp(axis, out=out, fill_value=fill_value, **kwargs)
  5645. except (AttributeError, TypeError):
  5646. # If obj doesn't have a ptp method or if the method doesn't accept
  5647. # a fill_value argument
  5648. return asanyarray(obj).ptp(axis=axis, fill_value=fill_value,
  5649. out=out, **kwargs)
  5650. ptp.__doc__ = MaskedArray.ptp.__doc__
  5651. ##############################################################################
  5652. # Definition of functions from the corresponding methods #
  5653. ##############################################################################
  5654. class _frommethod:
  5655. """
  5656. Define functions from existing MaskedArray methods.
  5657. Parameters
  5658. ----------
  5659. methodname : str
  5660. Name of the method to transform.
  5661. """
  5662. def __init__(self, methodname, reversed=False):
  5663. self.__name__ = methodname
  5664. self.__doc__ = self.getdoc()
  5665. self.reversed = reversed
  5666. def getdoc(self):
  5667. "Return the doc of the function (from the doc of the method)."
  5668. meth = getattr(MaskedArray, self.__name__, None) or\
  5669. getattr(np, self.__name__, None)
  5670. signature = self.__name__ + get_object_signature(meth)
  5671. if meth is not None:
  5672. doc = """ %s\n%s""" % (
  5673. signature, getattr(meth, '__doc__', None))
  5674. return doc
  5675. def __call__(self, a, *args, **params):
  5676. if self.reversed:
  5677. args = list(args)
  5678. a, args[0] = args[0], a
  5679. marr = asanyarray(a)
  5680. method_name = self.__name__
  5681. method = getattr(type(marr), method_name, None)
  5682. if method is None:
  5683. # use the corresponding np function
  5684. method = getattr(np, method_name)
  5685. return method(marr, *args, **params)
  5686. all = _frommethod('all')
  5687. anomalies = anom = _frommethod('anom')
  5688. any = _frommethod('any')
  5689. compress = _frommethod('compress', reversed=True)
  5690. cumprod = _frommethod('cumprod')
  5691. cumsum = _frommethod('cumsum')
  5692. copy = _frommethod('copy')
  5693. diagonal = _frommethod('diagonal')
  5694. harden_mask = _frommethod('harden_mask')
  5695. ids = _frommethod('ids')
  5696. maximum = _extrema_operation(umath.maximum, greater, maximum_fill_value)
  5697. mean = _frommethod('mean')
  5698. minimum = _extrema_operation(umath.minimum, less, minimum_fill_value)
  5699. nonzero = _frommethod('nonzero')
  5700. prod = _frommethod('prod')
  5701. product = _frommethod('prod')
  5702. ravel = _frommethod('ravel')
  5703. repeat = _frommethod('repeat')
  5704. shrink_mask = _frommethod('shrink_mask')
  5705. soften_mask = _frommethod('soften_mask')
  5706. std = _frommethod('std')
  5707. sum = _frommethod('sum')
  5708. swapaxes = _frommethod('swapaxes')
  5709. #take = _frommethod('take')
  5710. trace = _frommethod('trace')
  5711. var = _frommethod('var')
  5712. count = _frommethod('count')
  5713. def take(a, indices, axis=None, out=None, mode='raise'):
  5714. """
  5715. """
  5716. a = masked_array(a)
  5717. return a.take(indices, axis=axis, out=out, mode=mode)
  5718. def power(a, b, third=None):
  5719. """
  5720. Returns element-wise base array raised to power from second array.
  5721. This is the masked array version of `numpy.power`. For details see
  5722. `numpy.power`.
  5723. See Also
  5724. --------
  5725. numpy.power
  5726. Notes
  5727. -----
  5728. The *out* argument to `numpy.power` is not supported, `third` has to be
  5729. None.
  5730. """
  5731. if third is not None:
  5732. raise MaskError("3-argument power not supported.")
  5733. # Get the masks
  5734. ma = getmask(a)
  5735. mb = getmask(b)
  5736. m = mask_or(ma, mb)
  5737. # Get the rawdata
  5738. fa = getdata(a)
  5739. fb = getdata(b)
  5740. # Get the type of the result (so that we preserve subclasses)
  5741. if isinstance(a, MaskedArray):
  5742. basetype = type(a)
  5743. else:
  5744. basetype = MaskedArray
  5745. # Get the result and view it as a (subclass of) MaskedArray
  5746. with np.errstate(divide='ignore', invalid='ignore'):
  5747. result = np.where(m, fa, umath.power(fa, fb)).view(basetype)
  5748. result._update_from(a)
  5749. # Find where we're in trouble w/ NaNs and Infs
  5750. invalid = np.logical_not(np.isfinite(result.view(ndarray)))
  5751. # Add the initial mask
  5752. if m is not nomask:
  5753. if not result.ndim:
  5754. return masked
  5755. result._mask = np.logical_or(m, invalid)
  5756. # Fix the invalid parts
  5757. if invalid.any():
  5758. if not result.ndim:
  5759. return masked
  5760. elif result._mask is nomask:
  5761. result._mask = invalid
  5762. result._data[invalid] = result.fill_value
  5763. return result
  5764. argmin = _frommethod('argmin')
  5765. argmax = _frommethod('argmax')
  5766. def argsort(a, axis=np._NoValue, kind=None, order=None, endwith=True, fill_value=None):
  5767. "Function version of the eponymous method."
  5768. a = np.asanyarray(a)
  5769. # 2017-04-11, Numpy 1.13.0, gh-8701: warn on axis default
  5770. if axis is np._NoValue:
  5771. axis = _deprecate_argsort_axis(a)
  5772. if isinstance(a, MaskedArray):
  5773. return a.argsort(axis=axis, kind=kind, order=order,
  5774. endwith=endwith, fill_value=fill_value)
  5775. else:
  5776. return a.argsort(axis=axis, kind=kind, order=order)
  5777. argsort.__doc__ = MaskedArray.argsort.__doc__
  5778. def sort(a, axis=-1, kind=None, order=None, endwith=True, fill_value=None):
  5779. """
  5780. Return a sorted copy of the masked array.
  5781. Equivalent to creating a copy of the array
  5782. and applying the MaskedArray ``sort()`` method.
  5783. Refer to ``MaskedArray.sort`` for the full documentation
  5784. See Also
  5785. --------
  5786. MaskedArray.sort : equivalent method
  5787. """
  5788. a = np.array(a, copy=True, subok=True)
  5789. if axis is None:
  5790. a = a.flatten()
  5791. axis = 0
  5792. if isinstance(a, MaskedArray):
  5793. a.sort(axis=axis, kind=kind, order=order,
  5794. endwith=endwith, fill_value=fill_value)
  5795. else:
  5796. a.sort(axis=axis, kind=kind, order=order)
  5797. return a
  5798. def compressed(x):
  5799. """
  5800. Return all the non-masked data as a 1-D array.
  5801. This function is equivalent to calling the "compressed" method of a
  5802. `ma.MaskedArray`, see `ma.MaskedArray.compressed` for details.
  5803. See Also
  5804. --------
  5805. ma.MaskedArray.compressed
  5806. Equivalent method.
  5807. """
  5808. return asanyarray(x).compressed()
  5809. def concatenate(arrays, axis=0):
  5810. """
  5811. Concatenate a sequence of arrays along the given axis.
  5812. Parameters
  5813. ----------
  5814. arrays : sequence of array_like
  5815. The arrays must have the same shape, except in the dimension
  5816. corresponding to `axis` (the first, by default).
  5817. axis : int, optional
  5818. The axis along which the arrays will be joined. Default is 0.
  5819. Returns
  5820. -------
  5821. result : MaskedArray
  5822. The concatenated array with any masked entries preserved.
  5823. See Also
  5824. --------
  5825. numpy.concatenate : Equivalent function in the top-level NumPy module.
  5826. Examples
  5827. --------
  5828. >>> import numpy.ma as ma
  5829. >>> a = ma.arange(3)
  5830. >>> a[1] = ma.masked
  5831. >>> b = ma.arange(2, 5)
  5832. >>> a
  5833. masked_array(data=[0, --, 2],
  5834. mask=[False, True, False],
  5835. fill_value=999999)
  5836. >>> b
  5837. masked_array(data=[2, 3, 4],
  5838. mask=False,
  5839. fill_value=999999)
  5840. >>> ma.concatenate([a, b])
  5841. masked_array(data=[0, --, 2, 2, 3, 4],
  5842. mask=[False, True, False, False, False, False],
  5843. fill_value=999999)
  5844. """
  5845. d = np.concatenate([getdata(a) for a in arrays], axis)
  5846. rcls = get_masked_subclass(*arrays)
  5847. data = d.view(rcls)
  5848. # Check whether one of the arrays has a non-empty mask.
  5849. for x in arrays:
  5850. if getmask(x) is not nomask:
  5851. break
  5852. else:
  5853. return data
  5854. # OK, so we have to concatenate the masks
  5855. dm = np.concatenate([getmaskarray(a) for a in arrays], axis)
  5856. dm = dm.reshape(d.shape)
  5857. # If we decide to keep a '_shrinkmask' option, we want to check that
  5858. # all of them are True, and then check for dm.any()
  5859. data._mask = _shrink_mask(dm)
  5860. return data
  5861. def diag(v, k=0):
  5862. """
  5863. Extract a diagonal or construct a diagonal array.
  5864. This function is the equivalent of `numpy.diag` that takes masked
  5865. values into account, see `numpy.diag` for details.
  5866. See Also
  5867. --------
  5868. numpy.diag : Equivalent function for ndarrays.
  5869. """
  5870. output = np.diag(v, k).view(MaskedArray)
  5871. if getmask(v) is not nomask:
  5872. output._mask = np.diag(v._mask, k)
  5873. return output
  5874. def left_shift(a, n):
  5875. """
  5876. Shift the bits of an integer to the left.
  5877. This is the masked array version of `numpy.left_shift`, for details
  5878. see that function.
  5879. See Also
  5880. --------
  5881. numpy.left_shift
  5882. """
  5883. m = getmask(a)
  5884. if m is nomask:
  5885. d = umath.left_shift(filled(a), n)
  5886. return masked_array(d)
  5887. else:
  5888. d = umath.left_shift(filled(a, 0), n)
  5889. return masked_array(d, mask=m)
  5890. def right_shift(a, n):
  5891. """
  5892. Shift the bits of an integer to the right.
  5893. This is the masked array version of `numpy.right_shift`, for details
  5894. see that function.
  5895. See Also
  5896. --------
  5897. numpy.right_shift
  5898. """
  5899. m = getmask(a)
  5900. if m is nomask:
  5901. d = umath.right_shift(filled(a), n)
  5902. return masked_array(d)
  5903. else:
  5904. d = umath.right_shift(filled(a, 0), n)
  5905. return masked_array(d, mask=m)
  5906. def put(a, indices, values, mode='raise'):
  5907. """
  5908. Set storage-indexed locations to corresponding values.
  5909. This function is equivalent to `MaskedArray.put`, see that method
  5910. for details.
  5911. See Also
  5912. --------
  5913. MaskedArray.put
  5914. """
  5915. # We can't use 'frommethod', the order of arguments is different
  5916. try:
  5917. return a.put(indices, values, mode=mode)
  5918. except AttributeError:
  5919. return narray(a, copy=False).put(indices, values, mode=mode)
  5920. def putmask(a, mask, values): # , mode='raise'):
  5921. """
  5922. Changes elements of an array based on conditional and input values.
  5923. This is the masked array version of `numpy.putmask`, for details see
  5924. `numpy.putmask`.
  5925. See Also
  5926. --------
  5927. numpy.putmask
  5928. Notes
  5929. -----
  5930. Using a masked array as `values` will **not** transform a `ndarray` into
  5931. a `MaskedArray`.
  5932. """
  5933. # We can't use 'frommethod', the order of arguments is different
  5934. if not isinstance(a, MaskedArray):
  5935. a = a.view(MaskedArray)
  5936. (valdata, valmask) = (getdata(values), getmask(values))
  5937. if getmask(a) is nomask:
  5938. if valmask is not nomask:
  5939. a._sharedmask = True
  5940. a._mask = make_mask_none(a.shape, a.dtype)
  5941. np.copyto(a._mask, valmask, where=mask)
  5942. elif a._hardmask:
  5943. if valmask is not nomask:
  5944. m = a._mask.copy()
  5945. np.copyto(m, valmask, where=mask)
  5946. a.mask |= m
  5947. else:
  5948. if valmask is nomask:
  5949. valmask = getmaskarray(values)
  5950. np.copyto(a._mask, valmask, where=mask)
  5951. np.copyto(a._data, valdata, where=mask)
  5952. return
  5953. def transpose(a, axes=None):
  5954. """
  5955. Permute the dimensions of an array.
  5956. This function is exactly equivalent to `numpy.transpose`.
  5957. See Also
  5958. --------
  5959. numpy.transpose : Equivalent function in top-level NumPy module.
  5960. Examples
  5961. --------
  5962. >>> import numpy.ma as ma
  5963. >>> x = ma.arange(4).reshape((2,2))
  5964. >>> x[1, 1] = ma.masked
  5965. >>> x
  5966. masked_array(
  5967. data=[[0, 1],
  5968. [2, --]],
  5969. mask=[[False, False],
  5970. [False, True]],
  5971. fill_value=999999)
  5972. >>> ma.transpose(x)
  5973. masked_array(
  5974. data=[[0, 2],
  5975. [1, --]],
  5976. mask=[[False, False],
  5977. [False, True]],
  5978. fill_value=999999)
  5979. """
  5980. # We can't use 'frommethod', as 'transpose' doesn't take keywords
  5981. try:
  5982. return a.transpose(axes)
  5983. except AttributeError:
  5984. return narray(a, copy=False).transpose(axes).view(MaskedArray)
  5985. def reshape(a, new_shape, order='C'):
  5986. """
  5987. Returns an array containing the same data with a new shape.
  5988. Refer to `MaskedArray.reshape` for full documentation.
  5989. See Also
  5990. --------
  5991. MaskedArray.reshape : equivalent function
  5992. """
  5993. # We can't use 'frommethod', it whine about some parameters. Dmmit.
  5994. try:
  5995. return a.reshape(new_shape, order=order)
  5996. except AttributeError:
  5997. _tmp = narray(a, copy=False).reshape(new_shape, order=order)
  5998. return _tmp.view(MaskedArray)
  5999. def resize(x, new_shape):
  6000. """
  6001. Return a new masked array with the specified size and shape.
  6002. This is the masked equivalent of the `numpy.resize` function. The new
  6003. array is filled with repeated copies of `x` (in the order that the
  6004. data are stored in memory). If `x` is masked, the new array will be
  6005. masked, and the new mask will be a repetition of the old one.
  6006. See Also
  6007. --------
  6008. numpy.resize : Equivalent function in the top level NumPy module.
  6009. Examples
  6010. --------
  6011. >>> import numpy.ma as ma
  6012. >>> a = ma.array([[1, 2] ,[3, 4]])
  6013. >>> a[0, 1] = ma.masked
  6014. >>> a
  6015. masked_array(
  6016. data=[[1, --],
  6017. [3, 4]],
  6018. mask=[[False, True],
  6019. [False, False]],
  6020. fill_value=999999)
  6021. >>> np.resize(a, (3, 3))
  6022. masked_array(
  6023. data=[[1, 2, 3],
  6024. [4, 1, 2],
  6025. [3, 4, 1]],
  6026. mask=False,
  6027. fill_value=999999)
  6028. >>> ma.resize(a, (3, 3))
  6029. masked_array(
  6030. data=[[1, --, 3],
  6031. [4, 1, --],
  6032. [3, 4, 1]],
  6033. mask=[[False, True, False],
  6034. [False, False, True],
  6035. [False, False, False]],
  6036. fill_value=999999)
  6037. A MaskedArray is always returned, regardless of the input type.
  6038. >>> a = np.array([[1, 2] ,[3, 4]])
  6039. >>> ma.resize(a, (3, 3))
  6040. masked_array(
  6041. data=[[1, 2, 3],
  6042. [4, 1, 2],
  6043. [3, 4, 1]],
  6044. mask=False,
  6045. fill_value=999999)
  6046. """
  6047. # We can't use _frommethods here, as N.resize is notoriously whiny.
  6048. m = getmask(x)
  6049. if m is not nomask:
  6050. m = np.resize(m, new_shape)
  6051. result = np.resize(x, new_shape).view(get_masked_subclass(x))
  6052. if result.ndim:
  6053. result._mask = m
  6054. return result
  6055. def ndim(obj):
  6056. """
  6057. maskedarray version of the numpy function.
  6058. """
  6059. return np.ndim(getdata(obj))
  6060. ndim.__doc__ = np.ndim.__doc__
  6061. def shape(obj):
  6062. "maskedarray version of the numpy function."
  6063. return np.shape(getdata(obj))
  6064. shape.__doc__ = np.shape.__doc__
  6065. def size(obj, axis=None):
  6066. "maskedarray version of the numpy function."
  6067. return np.size(getdata(obj), axis)
  6068. size.__doc__ = np.size.__doc__
  6069. ##############################################################################
  6070. # Extra functions #
  6071. ##############################################################################
  6072. def where(condition, x=_NoValue, y=_NoValue):
  6073. """
  6074. Return a masked array with elements from `x` or `y`, depending on condition.
  6075. .. note::
  6076. When only `condition` is provided, this function is identical to
  6077. `nonzero`. The rest of this documentation covers only the case where
  6078. all three arguments are provided.
  6079. Parameters
  6080. ----------
  6081. condition : array_like, bool
  6082. Where True, yield `x`, otherwise yield `y`.
  6083. x, y : array_like, optional
  6084. Values from which to choose. `x`, `y` and `condition` need to be
  6085. broadcastable to some shape.
  6086. Returns
  6087. -------
  6088. out : MaskedArray
  6089. An masked array with `masked` elements where the condition is masked,
  6090. elements from `x` where `condition` is True, and elements from `y`
  6091. elsewhere.
  6092. See Also
  6093. --------
  6094. numpy.where : Equivalent function in the top-level NumPy module.
  6095. nonzero : The function that is called when x and y are omitted
  6096. Examples
  6097. --------
  6098. >>> x = np.ma.array(np.arange(9.).reshape(3, 3), mask=[[0, 1, 0],
  6099. ... [1, 0, 1],
  6100. ... [0, 1, 0]])
  6101. >>> x
  6102. masked_array(
  6103. data=[[0.0, --, 2.0],
  6104. [--, 4.0, --],
  6105. [6.0, --, 8.0]],
  6106. mask=[[False, True, False],
  6107. [ True, False, True],
  6108. [False, True, False]],
  6109. fill_value=1e+20)
  6110. >>> np.ma.where(x > 5, x, -3.1416)
  6111. masked_array(
  6112. data=[[-3.1416, --, -3.1416],
  6113. [--, -3.1416, --],
  6114. [6.0, --, 8.0]],
  6115. mask=[[False, True, False],
  6116. [ True, False, True],
  6117. [False, True, False]],
  6118. fill_value=1e+20)
  6119. """
  6120. # handle the single-argument case
  6121. missing = (x is _NoValue, y is _NoValue).count(True)
  6122. if missing == 1:
  6123. raise ValueError("Must provide both 'x' and 'y' or neither.")
  6124. if missing == 2:
  6125. return nonzero(condition)
  6126. # we only care if the condition is true - false or masked pick y
  6127. cf = filled(condition, False)
  6128. xd = getdata(x)
  6129. yd = getdata(y)
  6130. # we need the full arrays here for correct final dimensions
  6131. cm = getmaskarray(condition)
  6132. xm = getmaskarray(x)
  6133. ym = getmaskarray(y)
  6134. # deal with the fact that masked.dtype == float64, but we don't actually
  6135. # want to treat it as that.
  6136. if x is masked and y is not masked:
  6137. xd = np.zeros((), dtype=yd.dtype)
  6138. xm = np.ones((), dtype=ym.dtype)
  6139. elif y is masked and x is not masked:
  6140. yd = np.zeros((), dtype=xd.dtype)
  6141. ym = np.ones((), dtype=xm.dtype)
  6142. data = np.where(cf, xd, yd)
  6143. mask = np.where(cf, xm, ym)
  6144. mask = np.where(cm, np.ones((), dtype=mask.dtype), mask)
  6145. # collapse the mask, for backwards compatibility
  6146. mask = _shrink_mask(mask)
  6147. return masked_array(data, mask=mask)
  6148. def choose(indices, choices, out=None, mode='raise'):
  6149. """
  6150. Use an index array to construct a new array from a set of choices.
  6151. Given an array of integers and a set of n choice arrays, this method
  6152. will create a new array that merges each of the choice arrays. Where a
  6153. value in `a` is i, the new array will have the value that choices[i]
  6154. contains in the same place.
  6155. Parameters
  6156. ----------
  6157. a : ndarray of ints
  6158. This array must contain integers in ``[0, n-1]``, where n is the
  6159. number of choices.
  6160. choices : sequence of arrays
  6161. Choice arrays. The index array and all of the choices should be
  6162. broadcastable to the same shape.
  6163. out : array, optional
  6164. If provided, the result will be inserted into this array. It should
  6165. be of the appropriate shape and `dtype`.
  6166. mode : {'raise', 'wrap', 'clip'}, optional
  6167. Specifies how out-of-bounds indices will behave.
  6168. * 'raise' : raise an error
  6169. * 'wrap' : wrap around
  6170. * 'clip' : clip to the range
  6171. Returns
  6172. -------
  6173. merged_array : array
  6174. See Also
  6175. --------
  6176. choose : equivalent function
  6177. Examples
  6178. --------
  6179. >>> choice = np.array([[1,1,1], [2,2,2], [3,3,3]])
  6180. >>> a = np.array([2, 1, 0])
  6181. >>> np.ma.choose(a, choice)
  6182. masked_array(data=[3, 2, 1],
  6183. mask=False,
  6184. fill_value=999999)
  6185. """
  6186. def fmask(x):
  6187. "Returns the filled array, or True if masked."
  6188. if x is masked:
  6189. return True
  6190. return filled(x)
  6191. def nmask(x):
  6192. "Returns the mask, True if ``masked``, False if ``nomask``."
  6193. if x is masked:
  6194. return True
  6195. return getmask(x)
  6196. # Get the indices.
  6197. c = filled(indices, 0)
  6198. # Get the masks.
  6199. masks = [nmask(x) for x in choices]
  6200. data = [fmask(x) for x in choices]
  6201. # Construct the mask
  6202. outputmask = np.choose(c, masks, mode=mode)
  6203. outputmask = make_mask(mask_or(outputmask, getmask(indices)),
  6204. copy=False, shrink=True)
  6205. # Get the choices.
  6206. d = np.choose(c, data, mode=mode, out=out).view(MaskedArray)
  6207. if out is not None:
  6208. if isinstance(out, MaskedArray):
  6209. out.__setmask__(outputmask)
  6210. return out
  6211. d.__setmask__(outputmask)
  6212. return d
  6213. def round_(a, decimals=0, out=None):
  6214. """
  6215. Return a copy of a, rounded to 'decimals' places.
  6216. When 'decimals' is negative, it specifies the number of positions
  6217. to the left of the decimal point. The real and imaginary parts of
  6218. complex numbers are rounded separately. Nothing is done if the
  6219. array is not of float type and 'decimals' is greater than or equal
  6220. to 0.
  6221. Parameters
  6222. ----------
  6223. decimals : int
  6224. Number of decimals to round to. May be negative.
  6225. out : array_like
  6226. Existing array to use for output.
  6227. If not given, returns a default copy of a.
  6228. Notes
  6229. -----
  6230. If out is given and does not have a mask attribute, the mask of a
  6231. is lost!
  6232. """
  6233. if out is None:
  6234. return np.round_(a, decimals, out)
  6235. else:
  6236. np.round_(getdata(a), decimals, out)
  6237. if hasattr(out, '_mask'):
  6238. out._mask = getmask(a)
  6239. return out
  6240. round = round_
  6241. # Needed by dot, so move here from extras.py. It will still be exported
  6242. # from extras.py for compatibility.
  6243. def mask_rowcols(a, axis=None):
  6244. """
  6245. Mask rows and/or columns of a 2D array that contain masked values.
  6246. Mask whole rows and/or columns of a 2D array that contain
  6247. masked values. The masking behavior is selected using the
  6248. `axis` parameter.
  6249. - If `axis` is None, rows *and* columns are masked.
  6250. - If `axis` is 0, only rows are masked.
  6251. - If `axis` is 1 or -1, only columns are masked.
  6252. Parameters
  6253. ----------
  6254. a : array_like, MaskedArray
  6255. The array to mask. If not a MaskedArray instance (or if no array
  6256. elements are masked). The result is a MaskedArray with `mask` set
  6257. to `nomask` (False). Must be a 2D array.
  6258. axis : int, optional
  6259. Axis along which to perform the operation. If None, applies to a
  6260. flattened version of the array.
  6261. Returns
  6262. -------
  6263. a : MaskedArray
  6264. A modified version of the input array, masked depending on the value
  6265. of the `axis` parameter.
  6266. Raises
  6267. ------
  6268. NotImplementedError
  6269. If input array `a` is not 2D.
  6270. See Also
  6271. --------
  6272. mask_rows : Mask rows of a 2D array that contain masked values.
  6273. mask_cols : Mask cols of a 2D array that contain masked values.
  6274. masked_where : Mask where a condition is met.
  6275. Notes
  6276. -----
  6277. The input array's mask is modified by this function.
  6278. Examples
  6279. --------
  6280. >>> import numpy.ma as ma
  6281. >>> a = np.zeros((3, 3), dtype=int)
  6282. >>> a[1, 1] = 1
  6283. >>> a
  6284. array([[0, 0, 0],
  6285. [0, 1, 0],
  6286. [0, 0, 0]])
  6287. >>> a = ma.masked_equal(a, 1)
  6288. >>> a
  6289. masked_array(
  6290. data=[[0, 0, 0],
  6291. [0, --, 0],
  6292. [0, 0, 0]],
  6293. mask=[[False, False, False],
  6294. [False, True, False],
  6295. [False, False, False]],
  6296. fill_value=1)
  6297. >>> ma.mask_rowcols(a)
  6298. masked_array(
  6299. data=[[0, --, 0],
  6300. [--, --, --],
  6301. [0, --, 0]],
  6302. mask=[[False, True, False],
  6303. [ True, True, True],
  6304. [False, True, False]],
  6305. fill_value=1)
  6306. """
  6307. a = array(a, subok=False)
  6308. if a.ndim != 2:
  6309. raise NotImplementedError("mask_rowcols works for 2D arrays only.")
  6310. m = getmask(a)
  6311. # Nothing is masked: return a
  6312. if m is nomask or not m.any():
  6313. return a
  6314. maskedval = m.nonzero()
  6315. a._mask = a._mask.copy()
  6316. if not axis:
  6317. a[np.unique(maskedval[0])] = masked
  6318. if axis in [None, 1, -1]:
  6319. a[:, np.unique(maskedval[1])] = masked
  6320. return a
  6321. # Include masked dot here to avoid import problems in getting it from
  6322. # extras.py. Note that it is not included in __all__, but rather exported
  6323. # from extras in order to avoid backward compatibility problems.
  6324. def dot(a, b, strict=False, out=None):
  6325. """
  6326. Return the dot product of two arrays.
  6327. This function is the equivalent of `numpy.dot` that takes masked values
  6328. into account. Note that `strict` and `out` are in different position
  6329. than in the method version. In order to maintain compatibility with the
  6330. corresponding method, it is recommended that the optional arguments be
  6331. treated as keyword only. At some point that may be mandatory.
  6332. .. note::
  6333. Works only with 2-D arrays at the moment.
  6334. Parameters
  6335. ----------
  6336. a, b : masked_array_like
  6337. Inputs arrays.
  6338. strict : bool, optional
  6339. Whether masked data are propagated (True) or set to 0 (False) for
  6340. the computation. Default is False. Propagating the mask means that
  6341. if a masked value appears in a row or column, the whole row or
  6342. column is considered masked.
  6343. out : masked_array, optional
  6344. Output argument. This must have the exact kind that would be returned
  6345. if it was not used. In particular, it must have the right type, must be
  6346. C-contiguous, and its dtype must be the dtype that would be returned
  6347. for `dot(a,b)`. This is a performance feature. Therefore, if these
  6348. conditions are not met, an exception is raised, instead of attempting
  6349. to be flexible.
  6350. .. versionadded:: 1.10.2
  6351. See Also
  6352. --------
  6353. numpy.dot : Equivalent function for ndarrays.
  6354. Examples
  6355. --------
  6356. >>> a = np.ma.array([[1, 2, 3], [4, 5, 6]], mask=[[1, 0, 0], [0, 0, 0]])
  6357. >>> b = np.ma.array([[1, 2], [3, 4], [5, 6]], mask=[[1, 0], [0, 0], [0, 0]])
  6358. >>> np.ma.dot(a, b)
  6359. masked_array(
  6360. data=[[21, 26],
  6361. [45, 64]],
  6362. mask=[[False, False],
  6363. [False, False]],
  6364. fill_value=999999)
  6365. >>> np.ma.dot(a, b, strict=True)
  6366. masked_array(
  6367. data=[[--, --],
  6368. [--, 64]],
  6369. mask=[[ True, True],
  6370. [ True, False]],
  6371. fill_value=999999)
  6372. """
  6373. # !!!: Works only with 2D arrays. There should be a way to get it to run
  6374. # with higher dimension
  6375. if strict and (a.ndim == 2) and (b.ndim == 2):
  6376. a = mask_rowcols(a, 0)
  6377. b = mask_rowcols(b, 1)
  6378. am = ~getmaskarray(a)
  6379. bm = ~getmaskarray(b)
  6380. if out is None:
  6381. d = np.dot(filled(a, 0), filled(b, 0))
  6382. m = ~np.dot(am, bm)
  6383. if d.ndim == 0:
  6384. d = np.asarray(d)
  6385. r = d.view(get_masked_subclass(a, b))
  6386. r.__setmask__(m)
  6387. return r
  6388. else:
  6389. d = np.dot(filled(a, 0), filled(b, 0), out._data)
  6390. if out.mask.shape != d.shape:
  6391. out._mask = np.empty(d.shape, MaskType)
  6392. np.dot(am, bm, out._mask)
  6393. np.logical_not(out._mask, out._mask)
  6394. return out
  6395. def inner(a, b):
  6396. """
  6397. Returns the inner product of a and b for arrays of floating point types.
  6398. Like the generic NumPy equivalent the product sum is over the last dimension
  6399. of a and b. The first argument is not conjugated.
  6400. """
  6401. fa = filled(a, 0)
  6402. fb = filled(b, 0)
  6403. if fa.ndim == 0:
  6404. fa.shape = (1,)
  6405. if fb.ndim == 0:
  6406. fb.shape = (1,)
  6407. return np.inner(fa, fb).view(MaskedArray)
  6408. inner.__doc__ = doc_note(np.inner.__doc__,
  6409. "Masked values are replaced by 0.")
  6410. innerproduct = inner
  6411. def outer(a, b):
  6412. "maskedarray version of the numpy function."
  6413. fa = filled(a, 0).ravel()
  6414. fb = filled(b, 0).ravel()
  6415. d = np.outer(fa, fb)
  6416. ma = getmask(a)
  6417. mb = getmask(b)
  6418. if ma is nomask and mb is nomask:
  6419. return masked_array(d)
  6420. ma = getmaskarray(a)
  6421. mb = getmaskarray(b)
  6422. m = make_mask(1 - np.outer(1 - ma, 1 - mb), copy=False)
  6423. return masked_array(d, mask=m)
  6424. outer.__doc__ = doc_note(np.outer.__doc__,
  6425. "Masked values are replaced by 0.")
  6426. outerproduct = outer
  6427. def _convolve_or_correlate(f, a, v, mode, propagate_mask):
  6428. """
  6429. Helper function for ma.correlate and ma.convolve
  6430. """
  6431. if propagate_mask:
  6432. # results which are contributed to by either item in any pair being invalid
  6433. mask = (
  6434. f(getmaskarray(a), np.ones(np.shape(v), dtype=bool), mode=mode)
  6435. | f(np.ones(np.shape(a), dtype=bool), getmaskarray(v), mode=mode)
  6436. )
  6437. data = f(getdata(a), getdata(v), mode=mode)
  6438. else:
  6439. # results which are not contributed to by any pair of valid elements
  6440. mask = ~f(~getmaskarray(a), ~getmaskarray(v))
  6441. data = f(filled(a, 0), filled(v, 0), mode=mode)
  6442. return masked_array(data, mask=mask)
  6443. def correlate(a, v, mode='valid', propagate_mask=True):
  6444. """
  6445. Cross-correlation of two 1-dimensional sequences.
  6446. Parameters
  6447. ----------
  6448. a, v : array_like
  6449. Input sequences.
  6450. mode : {'valid', 'same', 'full'}, optional
  6451. Refer to the `np.convolve` docstring. Note that the default
  6452. is 'valid', unlike `convolve`, which uses 'full'.
  6453. propagate_mask : bool
  6454. If True, then a result element is masked if any masked element contributes towards it.
  6455. If False, then a result element is only masked if no non-masked element
  6456. contribute towards it
  6457. Returns
  6458. -------
  6459. out : MaskedArray
  6460. Discrete cross-correlation of `a` and `v`.
  6461. See Also
  6462. --------
  6463. numpy.correlate : Equivalent function in the top-level NumPy module.
  6464. """
  6465. return _convolve_or_correlate(np.correlate, a, v, mode, propagate_mask)
  6466. def convolve(a, v, mode='full', propagate_mask=True):
  6467. """
  6468. Returns the discrete, linear convolution of two one-dimensional sequences.
  6469. Parameters
  6470. ----------
  6471. a, v : array_like
  6472. Input sequences.
  6473. mode : {'valid', 'same', 'full'}, optional
  6474. Refer to the `np.convolve` docstring.
  6475. propagate_mask : bool
  6476. If True, then if any masked element is included in the sum for a result
  6477. element, then the result is masked.
  6478. If False, then the result element is only masked if no non-masked cells
  6479. contribute towards it
  6480. Returns
  6481. -------
  6482. out : MaskedArray
  6483. Discrete, linear convolution of `a` and `v`.
  6484. See Also
  6485. --------
  6486. numpy.convolve : Equivalent function in the top-level NumPy module.
  6487. """
  6488. return _convolve_or_correlate(np.convolve, a, v, mode, propagate_mask)
  6489. def allequal(a, b, fill_value=True):
  6490. """
  6491. Return True if all entries of a and b are equal, using
  6492. fill_value as a truth value where either or both are masked.
  6493. Parameters
  6494. ----------
  6495. a, b : array_like
  6496. Input arrays to compare.
  6497. fill_value : bool, optional
  6498. Whether masked values in a or b are considered equal (True) or not
  6499. (False).
  6500. Returns
  6501. -------
  6502. y : bool
  6503. Returns True if the two arrays are equal within the given
  6504. tolerance, False otherwise. If either array contains NaN,
  6505. then False is returned.
  6506. See Also
  6507. --------
  6508. all, any
  6509. numpy.ma.allclose
  6510. Examples
  6511. --------
  6512. >>> a = np.ma.array([1e10, 1e-7, 42.0], mask=[0, 0, 1])
  6513. >>> a
  6514. masked_array(data=[10000000000.0, 1e-07, --],
  6515. mask=[False, False, True],
  6516. fill_value=1e+20)
  6517. >>> b = np.array([1e10, 1e-7, -42.0])
  6518. >>> b
  6519. array([ 1.00000000e+10, 1.00000000e-07, -4.20000000e+01])
  6520. >>> np.ma.allequal(a, b, fill_value=False)
  6521. False
  6522. >>> np.ma.allequal(a, b)
  6523. True
  6524. """
  6525. m = mask_or(getmask(a), getmask(b))
  6526. if m is nomask:
  6527. x = getdata(a)
  6528. y = getdata(b)
  6529. d = umath.equal(x, y)
  6530. return d.all()
  6531. elif fill_value:
  6532. x = getdata(a)
  6533. y = getdata(b)
  6534. d = umath.equal(x, y)
  6535. dm = array(d, mask=m, copy=False)
  6536. return dm.filled(True).all(None)
  6537. else:
  6538. return False
  6539. def allclose(a, b, masked_equal=True, rtol=1e-5, atol=1e-8):
  6540. """
  6541. Returns True if two arrays are element-wise equal within a tolerance.
  6542. This function is equivalent to `allclose` except that masked values
  6543. are treated as equal (default) or unequal, depending on the `masked_equal`
  6544. argument.
  6545. Parameters
  6546. ----------
  6547. a, b : array_like
  6548. Input arrays to compare.
  6549. masked_equal : bool, optional
  6550. Whether masked values in `a` and `b` are considered equal (True) or not
  6551. (False). They are considered equal by default.
  6552. rtol : float, optional
  6553. Relative tolerance. The relative difference is equal to ``rtol * b``.
  6554. Default is 1e-5.
  6555. atol : float, optional
  6556. Absolute tolerance. The absolute difference is equal to `atol`.
  6557. Default is 1e-8.
  6558. Returns
  6559. -------
  6560. y : bool
  6561. Returns True if the two arrays are equal within the given
  6562. tolerance, False otherwise. If either array contains NaN, then
  6563. False is returned.
  6564. See Also
  6565. --------
  6566. all, any
  6567. numpy.allclose : the non-masked `allclose`.
  6568. Notes
  6569. -----
  6570. If the following equation is element-wise True, then `allclose` returns
  6571. True::
  6572. absolute(`a` - `b`) <= (`atol` + `rtol` * absolute(`b`))
  6573. Return True if all elements of `a` and `b` are equal subject to
  6574. given tolerances.
  6575. Examples
  6576. --------
  6577. >>> a = np.ma.array([1e10, 1e-7, 42.0], mask=[0, 0, 1])
  6578. >>> a
  6579. masked_array(data=[10000000000.0, 1e-07, --],
  6580. mask=[False, False, True],
  6581. fill_value=1e+20)
  6582. >>> b = np.ma.array([1e10, 1e-8, -42.0], mask=[0, 0, 1])
  6583. >>> np.ma.allclose(a, b)
  6584. False
  6585. >>> a = np.ma.array([1e10, 1e-8, 42.0], mask=[0, 0, 1])
  6586. >>> b = np.ma.array([1.00001e10, 1e-9, -42.0], mask=[0, 0, 1])
  6587. >>> np.ma.allclose(a, b)
  6588. True
  6589. >>> np.ma.allclose(a, b, masked_equal=False)
  6590. False
  6591. Masked values are not compared directly.
  6592. >>> a = np.ma.array([1e10, 1e-8, 42.0], mask=[0, 0, 1])
  6593. >>> b = np.ma.array([1.00001e10, 1e-9, 42.0], mask=[0, 0, 1])
  6594. >>> np.ma.allclose(a, b)
  6595. True
  6596. >>> np.ma.allclose(a, b, masked_equal=False)
  6597. False
  6598. """
  6599. x = masked_array(a, copy=False)
  6600. y = masked_array(b, copy=False)
  6601. # make sure y is an inexact type to avoid abs(MIN_INT); will cause
  6602. # casting of x later.
  6603. # NOTE: We explicitly allow timedelta, which used to work. This could
  6604. # possibly be deprecated. See also gh-18286.
  6605. # timedelta works if `atol` is an integer or also a timedelta.
  6606. # Although, the default tolerances are unlikely to be useful
  6607. if y.dtype.kind != "m":
  6608. dtype = np.result_type(y, 1.)
  6609. if y.dtype != dtype:
  6610. y = masked_array(y, dtype=dtype, copy=False)
  6611. m = mask_or(getmask(x), getmask(y))
  6612. xinf = np.isinf(masked_array(x, copy=False, mask=m)).filled(False)
  6613. # If we have some infs, they should fall at the same place.
  6614. if not np.all(xinf == filled(np.isinf(y), False)):
  6615. return False
  6616. # No infs at all
  6617. if not np.any(xinf):
  6618. d = filled(less_equal(absolute(x - y), atol + rtol * absolute(y)),
  6619. masked_equal)
  6620. return np.all(d)
  6621. if not np.all(filled(x[xinf] == y[xinf], masked_equal)):
  6622. return False
  6623. x = x[~xinf]
  6624. y = y[~xinf]
  6625. d = filled(less_equal(absolute(x - y), atol + rtol * absolute(y)),
  6626. masked_equal)
  6627. return np.all(d)
  6628. def asarray(a, dtype=None, order=None):
  6629. """
  6630. Convert the input to a masked array of the given data-type.
  6631. No copy is performed if the input is already an `ndarray`. If `a` is
  6632. a subclass of `MaskedArray`, a base class `MaskedArray` is returned.
  6633. Parameters
  6634. ----------
  6635. a : array_like
  6636. Input data, in any form that can be converted to a masked array. This
  6637. includes lists, lists of tuples, tuples, tuples of tuples, tuples
  6638. of lists, ndarrays and masked arrays.
  6639. dtype : dtype, optional
  6640. By default, the data-type is inferred from the input data.
  6641. order : {'C', 'F'}, optional
  6642. Whether to use row-major ('C') or column-major ('FORTRAN') memory
  6643. representation. Default is 'C'.
  6644. Returns
  6645. -------
  6646. out : MaskedArray
  6647. Masked array interpretation of `a`.
  6648. See Also
  6649. --------
  6650. asanyarray : Similar to `asarray`, but conserves subclasses.
  6651. Examples
  6652. --------
  6653. >>> x = np.arange(10.).reshape(2, 5)
  6654. >>> x
  6655. array([[0., 1., 2., 3., 4.],
  6656. [5., 6., 7., 8., 9.]])
  6657. >>> np.ma.asarray(x)
  6658. masked_array(
  6659. data=[[0., 1., 2., 3., 4.],
  6660. [5., 6., 7., 8., 9.]],
  6661. mask=False,
  6662. fill_value=1e+20)
  6663. >>> type(np.ma.asarray(x))
  6664. <class 'numpy.ma.core.MaskedArray'>
  6665. """
  6666. order = order or 'C'
  6667. return masked_array(a, dtype=dtype, copy=False, keep_mask=True,
  6668. subok=False, order=order)
  6669. def asanyarray(a, dtype=None):
  6670. """
  6671. Convert the input to a masked array, conserving subclasses.
  6672. If `a` is a subclass of `MaskedArray`, its class is conserved.
  6673. No copy is performed if the input is already an `ndarray`.
  6674. Parameters
  6675. ----------
  6676. a : array_like
  6677. Input data, in any form that can be converted to an array.
  6678. dtype : dtype, optional
  6679. By default, the data-type is inferred from the input data.
  6680. order : {'C', 'F'}, optional
  6681. Whether to use row-major ('C') or column-major ('FORTRAN') memory
  6682. representation. Default is 'C'.
  6683. Returns
  6684. -------
  6685. out : MaskedArray
  6686. MaskedArray interpretation of `a`.
  6687. See Also
  6688. --------
  6689. asarray : Similar to `asanyarray`, but does not conserve subclass.
  6690. Examples
  6691. --------
  6692. >>> x = np.arange(10.).reshape(2, 5)
  6693. >>> x
  6694. array([[0., 1., 2., 3., 4.],
  6695. [5., 6., 7., 8., 9.]])
  6696. >>> np.ma.asanyarray(x)
  6697. masked_array(
  6698. data=[[0., 1., 2., 3., 4.],
  6699. [5., 6., 7., 8., 9.]],
  6700. mask=False,
  6701. fill_value=1e+20)
  6702. >>> type(np.ma.asanyarray(x))
  6703. <class 'numpy.ma.core.MaskedArray'>
  6704. """
  6705. # workaround for #8666, to preserve identity. Ideally the bottom line
  6706. # would handle this for us.
  6707. if isinstance(a, MaskedArray) and (dtype is None or dtype == a.dtype):
  6708. return a
  6709. return masked_array(a, dtype=dtype, copy=False, keep_mask=True, subok=True)
  6710. ##############################################################################
  6711. # Pickling #
  6712. ##############################################################################
  6713. def _pickle_warn(method):
  6714. # NumPy 1.15.0, 2017-12-10
  6715. warnings.warn(
  6716. f"np.ma.{method} is deprecated, use pickle.{method} instead",
  6717. DeprecationWarning, stacklevel=3)
  6718. def fromfile(file, dtype=float, count=-1, sep=''):
  6719. raise NotImplementedError(
  6720. "fromfile() not yet implemented for a MaskedArray.")
  6721. def fromflex(fxarray):
  6722. """
  6723. Build a masked array from a suitable flexible-type array.
  6724. The input array has to have a data-type with ``_data`` and ``_mask``
  6725. fields. This type of array is output by `MaskedArray.toflex`.
  6726. Parameters
  6727. ----------
  6728. fxarray : ndarray
  6729. The structured input array, containing ``_data`` and ``_mask``
  6730. fields. If present, other fields are discarded.
  6731. Returns
  6732. -------
  6733. result : MaskedArray
  6734. The constructed masked array.
  6735. See Also
  6736. --------
  6737. MaskedArray.toflex : Build a flexible-type array from a masked array.
  6738. Examples
  6739. --------
  6740. >>> x = np.ma.array(np.arange(9).reshape(3, 3), mask=[0] + [1, 0] * 4)
  6741. >>> rec = x.toflex()
  6742. >>> rec
  6743. array([[(0, False), (1, True), (2, False)],
  6744. [(3, True), (4, False), (5, True)],
  6745. [(6, False), (7, True), (8, False)]],
  6746. dtype=[('_data', '<i8'), ('_mask', '?')])
  6747. >>> x2 = np.ma.fromflex(rec)
  6748. >>> x2
  6749. masked_array(
  6750. data=[[0, --, 2],
  6751. [--, 4, --],
  6752. [6, --, 8]],
  6753. mask=[[False, True, False],
  6754. [ True, False, True],
  6755. [False, True, False]],
  6756. fill_value=999999)
  6757. Extra fields can be present in the structured array but are discarded:
  6758. >>> dt = [('_data', '<i4'), ('_mask', '|b1'), ('field3', '<f4')]
  6759. >>> rec2 = np.zeros((2, 2), dtype=dt)
  6760. >>> rec2
  6761. array([[(0, False, 0.), (0, False, 0.)],
  6762. [(0, False, 0.), (0, False, 0.)]],
  6763. dtype=[('_data', '<i4'), ('_mask', '?'), ('field3', '<f4')])
  6764. >>> y = np.ma.fromflex(rec2)
  6765. >>> y
  6766. masked_array(
  6767. data=[[0, 0],
  6768. [0, 0]],
  6769. mask=[[False, False],
  6770. [False, False]],
  6771. fill_value=999999,
  6772. dtype=int32)
  6773. """
  6774. return masked_array(fxarray['_data'], mask=fxarray['_mask'])
  6775. class _convert2ma:
  6776. """
  6777. Convert functions from numpy to numpy.ma.
  6778. Parameters
  6779. ----------
  6780. _methodname : string
  6781. Name of the method to transform.
  6782. """
  6783. __doc__ = None
  6784. def __init__(self, funcname, params=None):
  6785. self._func = getattr(np, funcname)
  6786. self.__doc__ = self.getdoc()
  6787. self._extras = params or {}
  6788. def getdoc(self):
  6789. "Return the doc of the function (from the doc of the method)."
  6790. doc = getattr(self._func, '__doc__', None)
  6791. sig = get_object_signature(self._func)
  6792. if doc:
  6793. # Add the signature of the function at the beginning of the doc
  6794. if sig:
  6795. sig = "%s%s\n" % (self._func.__name__, sig)
  6796. doc = sig + doc
  6797. return doc
  6798. def __call__(self, *args, **params):
  6799. # Find the common parameters to the call and the definition
  6800. _extras = self._extras
  6801. common_params = set(params).intersection(_extras)
  6802. # Drop the common parameters from the call
  6803. for p in common_params:
  6804. _extras[p] = params.pop(p)
  6805. # Get the result
  6806. result = self._func.__call__(*args, **params).view(MaskedArray)
  6807. if "fill_value" in common_params:
  6808. result.fill_value = _extras.get("fill_value", None)
  6809. if "hardmask" in common_params:
  6810. result._hardmask = bool(_extras.get("hard_mask", False))
  6811. return result
  6812. arange = _convert2ma('arange', params=dict(fill_value=None, hardmask=False))
  6813. clip = np.clip
  6814. diff = np.diff
  6815. empty = _convert2ma('empty', params=dict(fill_value=None, hardmask=False))
  6816. empty_like = _convert2ma('empty_like')
  6817. frombuffer = _convert2ma('frombuffer')
  6818. fromfunction = _convert2ma('fromfunction')
  6819. identity = _convert2ma(
  6820. 'identity', params=dict(fill_value=None, hardmask=False))
  6821. indices = np.indices
  6822. ones = _convert2ma('ones', params=dict(fill_value=None, hardmask=False))
  6823. ones_like = np.ones_like
  6824. squeeze = np.squeeze
  6825. zeros = _convert2ma('zeros', params=dict(fill_value=None, hardmask=False))
  6826. zeros_like = np.zeros_like
  6827. def append(a, b, axis=None):
  6828. """Append values to the end of an array.
  6829. .. versionadded:: 1.9.0
  6830. Parameters
  6831. ----------
  6832. a : array_like
  6833. Values are appended to a copy of this array.
  6834. b : array_like
  6835. These values are appended to a copy of `a`. It must be of the
  6836. correct shape (the same shape as `a`, excluding `axis`). If `axis`
  6837. is not specified, `b` can be any shape and will be flattened
  6838. before use.
  6839. axis : int, optional
  6840. The axis along which `v` are appended. If `axis` is not given,
  6841. both `a` and `b` are flattened before use.
  6842. Returns
  6843. -------
  6844. append : MaskedArray
  6845. A copy of `a` with `b` appended to `axis`. Note that `append`
  6846. does not occur in-place: a new array is allocated and filled. If
  6847. `axis` is None, the result is a flattened array.
  6848. See Also
  6849. --------
  6850. numpy.append : Equivalent function in the top-level NumPy module.
  6851. Examples
  6852. --------
  6853. >>> import numpy.ma as ma
  6854. >>> a = ma.masked_values([1, 2, 3], 2)
  6855. >>> b = ma.masked_values([[4, 5, 6], [7, 8, 9]], 7)
  6856. >>> ma.append(a, b)
  6857. masked_array(data=[1, --, 3, 4, 5, 6, --, 8, 9],
  6858. mask=[False, True, False, False, False, False, True, False,
  6859. False],
  6860. fill_value=999999)
  6861. """
  6862. return concatenate([a, b], axis)