From 380b2817cff6de1cd0dd6299fb4e190d906f0d83 Mon Sep 17 00:00:00 2001 From: Duygu Altinok Date: Mon, 9 Aug 2021 12:39:22 +0200 Subject: [PATCH 01/70] updated unv json for new book --- website/meta/universe.json | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/website/meta/universe.json b/website/meta/universe.json index 1f469c33b..84e14a9f6 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -1614,6 +1614,22 @@ "author": "Bhargav Srinivasa-Desikan", "category": ["books"] }, + { + "type": "education", + "id": "mastering-spacy", + "title": "Mastering spaCy", + "slogan": "Packt, 2021", + "description": "This is your ultimate spaCy book. Master the crucial skills to use spaCy components effectively to create real-world NLP applications with spaCy. Explaining linguistic concepts such as dependency parsing, POS-tagging and named entity extraction with many examples, this book will help you to conquer computational linguistics with spaCy. The book further focuses on ML topics with Keras and Tensorflow. You'll cover popular topics, including intent recognition, sentiment analysis and context resolution; and use them on popular datasets and interpret the results. A special hands-on section on chatbot design is included.", + "github": "PacktPublishing/Mastering-spaCy", + "cover": "https://tinyimg.io/i/aWEm0dh.jpeg", + "url": "https://www.amazon.com/Mastering-spaCy-end-end-implementing/dp/1800563353", + "author": "Duygu Altinok", + "author_links": { + "github": "DuyguA", + "website": "https://www.linkedin.com/in/duygu-altinok-4021389a" + }, + "category": ["books"] + }, { "type": "education", "id": "learning-path-spacy", From 6029cfc3912ba331168fcac71147efd525b51ba6 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Tue, 10 Aug 2021 20:47:49 +0900 Subject: [PATCH 02/70] Add scores to output in spancat (#8855) * Add scores to output in spancat This exposes the scores as an attribute on the SpanGroup. Includes a basic test. * Add basic doc note * Vectorize score calcs * Add "annotation format" section * Update website/docs/api/spancategorizer.md Co-authored-by: Adriane Boyd * Clean up doc section * Ran prettier on docs * Get arrays off the gpu before iterating over them * Remove int() calls Co-authored-by: Adriane Boyd --- spacy/pipeline/spancat.py | 27 ++++++++++++++++----------- spacy/tests/pipeline/test_spancat.py | 2 ++ website/docs/api/spancategorizer.md | 16 ++++++++++++++++ 3 files changed, 34 insertions(+), 11 deletions(-) diff --git a/spacy/pipeline/spancat.py b/spacy/pipeline/spancat.py index 8d1be06c3..e2f53be0d 100644 --- a/spacy/pipeline/spancat.py +++ b/spacy/pipeline/spancat.py @@ -408,16 +408,21 @@ class SpanCategorizer(TrainablePipe): spans = SpanGroup(doc, name=self.key) max_positive = self.cfg["max_positive"] threshold = self.cfg["threshold"] + + keeps = scores >= threshold + ranked = (scores * -1).argsort() + keeps[ranked[:, max_positive:]] = False + spans.attrs["scores"] = scores[keeps].flatten() + + indices = self.model.ops.to_numpy(indices) + keeps = self.model.ops.to_numpy(keeps) + for i in range(indices.shape[0]): - start = int(indices[i, 0]) - end = int(indices[i, 1]) - positives = [] - for j, score in enumerate(scores[i]): - if score >= threshold: - positives.append((score, start, end, labels[j])) - positives.sort(reverse=True) - if max_positive: - positives = positives[:max_positive] - for score, start, end, label in positives: - spans.append(Span(doc, start, end, label=label)) + start = indices[i, 0] + end = indices[i, 1] + + for j, keep in enumerate(keeps[i]): + if keep: + spans.append(Span(doc, start, end, label=labels[j])) + return spans diff --git a/spacy/tests/pipeline/test_spancat.py b/spacy/tests/pipeline/test_spancat.py index 6a5ae2c66..bf1c00041 100644 --- a/spacy/tests/pipeline/test_spancat.py +++ b/spacy/tests/pipeline/test_spancat.py @@ -85,12 +85,14 @@ def test_simple_train(): doc = nlp("I like London and Berlin.") assert doc.spans[spancat.key] == doc.spans[SPAN_KEY] assert len(doc.spans[spancat.key]) == 2 + assert len(doc.spans[spancat.key].attrs["scores"]) == 2 assert doc.spans[spancat.key][0].text == "London" scores = nlp.evaluate(get_examples()) assert f"spans_{SPAN_KEY}_f" in scores assert scores[f"spans_{SPAN_KEY}_f"] == 1.0 + def test_ngram_suggester(en_tokenizer): # test different n-gram lengths for size in [1, 2, 3]: diff --git a/website/docs/api/spancategorizer.md b/website/docs/api/spancategorizer.md index 57395846d..d37b2f23a 100644 --- a/website/docs/api/spancategorizer.md +++ b/website/docs/api/spancategorizer.md @@ -13,6 +13,22 @@ A span categorizer consists of two parts: a [suggester function](#suggesters) that proposes candidate spans, which may or may not overlap, and a labeler model that predicts zero or more labels for each candidate. +Predicted spans will be saved in a [`SpanGroup`](/api/spangroup) on the doc. +Individual span scores can be found in `spangroup.attrs["scores"]`. + +## Assigned Attributes {#assigned-attributes} + +Predictions will be saved to `Doc.spans[spans_key]` as a +[`SpanGroup`](/api/spangroup). The scores for the spans in the `SpanGroup` will +be saved in `SpanGroup.attrs["scores"]`. + +`spans_key` defaults to `"sc"`, but can be passed as a parameter. + +| Location | Value | +| -------------------------------------- | -------------------------------------------------------- | +| `Doc.spans[spans_key]` | The annotated spans. ~~SpanGroup~~ | +| `Doc.spans[spans_key].attrs["scores"]` | The score for each span in the `SpanGroup`. ~~Floats1d~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes From e227d24d4356ddd6ffc0b997a092c02225bbc3e3 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Tue, 10 Aug 2021 22:13:53 +0900 Subject: [PATCH 03/70] Allow passing in array vars for speedup (#8882) * Allow passing in array vars for speedup This fixes #8845. Not sure about the docstring changes here... * Update docs Types maybe need more detail? Maybe not? * Run prettier on docs * Update spacy/tokens/span.pyx Co-authored-by: Sofie Van Landeghem --- spacy/tokens/span.pyx | 10 +++++++--- website/docs/api/span.md | 14 ++++++++++---- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/spacy/tokens/span.pyx b/spacy/tokens/span.pyx index 48c6053c1..7087ba986 100644 --- a/spacy/tokens/span.pyx +++ b/spacy/tokens/span.pyx @@ -218,10 +218,12 @@ cdef class Span: return Underscore(Underscore.span_extensions, self, start=self.c.start_char, end=self.c.end_char) - def as_doc(self, *, bint copy_user_data=False): + def as_doc(self, *, bint copy_user_data=False, array_head=None, array=None): """Create a `Doc` object with a copy of the `Span`'s data. copy_user_data (bool): Whether or not to copy the original doc's user data. + array_head (tuple): `Doc` array attrs, can be passed in to speed up computation. + array (ndarray): `Doc` as array, can be passed in to speed up computation. RETURNS (Doc): The `Doc` copy of the span. DOCS: https://spacy.io/api/span#as_doc @@ -229,8 +231,10 @@ cdef class Span: words = [t.text for t in self] spaces = [bool(t.whitespace_) for t in self] cdef Doc doc = Doc(self.doc.vocab, words=words, spaces=spaces) - array_head = self.doc._get_array_attrs() - array = self.doc.to_array(array_head) + if array_head is None: + array_head = self.doc._get_array_attrs() + if array is None: + array = self.doc.to_array(array_head) array = array[self.start : self.end] self._fix_dep_copy(array_head, array) # Fix initial IOB so the entities are valid for doc.ents below. diff --git a/website/docs/api/span.md b/website/docs/api/span.md index 9212f957d..48e310979 100644 --- a/website/docs/api/span.md +++ b/website/docs/api/span.md @@ -303,6 +303,10 @@ not been implemeted for the given language, a `NotImplementedError` is raised. Create a new `Doc` object corresponding to the `Span`, with a copy of the data. +When calling this on many spans from the same doc, passing in a precomputed +array representation of the doc using the `array_head` and `array` args can save +time. + > #### Example > > ```python @@ -312,10 +316,12 @@ Create a new `Doc` object corresponding to the `Span`, with a copy of the data. > assert doc2.text == "New York" > ``` -| Name | Description | -| ---------------- | ------------------------------------------------------------- | -| `copy_user_data` | Whether or not to copy the original doc's user data. ~~bool~~ | -| **RETURNS** | A `Doc` object of the `Span`'s content. ~~Doc~~ | +| Name | Description | +| ---------------- | -------------------------------------------------------------------------------------------------------------------- | +| `copy_user_data` | Whether or not to copy the original doc's user data. ~~bool~~ | +| `array_head` | Precomputed array attributes (headers) of the original doc, as generated by `Doc._get_array_attrs()`. ~~Tuple~~ | +| `array` | Precomputed array version of the original doc as generated by [`Doc.to_array`](/api/doc#to_array). ~~numpy.ndarray~~ | +| **RETURNS** | A `Doc` object of the `Span`'s content. ~~Doc~~ | ## Span.root {#root tag="property" model="parser"} From 4f769ff91333c2df4369626fc68a72e26f1546a0 Mon Sep 17 00:00:00 2001 From: Ines Montani Date: Thu, 12 Aug 2021 13:46:20 +1000 Subject: [PATCH 04/70] Update Prodigy project template for v1.11 [ci skip] --- website/docs/images/prodigy_train_curve.jpg | Bin 0 -> 204599 bytes website/docs/usage/projects.md | 109 +++++++++++++------- 2 files changed, 70 insertions(+), 39 deletions(-) create mode 100644 website/docs/images/prodigy_train_curve.jpg diff --git a/website/docs/images/prodigy_train_curve.jpg b/website/docs/images/prodigy_train_curve.jpg new file mode 100644 index 0000000000000000000000000000000000000000..af22cd06582730599b9b2f97d02ab0d4e861c119 GIT binary patch literal 204599 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 {EXAt zYjGx7M(aa4GaaEnr5)|_iDTQ|=}k!e>re(KfDkW8d@5BW=Hco=^oOO*oM5rnIt{fI zZ>`Eg1<%xddDv%R{UZ*>GN}z^@YdPJ)e;qxD;mmz2~2MgT$VhWk$SM`2Z@I2iUhk- zFRqWQUTm@^Oj*&9wJ@X2b@nzPxL=GEHLFL*vJG03>XEg;`tMEwndon4va)w%>it4Z z`9@cC860)aN*8jlB)E4re_hK9YRmev5PYmfHm-dsVq-P%@zzw_Lx-Ni`ME|`Owx@* z@*?j!YONi9+J2e2Zf%unS~*u+h2`BlXBH%aW#1ElCn3KMq4neBY*}zfQ-8c>ti^Ar z>N$}p|Fu$huwcbGy2L3Hg|9vn=b@Z8?r%XnM~;sEb&AbAN(SN8bPsz2y|0$Y zBil9s912v+*6_EObNR2HCviTRMDr5EXSLAT^1eU9&X6|4CSy^W=cluj+jz+Ic16?` z{>2*)^0{y{$iz66SB$H@GFV4<#>4`kDfpga!-fk{Xlc{+w1ZN6z~cK3R)KHmNu@gY zDM%s$V_Vu&4n8@jd2FGdScbx?dd@DhypO#n=iv2Kddg%yU8~_w?8;5r*y}=89F_*=P|dG-QPghMjLH1@#gqE?IC)?AqhYzM zM1py6LU z#w}37Tvf7n47Weagi(>j{dm?Nlb=K#4klY_#Q)Zr$263y^CE?|fVAV~z5Kjj_7EM1 z+n?EQBoZjk<#4C1Poe z;DqIj{H&OTxlm*{fUH(-6zOY={$&i6>27U9^GJDa05;{sBdZLxL4tXz8;Ie5|D9hlp;8sIZsDfAgc}mWnaVEqjW|70R1)^FlEJ;0Vt~bin?mlU=Xh3 zk2tpk4Zk9xE&%oVS&>dyOO|iNOk13VtrJ>mpNpVwLlS zk1*ZLL81%N4WER$C`XXAtn-DnM!y9ahsZK^NVU84zBLytvSSt|qa>TJa>D61@p?fu zGbv2fK@IB`^i(MsbX?H?I0GJzVJ=wS7^XKzQ{qt-(}N~qp&ttxTLyJp`KEz6@0C@J z4+>&EQ%Zxo6f}L>%)mDuDvb!GX~^yx+dY7FArtwOZU7cm8dbSfzFnb|atbJPv@5wA z0rvj;2{ecrzcJ4Cu>?-1rKujs7uO?gh)2;PCg%zI-jNwM$N% zP@fwm%%bz!{ZY&MmG1^P9)&{Ta`XD6VvQeS$PUl zD&^Y&)U-Cp{1JC+U$%aH{ZwYqvZuN8D&UL4RKTvsDKJiko7j-mZ9c9ZoQ-r-M=^a=e+dtfHJfR4OvEE+MwI&$ zFg6K6go#jkcTj9yRB^vZzID~aPJ{B{+MZ&HG%ac(yh3+_1^Qe=?8eXxTk|k$Ix2xu z=L+R10B*6EhHo?p$)=LfGw>w7-ON4OV$gtEU zrR)@tk7dScR!o|x#`f1!JZe+eIN9p&AO9>&hPa5NCda@H`wIRWGMW_`6AoY{PD#nZDt1*uF>M52_&4fd0p~S@ z!I+S@Zqj)Ug$I>YYFtl?3;BneNHms%NNjJi?RM;{o&vU=PVJpzJv=K10zIrzy3KVR zk7CTh-b5?1GreQ6r@&H`!xUPdFq?|4n36GP83B`D)583xoQw`@a;?0%j7W>brX1Qk zpsZE$@l}k_K}vy0E_)jdZ*hg2DX>A&Quifugf2%cXBwPeCzX1B z(t_#4SsvRL_ikTOl2{QVE8s{GQ|~5Eb=6xYbW+_#3NC({%kP z$@mSIl+B%tiIeFgqa8V_kzP`SC`8XGU!_aW| znULa$Ia1+kHZx5L+b%KkJx{he19SSuFbPC-*I_^MJJ~25b%ux;+k&t+)@?a3$lJ4x z?=iW5-6T~VD4sLSP)Ik6#eAh(#>^#iM|LzHa$UXAQ-YE5GEPokTdXZz;uIjC?-UIZ z#*|)hbnYn}e8bZn#rcEAc-5OT*09{1^r3lE@@Q~YiXUU4b|EVAQ+@Bf70!fWN;&~t zW0J7uuvoui!Ab`=;ctm^Ul{rdXjn0@w<`QX)YCSd=Mt2+x04oHzkc}S-ni_r*ictk zJouGo$?>?lLQ{5?*^NBXblX~dpL$_&*9!zq)NHO5dqdHWL$IftW$C+aWKD^D1>6ouvMQ^tHo-3oQocU)~J@;S^|e^i(_Sh!F=A6))c-N2~0 zm^wG*TDKUw7CEupDHW&N@L~O%ZpF(&4Dt^P%_cN=s$7e;`Wi^O%ws|ciRaPLNc;sP z#hyN7>w{)t;jjq9@A@vt)o3zgHZT<9-7iY}(3k#|+nsyJLvqaTrXL#R( zG8%pE*DJEVQ5jiMWbcAS9c#cf7$-a=udDUmlWE*k;qKIO-B)2J8FS!nrmBQu7VH)` zb`sBwiZ;3~g{~$8`nFjmVMA^0XsA+kTdSY??ONWXW$o71vd3IuoT@Gb$SIWVuW*?L zq_Dj!Ry~!J2rHVZj4Jctg;#r!9y0r7bi0w4vS~rnd6i&hs|DGvsv0mppKSv7$4VR0 zQ-MC|je0LmqPSMrt1Z(gm-O)+I~O7?wR4A#dUqHH%4Ii6D-C~BBN(iTLaQ~p--_0m@8GG_N$OyfSk~?;hHVIQ=pG%8_nd4MM0mr!pLl4 z{`HVmA`o>V{+`eG=LdXV`aR2zwJYSBnM5iFs^YN)3i_3XuuI=15qC0%a_&4dtf(ml zMZx+;5gTwPbT6-Fr?|+=sGwx)VPORWeH4a$%(63hq7tIFIzLnxC#SNTnqv(cqe=;9 zb1d6QW4_N#6X?g&vqDF##xG4^^$qC{laKzf+3MwaUCWn|jnW~Bo+RM``x?DxLJi{v;9aeL>0mW@fJBu;O z5rcQqEp*GtZc|Ft?v~NO5vHe|xq&pMgn8IXrt4=x#Zk4^%u#s^U`;8}$-K0_^NflA2WTyCV0*zK0 z5{vs41~S!@(wpdmX~!6bcS1` zK5uqS1UidBSiC=fHS$1N-g`BUWNnA0oMafQG`+SRv5Q|rSZ0txG@pglOgkc;z;${X zvByZxMyFV*xq{Pd&Dnt2y`aWd>BgX{F1F6Au~y}%{B*g5jO;f~T24k%aDMK0bSLHB zREgOcgUBU56(t?0im6M-v05I0j4_Kc<(1Rzy2GOv3PF84p_}$JAwnJV(5>F<1LT94 z<;5T_a4*RA3-!$xrINDb;8Kb#!^V;Au`+SNEEnu_XIn3ece#hAtF~scsp1TL&q>(= zpr42Ap!b>Iv;Hudl1&^XxAcnL+@Onb9@7M$ExDd*4^;f*i)33o=)t`QhWwcmLt?W| zN{HFx&*U)2vx7^EP^sp6MKQE8k&-wfiwWLwkyI0cSGdLZGqH3+NaW-4ODDD#6-C=O|;O;OmxD(t75+Jy{dm#AW?!gJ}gOlLFLeSv3v-i9A zx#xT9?7FAEs#CY>*8Ov)yI1#GPs{4xlD;_gF`WLqSC_N;6D}|^wyzNFfNhzB(Vhq? zZoXo}{@9%&MLB5T17`Z_Be$m4dfJ}w9 zM?YE|^&uHSP)Dmbm>r*t2r zbJt3kw64y>T)Wa~gQUtSQ0*l}3_-~V+YG`6Dt|NN?!WrzD*R}MRf8{m7r2H*E|5Zq z>U4`)o^!lLN7p+6BE=@Y6UA(JD!DcF`^Xj}5gAsS?wzT;y4JlIo-MIcU!fuLn{|>0 zVgwIhA8g4TVW0?Xn-C}zud&oy>?{7v|K`rbvyQ>-T}0{4c~ILqMX0M?scb)a%>ur^ z+SM$LMwGi{$rU}tQtSO0u%K9p8}LRg(>k}0(pdDzc$H-{!iiJ>x-65v`GFt9ECV*z z^=p`RJ#fWb3fUqR5Oi9F3VFvbAY0QgiPdC>is9a-B^`O9SerA2^d?&$Yso&h6kq%H zeXUbA5|*jJR#0DyUR%pP{mHq)l#t{4IYVUKd07fiF+syYUPalG^X-$u?PW`|9{jjc z(G>wTW+udV3R8-Bh=c^(SZO*vl~}`oeC)o-vi3 z;IUxEhF)XJEP$C=dkbF4QyA5NIRx92e!4_Tv>c{MEzCZ@+d zb|M{fh8!YwX&tBFNj_e4tST*>EN6uCCU(&L*XS&me5k7le`QbUNwnvcU{HV)h-)L2 z$|{XboBzy_^<+9I`Opl?Q9yB4%j|bpIll32ieZYDeu*OO@V!I#Nqp0BTKkBJd~Rd* z2gYRNVqGO^^xNKWjwPA6SJ|y4f7PUzE759YlYw<{bz_Kj{P*oed#_tPV~SElJy!{= zbnus*jNiK@JB~zY=qiA5IAn`Or{H}aY;MEd3ot_ga&u43_nh4oG(G%6SeH zaO2QzV@lza3-NnUHf7j)P~lSlq>%4tJum}Q1!9Y(AJNBZ2Zff*#~Q(a*kGnkZ~bUD ztlc4Ij5J|<<3@#?_4%vDVRZ@a>5c>MMyTF!r0FW9D;i)B56g*eB~Dr}e|?UMhR5yK z$9(!&;%XKRnQ-AIRMvPYixegf!Hhf{bGf)}6P_2wc+c|LoAs*>Wd9uSyYi=WYao z^0MtLiG;;|8|P1haz{-ZY3Ws*eIL-GLY#?@o!%I~7sVGCgQ&j88cS{9!D3@l{>`wQ zXu&|o;6**Z_n%E!TfvT1ZG7->N+i-4fA!#gWBHBn{__u+B@c-@#J{+7uUntHdo3kK z?>g}c<|r>dZSyGb-Ie*SEnxN6sO}ow4R=vmUr`!-uxGKYkidq172E!&WKbP_AcR;z z0E*JENVav*KmWrx6*vKbHQl5+MTw_<1O6#3qmvar#{uvg3@Mrhl%u0FJMJ0Y_#=|h z50^#8U4LMRTE0Uvoswv5M-CA=IV`ZYSGl4i>@8_z$QvkK>TKdife?@Q#(X>U)m0XZ z1ciKEzbpxh(=4;yyL`+eS-&PGQZk0a6YjtM;o4AF!E??e&3B(93DW*4kYC0?Y5`Iq zZ_27O365KLXWGvBzO?1yj7=$Hx5DvdPbHz{f3R}jTY=tll2fSXUe;vBQ5WcO`fR$G`0{hF z=fddcb5D2uUwrLk6?mrgxR-YY1xilB1K1?0Ye*~~Y{fPH#ddv<2g;atGcn1iwAsH} z#IX_XEZF}BQ57;QMvQb6<0LK&Tamk?VCf6u#TSbju?+f7*$|x7=te0)r}KxkERDao zAiF>qHs@%g%bTqU{)^PEYo88gYS$VGQ6|FJKbdzMNeD|BCi5FDCh?S~dQv*})*B(H zJ@053)ZICXT_#Ky4M|Ykg41heMokATfWyIgEFewwZrR2X80XIs1xUT#$AiH6YehVQ z(T*2l9JU7p#v3~T+k>Gqb$wkVSi(;emd;t0Oup@)l%=@_vRiX@CuL__mB6rAi7ot< zhB@WK6Wy_h4W^1hwIO8pd*DjJ`m*5TsE@-EyumtPX?~=|30! zDY}vVTQuqIVP3qU0rF=mt*J&58@7Z3O;0~({@+yw(C0xQ7CqKsc2_-IudPj2uSI3E zSrKL6!^Cp7y-Ay)^{j3EI@OOgiyKl;=0wOK-jqwnFmIq(6hDU~O+xExirHVB- zj*YEbLGRm&)1iyT+DWs_ZR67*lcM>x+xwy{v7Rsb0w2C8?2KhCSUfzFedrNnH(PKu zhe%#BRY@+)#uQz&YzHsi^mqoCP1~~aVQlQpfIk;r#KtdKo6^{3J%agFZhWhtrq^!l ztozD`4sd2Ydv(~4QL)B|TCU$j+oqkK2ammmW0TL(i|kMhu8d(ogxMImVpET<=J=3* zT!4XniVGLDI&t3Ka0KkI|HkrL5fex5SMs{G>YPT>BqMZOJhJ(vQ2(vBCg@Yk^iq6g z6N^8`WV{4cug_I!nITg34oYjIr^nK`Z!zAN)UP==zV|o?=gtmKjVDUXz?9aFxOG*! z@IM?PCo6++DhPk|Pdm0nDBWbPPWRu$hqUaSKm6RR_zdZb*XQ$?6n=OI$>&c zjNCKBBkGh}7Drc1=l+0V%#FnY7-hq}SMxPf0Oa`Zm{}00}+29yO!qtzVAk zHtP`sJq3W*=R_FzKtl|EKjuF$wf=T~kTDMShH}6ew^_aoKxoV{ceLtG+}=58=Bpkj zkgPyHPn-i>XP^sNN7|j)o3fKAa5f@f_dZR%J2o7fa#{x0*{9lW8^L9<`z)dv#mii{nNBx=xU=bs1vUv$5?XRl_`tM0D8Whc zdu9(~SQ~~<6~NZuYQ`T(0OY5SuF>U5E97MkiZr}EgWpsyoS+%y17d;K*nQWjUIghv@jp0vS@O;Zh_ z?1JM5vsn&jV84JHL!F{WlJCnGbsdHxP7$_ZUC4i6XfoFz<%?O$1vOY_=QFPEQg&9s zU}vk&A|C>s{7i``fheig6pji%m{H|lfl+}#5<0mygWzkXD4z7Ph6oRNLc5w*EAhyZ z!_hQQr4_~UZ-YfkBYrtG4m~Bo!`tLbF~e80C}zazuxj63Eh*_v47#3ggttCuAb%r` zfe+xGPpmH~t8m1`Ng;y70i>JbXb%1bo|vEcVWaz0=sGQS_H%nj19o~ihPw_%TQy6e z+57<<=6)%l`}pC_`lUQZI+B(=RdtE20Of?jx~DR#>$~Rzo%}ta8TWiYJ1U_2gP}59 zy?l9~~`$t9d`&BpLqbym-mR6Q(_@gHTItCOS*k z!ujg@yY|vmUf~;?!!XjV#C8)TRBxaWVdoD0{Z>&%d6|p_cfYXxW?I?#B0sDN&`@aq zL)TEQcbbr5V{GT=Y^cdo1^WuA+prHZBT=GN8h{f#l_5JLq;HeQuP0Jb;gRmcg57n==$knS zuzJm99W;jPy^EBtPIHPjYh^;^4=jgTK2r?p*(b3m>3z=CPLB{j8tPJ&#a#COfzdvu zib&f4W>u~-CTY_SF?~GLn>MV3Yar2vHP%Ea?p@)?*ikP=kUMkVwxY_|nYyIN7n*&M zGYa>8Z=34Qs}Wc z-0nRXM>Lyle&}N%KJ(VhW&JkplosC7+n*3gGVE0fqt`z$t#0F)FfF{~YGD{$)3$7^ zbJ{(a;00Z7Lf%~-bhJ6313qs=Jnu@<103dO9dQa1wPokee)W_>;!#n;s8EMeUn*Kg zcyS{;V6ojPJ6>L^4;9F~ZMs}*KVe?GmklF{3qSfPoVVg9I_m1zCeH-z$EHq4hwc!{ zcZP{L;{qG&r&3EROVM-E1%Bby&()$~^B}m950-vJe2V1GB5#c{`k5(iUF=E43=Im` z?rK0+r+n%k_O!RzDywL>^=P;q7DskDf zO3nlO{M$1cjD${Ejd8_P>=%d~1kN=@Pqy6v9lf36w<$Fm%hUY$9~!_|=eqWbomw?Oo;m;>P1{W0Xj@P2 zqjXr3yaAEp5SeN0vVW^xMMo}+U5@$MG@RJf$)Mg`Iu!qhZY9R8BJ3Hh4tJp*E$Ge5 z`y-jLx0V12Bi2;Rcb;Fpmg=|L!{;a&BuqVUzG3|&(5(pxcM|n|CWEfTm!5wg0AUr)-9%P~V|^$!azO3%ACy&R0<$ zW1lu@6^0-U)lG(;dmI)e0IA5Lt_I22f@k>fhou;vVjCu-D~6mbIcH>3dwV8m)F%3f zJ1I*b7$8kE!G(lNlOPl=6BU^yOzyV@#?wh;BA`&py^Bu^{R%?pRF<^m&auNuskPY+g%=OE!CqaG7ZFDhSDRuT@L@#6%zlc?lP2+wi|m%U1XWe*2-Zb_BY zeDPfxW;|U#Z!fY7Vk52^n6)xivCvgG1Epr^aIb(2OVuu|Td6g!*q_LfMI;RE9IERD z9;2pLE35=laAuVgY8m8|eY6V1g)ycRAk!9#QyKCxupuJP>csD_dbsf!eAkZR?b>Si ziU(QDB644PI%cKf-r_p>#-c>oihYi^>Hz6XZj_buDr30_xIZs6P=ggZx*XXh&HR!$ zn$;DX_mqnhMzY+txsNkChB%bEznMXN?ksMZ;qJz*HfkI~XG#Za$1>vP-y@{4WyoVy z?R~YGc$+DivGar0xj=Q2c=jzj6>+otOXRsg|E@__X1ul2eXfvyYk<}$_ZASF=k7-< z^`V_@^Hqei1ih4ZB<`qq%-jBwCMXa*nqXq);1*$H!6_kr6;M<)XB zIRV}nySQU=@cMROI><=*TF*exGx#*%v9&*7t$=Wa(As## z0`9#xc*JZh3H1%{1p+s<)@>| z7QYj(iY$(0SC)5uE$I^BZPo4|VYR%llM{1N4QOtfI2fI9o_MBoOD)z|zV4+JZIJ!A$OFc{bIEJZioH>T^XFXxaxI z-vi{+xLezL%*HTJD}^vFWX(J>A!2T#1;YHRPRM?y@hxgzEW=O@A( zcb-5S!MEmRSf0BXQ1hb3@Ziw$9FSzVTX{hKgXW1(_nSoPZi^T{uPgaXR;L1)vE)FrXQl1ZSX^dd_jH*}M*GjVk@elRZdWtZW4 zBE?vazTw>=Jtyhw#C9*E+nc(DpMzXB&QaE`7OW3K9~t!^E8{_VX}nc zIPnBf(Yg8^sg1|7I$0Dwk`MD^t<+^%SOkq6@U24|G>gX>r4Bt)?07W97U|1`C!;tw zeTva66P(ygINZ|0?~rk-g0f`{l~*UT7hi~@-zMAQ@AJgEQ;%cg382KiNd_ybDr9v! zx0zW_w}B|qCiBZy?oP$s0I))==8Y0{<{R>U<>XdEpJY6%P+Rekyg&;Fq=E?2$7le1sjG>CY>CV3~b?A7jY<^*;gRHnpH{v?M^z)7SU3(+K0CHE1y9nLSCVoe0$=LgJwgM$C#4fL-pSAKL@3 z$j(FFZT!y#SL_wbhsS?lk_|>Z^R0-lq4ueG=Y_=H+9ikYGhDVbku}ZbhT3fU0VZyD zItlsaD?iJ?lGfny-*3fK%*?9>jQuB?R+lMATZ9up^-jOr z^f9kQP^l4vQ)^wJN>~zG0PY`{DR0?PA$_C4n_DtnCtlu}5#hU6`XQV(oBZGAX{Oj+cpbczU@sZ_bQ&DV;2$ia@!1&Ec3?>=NEeb?xSg!RXWu z@HkImc%6rxWB2NSXOtu=cV*~ZXdBE+npBK?!r&?7=b9M9RLLKhX}sqzSQar(12e(L z)th@mxl6`1y=&0)TP!2?791PH-wq@-gP#wolLXs!4M-1o0|Mi@)6{WIKM`V5e8Vc) z;2p;r8Ak(^4pF+--@=#1Md6c;_UeEXvHy25 z5M<^Vyp{9f_nHOaA3DEE0BLp+XRA%dEmWor`)m|mr5u!gZ&1ADy&c0GiMj0S%o2G2 z`bCK4W4Q!>fjilwXkwvoJ+P3cg4Ctry^${&8$&~E6=s#XqnXa8q^RrM2scq+PZb?j(uEsTaSY+4nO#2H5V@z_rZwP*jrMo87|#7}{6WJ} z%xl18w->9JY~o5g%2dOuq>~4VX}CrdnxiX0II8Q!mA_Ji#sS8(fl*`vK7gn@fY{o| zImBnkal#NBJrlU<$=5OCnSUfaTj+UvB)N}v)==!`ZNM{{R7h+2CX)Ui77_X~9vmM7 z&1{|up3$)rHbH$XY#N7!fsaR%*~Sd!xAy)&_`K1xuMXAw&SScxa(U$s4vwBXO*W^5 zO?@ERNLJ&?zgi1YWwLbwM`Vp3l7q%OcHS~5FVgFhT%%3&obZg}I%hBe{FK#<48y^|^x4Yt znYD}Y+>y(*=kZRrKFOM#te&3k4*P1<(qJw8V)+MVh4G6_}5KLmlEa}jCelg$Q7`5D0enxWFVZjsE|@4tqXzX99K;98Jwy3Lb#0`ljcKk zza&e$%6klc$tYhyd;HgH->1o zX>_pOq-1&W#;5Aa0D@#w0GTSNHmT%apBTS2S3fdVuLc`A+BeJk$c;Z)>k<5{Z`5Dq zbT>0m>>oSKGhLqsfkoI=SDWbg~5f9!)blYIBPdTIqy^4idwR9;CS zufq3(^Vas_1njQ6<=zO7)UfP$@1G_xX|ufIHcXlkEZ=S}Zpz9~1$f)1+87we0bGUq zlq8(ZJjlEZjI3@|o_nx%M24U7>2j6nwpSb*x3ufjxOx`4dQ_E^40FwjJODqcoso{c z(%&*Yf-ZSq?($|IgR&A`orBIoZ+djGDS zw}m`D`kYZGGNV`DiN?O7wpJGe=Lw1;N_B22y*}bMfV!FE#8&|1g`if;UGBtI4N?(r zoU1V-oRfC;tE>fAG_A356%ISt*SC)NUX{E$Ud~Mw2p_+Xzge$hnNl$txyxI@oLSlco@;I&unK;j_%EPI=ZD^$7?xj#zUS;#gluk zl{oVflyOdySQ?~FuqM4LEy#E2OQ)fS8S`g-$=o1%&tV`#60O8M;CrmO#Gq&fyea%$ z=fpkGWny{bnIBapk!fOPy2*BugkJqI=Qsp6*3+@1h-RbMzbx(Tw0)aT+92P zUt5n0j*Q4V+6J?m8%BcM(;N0E>J%`8?N?aw7^-z4-fsOiWBi20G9D$r(KkVxa4LQd z0^XiAt&lq6K}V1s61>+}NB@unx4;xp>3%#?aNBUcbNNvcOUpoZrVwg$XSmxW9TzG* zTCi$c@MUC2V^>RC|7Xi%qkd079MvC~k7JRtUp*Vhh)1pILsi``l#jl%3H>hf{6&x- zu+VvrHY0v){ETQvc~chz*PP_9F9{18>t!qYShKgCG20LPZ#EFS|3BQttKxreX#d@I z|7V33{P^FL^MCo0{0UbRKMxEc__ESs22&M{fuDMwO(zejuq5r8UMaBCdL*CpO`fqX z|6M@AxZ71ul-*$0K4~wj@?211z@pzke>(aDz}y;>`D52%cR5+55(!`;WOt2JQO^`W z_Mr`^u*!lLw|{O~N%USB(##XjG(?hLs~0NZ!-CG6obJ~e#hEb)0y`+t#O-U?JN@c9 zAe>jwLz{R>3`3xBT=4`aPG`Khz>ykKJRb+7i2{1=(8hd zefmh;bdfwSAm+kzrsSJJ!Q{M5Lbx!E*+<^!%kLG>ji z`S|=_C4UeX8(i_JwzI-ns1=bGJn75>j5DfRhWhyhApbmLsDKnZ`*s0^XQi$98pMBQ zHl>c6LxNn8^sDt+N!Rnb0{lyMq)cW4Wl2`N4!yz5+a}_sU6uW>pyE{mGcVh@reg-n z#b4v-J41FYd76RbO9c7Nkj*=fnMcpkMxk*0{uJzz^)-Vi%eV`^eFZZTY$}F|hOJLn z%c27PePR!C!c)yTsKRglak=mfzN_oLr`WT6lJdLn&6=bPG6SF7y?&{eH1+%gBLM}u zZjXeoUQB1j9{l`X%$_^`_$#quYldc{;$0@2F?e>jx{6*^^Pvv$+(duTB)}as2brc-Z6X zB9om>pO8K>N-?)jk?q6_zK6r7ra_y(j1OkpHlCG3w4vZ47`Un-^Dd|;4z2;78yGvT zdOs<=R9D-9;NoQHMG-$nAm~dMmYsWp%;P_6$`=-qsyRGf*;8EXub;{FuTXB?WgflQ z3;m0&*B^CNP3`m}#yN(`m+@&)r&M4;SMw@84y$S6KQQ+7D=z2onQ!VuVMaX@tNLwJ z#G~v0Aa?(hV<^!5&+g3*0_(Wm3m45Pnn2Ji=hM?X_@@a1L7L*r`(ib z2*HuD&MXJ|@U2O>!@>AcJHaJZY1uhcV?Q@}|4Vdq1Qy8ljDl^h)fd?OkOJ9lR?(3Wa%g<#DAXvzt=&E& zpftmfyx&m%_SuC!ijWR-{9PSB8kbl~!qc0!PL%;ymdKj?j8u>z-HGSX?bC<9t*)3& zhdgEGKsx)b4OzLloV&P_W__A^P4m9Y@UA9_A`26J-)^7mF=w1yag(d{^6hEQWfkz( zdbLPeZ5c{U`n{x;gNkoV24t%ST~ao~Zv4I{S$RcO5>9)Qc?K;Bf#;ryEn3yMc(vjw zI|e2OEuEz{s#Axk&_p!iS-*aKDA@S}v)*;_{e42*IpWdoof+5te=LD)t}eZoC>)dN zA(Bf<1D}yqJGs)D#?c<_(*X$Du;veDd{kv}gW1Zo>}_I{(C#+EJtt|oz${tR&YpmG z51#1jy?S}(&HTvuy#zzob<)KBs7<~CRlV@l7@2czWM^)Hf2g*BT%CAngMeSL``msWms-9JjX3GS%K?or%_h7rWR_KPy zv`quryOb)%0F+@R-$?$kX70KD>uf?g;(xEE9Vw)m4KxX;7_km3ur5njaMXG)*M7v*PR{^PH1GsxQ z#Y+ev;|cPKCb8)6^x<0bCy)&UWmzNu0?+Z(Z~QiVH47D3OT2WEunalT-wAi#y94Os zsTzX0Wqp0zIXiLGfJZGMIG`%S07mi{JpxT{u@f`BLM+1}R}ur)z5d(P4ON$Zwjo4H zG-`ZVSQOkLI_3)QH(t33)4yydWH9u@uOwP)RhDYU*yuQnFev%Ty@w)6YI>LgwOyko6bleJ{{d_zmr|U zsjuE`X<)6{Y99M1?5GQ&FbLDWL5T!hAHZ@ov*MMk9~rEU70T^wvH{g6z9!MOmhQ`@ z?}0wW2K9l=80Is zspI+i-Nf?vK`rp2E=Nl{Mf;v!=uoF*4Ni_?CP{WP*H07#{?iit#9Hq-w48lZHomP& zR0se8VK^#lCB_UY@9Dlsq@L01iENB6Djwi~=RL5v=83LGthAITde`=NLX()6b|IIw zn6!n2bYfjRUsrbHJXYM*%-~lOtN^K#`J(7M&0URt!4hE@%F=s7=b43Vjo|>Y*vJc% zDc)VogTTq--HzV=bW^vS8}t^In%wD_0C&DRM0nRHe(?xR@acM3WS+Fxwe$~goujE_ zk(}+Y^rdI#X>nz%( z5dkw&0z}-`2Ytp2-rn%~vo(mRq`j_K7hwA&Ycf2ac^|ZW`Acl8sum@BwwyT6u)ukx zDp0LfP~40iw;_cuVE}MT+K_2kZ>MeO;|~*fqxJDR{>2%MDP9e<} znK@R(2Lr3zja2jZe>?SIH~61K_LtUAa-73y7T^N}rqIoqK)^!Hiu%Vv3g8buLAb!= zss8?WS}U*BwADg`W0(@sQ!nBBWgmneBc4c+7fWZoBXNTo^jJP+)Qo!yxY6<@uNg63j7{SvY*z}Z4n6u0(a=wBr-HI#&$ z88n-qM&wd4+Yfv_OEwXx2TKNr#`%tvRH278K$kA}_rgqXMJec8pR`wQyQ3}PnN=!I zQr48WRi`pRV(3K)W15le1O}iIu4dls&fxC99Z>&6BR{ve)FuWJi)%6NE5xe+8syh3 zN*=sH!UjyFE75Pt!I)Nh`x1oXB8;nb6~XU}NaA3IOSn-)5?5}l6TZhDlx_C=UADVW zDOpw`lyVdqV#fcAx`hPoNXhXN_B(>5@~`^lvbv#>R`Anbzf zAF!i^Y5m0R^6iBGP40T3lk=)fHGNy4y5o%oFQ{scoNQ5OH3vk~>6d@o4@Ae28tFb_`KZupqxBDHh zB4Z42q0=Ep=iaIXI<%oM($9XA0__>SCCtjGY(Cn^{{vGnI#6}`8e_!;scTG^%Y5s4 zp@IFnyb=uG<7D=ZQ#0*RcMa(HeGxy-Hr%x7!(?@fvO@Z4; zqXRDEdPp-$Oi`k>G53(6dZx3j+?3_p?&?RiDh1phjh5k|*?R?Gg{&eDwq_eje$2%6 z8=_xLVj2;1!x1m3dG?*fBrqX6A8`X!BNx`5GMf%Ux<(KB_eSKF6Uay$I<{z)DR?YT zZQJ|$i_Lw%zMbV7Y)01HwYOAMfTh*K9eTg<v5S6N8!G7yMoS_XXKdR**`Zt`#`E z2Y8rZ5?-T^ACDcVc%l7xWY8co%6dq(0?)VSN>sPU^lsa@S8vTm+I*tHCLsxoXnC^J zxX*65+CUPlD8;Q$j{%pAMCli4Rw@Y1y_iMLZ~pXLa6R3*aCm(AA7|E3l@sc`{5E?+ z%>3C%M83*+;a26(P*UoWqbvQ$i5$$D1d>(|O~>#ux@ zjLYi!Q#sLV8Z9A;q8YF8ESe0omPP+pQa8_wad16L+epEC!?}(>xa1~lC8@7~R6Qxgr zGQCG3o^=9EU(@i{y9{gX|%fDH?38Fm9;LkW;S>-1{ zWwKs9+NC)6p48i`6ZAxg9MgRynBZGMWC#&~u@SBfbIp_EUD_@Tb8|a1=b8OV`MKd#lePV9=Rzh;tAAkX_xRFIi)BA;`FNuhM}-W>KuX8l*3o3L^_;6D*Zvl&uTEe-^9eD&|dk2Wj1D-=~T^w&FOnMADjv4zZ8q zZ~!)%0JOp_>MliJ|F@^b{~ISu*S>4w)VftmO+69lP^QK~aLy*sV|rG{SeSYTq&;2s zi8U%QXTl!sLm!KNH&rqRQUENR>O(2Hyj2&$TTAwL9z5?h-cdGTJh z0a5m$R{HpXJKKL?o~=9ceXWd7w8YyUBi*LVghgF(z$X3=P9D#5HT!qvB*%0X#xTsN_$KRM;Q=T7Pvrew9>Eo6eLr{{&pq)U?()go3s-Du$R!3u~olN|HFdtyEQdjlqJ#p3s19| zrQ0oI?xYhsu#DiP13cpg1Hw@eb}`(2+?$NhN$xLWDEYIF-p_|)#>9^S2AFAF5`=~4o(j=7;JdpLQ|3=ncUB3Yqqr}K1 zTlze^^T2={OOl^8!wjLcZT8Vu6KjGT5r5`vDgoP%f6n;F1rZhHp)b18+lunRx;ec_{}+G z?+}wCvuj(>uL0StS(yQfdP#Sxn1s-qQh_W-@{`}Q#i#`6Nm0IKxBLN*oh|m)`uyv5 z{y#%K*&lc*)owm&T@A-3D^QBBm_6GlP@dMm@_bJ6Uikwu~nP@)E+iotD_xca!fO2d!D>+Q&&@ z`Eo3DN_L?#X7I&dU1a2G!5tzHe3F&e7zC}A@VjiU#;li#!ZWC@@k7Tc(S_2O!8d<( zF@73`MimnJ>m+r%lO}F=s0IB<>Gg4i!YU9-?ccTjNo_^&*hz zwSRPaID5+dub)ub|7!J(=-)#q-IJx^ZC$paFLXaVT5d`2SgmUe)gZn_@;%Lytob`d z<8L2K|6)UM`+smzx>w`c`#*Sv^6<}YUrhcdiTGM7O}x}7dt{0;B$9Av{jr8%g z=k-hWO?@i?)$j4qy}QD_7yUabOo{oUUx&U;uZ<1RH}zKT#L>@fH2%PB^f*ht`}qaO z?g={r8k$1-Op{3R2gc9p^&z<7Skg`~c<}m~-z28m%y7gv(H7{JPiJRtq_EZ?rU2KX zUb^=Zns{D~+2(Xb`}dt3uMYpEY-6x*!Y0u=m`_pzoiVUtYbK2bMrYwY0+aOs%e=tD1oG_!2|5R9-WWRL)eTHevG^+JJ7s8EXpYK zlYUWIl33K|eq2oH7SeWG9rwP(1ays<{AdqUTvMpe!A;fl8bvCA1$VN?6r=Fz`_CFnOu$XuVUbSGDQA(H`ij%5hX1i>fwpCypjH~iM+k3iEu7o9FK5vm9#Ud|KpHN(#3Ya-c$&+b>FJ>45R zi7R}3nnPxhV{d;oS&>2m;zn6QK$BJ&C#Su3-hnP-6{n4jzMr|fgt*=M?5Mq&=CY2V z@iTSM@FM*BJ(s3U{Vt*7OS@HBwwr5bdspjsmYatxnWGlOAhGRwu%o?>Ur4vx!6>vv|p)z z*T=RXDzPrV7o>K(S|Gwfdlh>^B<55F*ci;0Eo1=!eiC11P|PGecHx)ztK zd){_Uyi{&!!$r4N17O9@h+IkApkeCNW?E!7Rl~PA_USF7;<$y7K5rn0KCS_MI$y-n z3ju+ti*su2@MGXOZ_IReubHNGjLyQy1_47##%WyE9dbas4GCTr+?)LM_pu;EL4$Lq zjYLa=yyi7NIKx$pz+2C`a5Xi}UPLdBHd{5s*~Ah)eO-%HVh|Zy6ZoC()jB^Tem^vv zZV?(z_nO(qK7PP$Mn1jCB@8BPS6k>UVczq_gPHO#-ew{b!F0I~`M6~(PIq{+H*Zn0 zCFkY)#X-)df0>oywy4QClXY#Fwm}p^5ocqr{Ay9#+nM zy4GkS0~I?mQCky(<@qwWNfZxFg^5qVAyC-JXUgVuWvb)U-bdVxaKDYSo?>z$!)*xd z!-!hT@}t;0ALXmQXw)UmEF(4RYH?)adRBscCcUb!N7>=1+08J*k2JOGw@q|1r!eoa zPa6+(;=okER{ycIipV5dX{r(kJ5gD;@^~ewxmo8?oS-R%z`(j??4g}?sc=ODZ!LF* zMB++E5|dH)_YGUHKO%3_Qnx5##NznHT{>wsCMFt!bRAv{>VUfE&EqJGKV7s;|8EoX zNcGFIqT5!sCo$A8rA(~hzAExzzQ#vcBU&uhA0N7^$yH^roc!6xyPu$8lTTcc*rSWh z($~#e45Fl6KRj5`3aZP!c0aFy;~%S4a(K<03C5};uzEt+P9C$_NOESR!s)qf86JMY z>YsNlEf@1wQjTQye3ANK*n0xhkeponxyF5oJ^w-{>u)zd7m+V!D^g2FGUXX#b@C6q z3~=tBaYM*4qIu^8Lyji5+Lm5eXPB6RTCCmk%Z!%G)7pmgMG2PER-jM4z0{TeY-qa6yiY z@b7A?4&`UM9r;;AI~=(qCT}Od>Q$1siW!@I zn1sXf>{_H2>1a1C0Z$W_2zU}tc*N6?PiW835szuDmSNx#gdfZZ_e9eodEi8G6OvqI zFF{;QF$@fQQZX)%P`ko1M$fm54*R`f-C2{J?2)+8hk zB9bAc1q-_LZx~}F5sVa4x3&82UfTO#P2nYpF)&ZyrZbTby3JTIhv}{oS&?h7>%|I?3f4=3K6JyvGG-N4j%EN`;S3d2GPA=!>Tx(mN+2(GLX z@78=eMD_zsR_jyj+Zl_4qdUepAEd!!n0PXw>wQO1ucEdn!ASq-Bw8atd= zJQ}8adHBMzMhrgy7=4oX+77L9s76XIB9+VdkPC+&Jb*Bz-qC^fP>9Y{#qNke*OR}3 z(>#f~XV#It1kj?7`~$=3n1?26SlORc!G)1?5W`Y8S8EXB5Fx5GwZ?(nS6&joVj&0A z$AfJalg5MkLJrE(Uq=t(EX)bAoJ@+*(bqD1&OSHIa=d`s?Wt&FRJ$nx*oGez%5W|+jsj}RH9%n3{ zw3$?tEDK~Es-L^&s|lI2ZkQoeJ5AqN`pidE*bsdvBJiY)>*!JlG$^)r$JrRt)S4<$ znCY&z&)mA}>tOY>KKvu7C+*Ay>JK}2S@#mV8l12#COVr{Yj^vADfXcG)5$+(+~>|M z1x{V+)Hx>rVy90kru{pQ;nnBxHyOPk<)XU zhyZX-Qbaz#|6Df%{F*}V$f6eBl%#9wq>t3X!PQBgt7nk+FKHrU z{S}L%JIS0EQ*A*fQGzd^PB<9oV=@sxt{=aD9GDu`SaH7llxAx}Ec~%>wWlFr7YCDT zuRK$muh{2Zv#{MteTSB){KDDFB?;@v67r=C(%js3rs?D3di^D3$0g?Dk9RQKw@-JYfy=|Se&!C*6Z+JIlIX@=t?x~7nIs3N;%@#R0jeX^m3{!o-Pc#M z55|F&$5}3d?t;^H#WgLn0_HZew_@KYEYYiUT%y|jEI)N)j%94axK%1IJ9>S!B~UwdxW-w4VCREov&@130fn_& zse0#A6d>jbI-yC>V2Q3VjY75aVbbj-**}tsy!F* z4jV~zL=Z_;55>xxvkc9rNkj@m458v*45hxUB!b3aM1T)ao+uYXmk&A` zwaLCeCEec(PaV3}zssMZs~u2Tt@gwwrg8`HH*wY%h%8sX_B{3Y{bT9x$Ho(aMW!L; zjcPnN<`4Xpv6x5lBEgzAvrtss$WzM_53BO-@xUc`M z=Z-5&BNy7o(xs8aiE$HQu{Bfsz<`)=rvn<-Y645yHxZU;;~uu8uApXg^NC#x46ilK z#Z!UlE#q4-;1jKR5SM+Xvqff6p9|`4Zf9b`+U;|Uv*nVpKd&{<`Z{lhy52dd zso@0ZBYka=ufFB!HTh>vZ`ElcY3p3>yzU1v033;ouJ*1vOhk0_xo)I+?7`mkJP_ud`Cz7Nt^lb zyOU3^PnS)NlI8WmN1b>_1-?ucWUoq{yO?6Av%|u>bnRgFYJ+x$(Sxcres#a>1~uOy z+SF9?B?pyDzNz=QC(7eA$+efJ^wd^*Gpi$ppS-U9?u9;J6t?$ zd~9qyOf+;1OfqsbED9D@ASD1Kw@51dM$6nH5}TP#+tMR!j*4Aq;Xp)IUenz(BBfAN z$1A)^!74PlQ8y~Jps4usQd&dv|1b9)#cRy}(8gs4DIk>d3l(1^N*b)}Y#f6c#f;d3 zjGJ5}&y~6{EqHj-p*Y{{Fm^h>p?)v=7cB)&>T(sP-suq;*xXt)OE2F7X6q-naBda}SI++aZ;HKP|n#6{d@gN2_ zmv(k>8P#8=^jI=Pd$mhWzeKK`_93hZ`e*7o-g9d78Y#DqRIsJW^U|(Zny4U+lfb!( z0R8-ddeOv&-sq_gqm;&9aPHrn*B&W?M5W@aVr!k`dZT6>4mZ7W-qEBa>0Nr=H{xuuJy2OlIR*fvvRsN9a!?ou3*2 zhJe_i(+cZHhK&}neq@5DFXL0P2?>i8Me%tFog>x3!6(N?bH7VRU+wG2U5|m}RsWdT zrj0Lh>n_#pA>3mN9)BlpcSf;N19`qwTdn2?TL$luk<>}OWgT`qe)y#syLnsN&1Cvd zW~7@G#jC>9qX5_NhuA}#Esp;%5;Lpz|qsWROKs{<9 zG1;49n=9wTuOq*b^g(Mv)7=WiiO;fLj4w3wn4Ud}O7=J?5(d}I1rzWOaVTATxfaLF zJ*g5GgOk#A|5q+^Q&XqrV&Al!#gbF=OI(ML z%NbG%ZUz3D{*>svs9iOj^3WD{f6P^yAFrdzwd9259UpJ5}nD*X;M$oJQ(X z-*cl6_@5aA)r*C(-xZQDY7uGt4Vv9y-fSd6l+(~vnF-4KB%V?C zlaLU?`_K{?8z>7g3zzINhJc|o+!aKQ`jTH0gks+cn`cbqO|?pYJ(}^&O;&X2CFe1% z_E~Y!FkWH$Iz%K#L;Eq!#$8&MdDqMpww<^u!ce=i~AH*0EO;`ofT4ShnPq7wbj;sy)F$6It>Xf-k zL^gk)Ob?*iuO(<~lMhKPUGYU?8O|T}l`R!iUJQ9ujRTL4wyeSoz64)VT9u-nX!`Qi zRM*K4Xj&mPTs3CQsaGV(JWti3q4$u#L<_F@XWE{r5^_f*>FJoJEq_fPfKo zYFt(&X0BF=rph9$Wa@CL)F=ns9w+Ux^x9QI4**X`iea-7l362x$&bH>)pbK+`qSp!WOACM}JZZ|I)4rpK}g{mnPvR|z%H z6vz`9Z`_)Htkpe8(f3#0pD%kSn4X7si=Oqx7OcHGEn^XCheONef^P*X;-_2v#13nr zx7Y?!zpe86G|G4EOMOP}^&3c0%~ppPJ7eJ`Vx}cSfcRdt+j0hRai@nCQdO95 zL(YKAedY;DyRyC|hfu9}bX`7vq=Te0m{?VeAa;+@R9&}Q-c!E-;3)p-zhJ{#U{c|x0! zxdK9qcZCP-mT!YR_ksVA&|UeSt2m@C!O8Lc?$x*07%V%j0rbbd4@UzO%WdDflmDTr z%yFJN*lJE#rjk*bVdmBG2mDWrL8^uHRIlZwooFc@gx0`+Q=TfSh=&XPhy?z5CfKP1 zJe^!MjVb+y+dgj4WL3Z8pVC5^7Rz;Cz4kTThb7G#pWiy?@+@J(?rz}R>+WT9eX_i`Qki%$c>g=XS7 zzWO-3bMX8*G9zYX?FsXDLq1KWrS*Iq^W2CbgRh-2QJ|Q2ASg#0#XnGviCawAe`q}c zJ26DrQLsc{`|;4){?koO=OEP?QaCa2a5WecxX$o6^XZ>)Y4%WHP8)g7*~6{E*58Z9 zsST&`|3h-_zLbHFZ_Jn&`v2tpav8pL_{~WHr;HvPdKHzi{YbLlV%mMF0nSOfGpHw# zV9S})|6|NFbbUf`K@;oaF&{w9`@vvlJrew_)@AkTpU5FVz-;y{(MNfdYoU4B+}-r( z+>X&Bu%^zttj27#`(gq)tpJ1Mo$pQ>dc~@jp?K8j9zRH;Y_|&>M{EaQly8HJ1 z%dCWk69bPgV+CK~D#)t8wV7_0FE0KW1-&IDeb?$nW_qXXu;2IJ7t6yqFOjXvt){On zi0e4hT=M$0Xb@OBYR8X0y;l51h`^M8joQL@c&DgqztBmKRH%DC>#HBItcDpkL;cM$ zV^!UF^mg~*wfwEJ?SLxZ${A-H)MqKNG%?I_8Ot+MOMj;~;^)t8d-O>s>*}jX;t*>Q z3(D%#;LTda08`|pp%+Ir%=IPjq2IN%d()r1`{A{Es>IJ(di}(o^q`rnTL=ck;pdLKK7?os+T7i4J*k1BRXJL<$0?cj zc&8zsEWLX=uSYelOCLYmiZu!rUKuZS$&NHFSip_+z`W0S>WGxq zF%EjGfb`!-@vXV{ea+{^k)~Q7lmyl!M&Ger^<525? zGDi8HepIIm(H&sas+W{go%ZG!b+#+7EVgtEA2n*hXt3Pquu}EA(b>rmjs;El>M5hi zT>Mt0QF!o8*}qkwV7;U@j}u+nRFh+KEbi6sSQhhdUKu9qX5O!4ooDs(&7F2#iG0cX z|IZ-et0-r(X=RD8ne4?0adug0(W8#2#!`SwjPr0pR>M(dH%Nbuy|jvCYczw!;b!7k zEWOQ^%ojfE5B~b+=Rf1%XY40wo0cwQ6MLgfCeP_Vm_7*)xA{&imbl2{^Tbpn^g&sS zxK;B1rcjytDXgyDoiHxw9>( zd5}Wb7UW!Lok9h%!4AcB$EPQ<1*JZfKIbXiSJYO<3NuQ^AN|?SzxOpn`zkN$EIniH zzLC1VHWt$>DjYo70!zTxp8{%oc5(k19qF_!vUy}IsQytQ2@ zS&2T>=Gy&{-@7KkNxz#8?5eIXSrDX-E$bLR8@&3nCZB5c>C7Tnt~f;Em-bxKufS;= z*0=7y1Nm%Y$0i9EW^tKtamFbm;01J0UKF=qXIszy5^xB*Q|yvoe?~EHujvuICNNZO5~7B?`tZ~Q~;WyJV2u!UJk$gMcvE} zi1G!mj=eb@%$@dq&9y?QDQyIV4isJ`$D9|2OZ&d$T7h6Pn~x}^n2QIG&A?nvB3*AD z!cL1&hZAJh;L{0XkWTstv_y@)MW94#S@FK=BQ-jlefZ+T(s}gaxuvop?DN8t=#x_e z4t#T5aQmEu$LBqjLojMfE4oGSt_{qlSm3T^Aib@%jxDOt7>#U%g?O544$D#gwO!oW zxx`b{tJSXE5bJ|)z8#B|QL|8zC__e=Pdc-eFum-R4Al7w$yR6-bqxeZr}?pik39@4 zc~q8W7jnWay(ib!sr5+8@@&Rz&EpBJY_<2q*o{lf$wW$EgF@bvCi>^K>^6Gc^E?u& zfeHq+-VQcs0+!FsoaslBu?x5WA;_$XpY6x zR&I)q*zw8`OsTBb@^JCXs^i=Y5mxe4^@VUqIT?t6z{{b=>O*Nw<+Q71(I!(BMo$jB z^JRs^PXOh+h=Ii`n+x1`TH-F^u*&ierRw(#jlNF97O1Y%`>6o<_k{T=rpbDM`osV2 zhIsE_NdZjl0PJ<7lFdHJ--b1$qmf{#uPmP?-ibbh1rDK0@q!ES-S;?B5SiXY3D zWadlX|F(H12(5D2ajTp!D8D{0z~zhaQ_pCV^H^PEi>bAhu6^Ym{TCD>LblvV^4^LIkU#Y)$Jt!> ztFITPQ%`zCgHBq$DDS?p0~z-=kQ-gI7UVK!CD---S)N_G0N% z7PH^rwFIJc>DugcBkkO@;MFIbzRUzgk!=i-t4A_3CyLE2Od- zP!cfveCp!Ok~X{OEGzv)_Qlmf(ZnAuvEXLfdb_8=ZC}T4VLi_3`f6q?9=i)d)7?sm zO=YQ0i6$Kdq-~vx@qc}!#L7c5N;a4gI?;Q4fd%Z;-ye5ZqL%w&NB%Wzh}M)o6B}=wrlF08qA7uk_75 z72^F)rZZE1k6}6_zC$~Y!I)%qVW(lxXS6*fK|FP1QL)KkQgMf}GqdScSiEwgB&cb& zlBp3Mhgd8Z_@Y!Bvf|cvytCTe-B>LQ+{(%um-$^wNm1jx(U@Q+N#rAHS*gIMn%twIpB|gK-W+0~MN< z-Hn(^xO688XJ_xvg%}4%qchW&AXS_b1KNQ~L17cGWtTL!w zqSl2=Qep})HMxRhpX=Z=2q`FUnl&gf)t37#^(}N1KDjA1R2-%omFp}Jg;9v8#;O`F zjnRzff*END#An8~+#;{#TBog8Z8ARnF^T!jBDx%hX1KrV6BS`BkHc2gQ1}qz_3NW1=o-80P7@_p+_)-A2;R@SeitTQs=G&j zAId14SY|}yqs5vR-V)mmTbQ(A!lNtzWoqVt1Vn(L24^O01Z$$uv~nYV3voKjm7Iqm4%;<5l)whwFP$=)UIrmLgTYjVXlLP8r<3ZO_7Nwn5KVF=m{tN8Zk%J9;a)vI#G0GjRNmeWyTW1Y ztB8)gpJz*_UxtX)QM9>npnh};x9xr7x$Zm2dVH}jv*q&$5xt;E4kM@uI%>(6J})K> z#6PUtxwU4{RC4}d1t+q&vXDw!_s`elAh>|4RoZv7QdP$nuc>$N_UNw%r!p1Np=^_l z&s76Kh+(6tY`H=jc^?8W*SxaW)3wG+SWSbUZe!?hIm2w9g>}3V(Mi#!sud2-)`OLR zXR_j8T9{26zw+5h#7d}M)y8rMY6wx0!f!e+JL!2Y>5@fe%rdvW_ zycI`TTwGbq%d1(9*@!!d)N>-+qxg{tQQ^~?#PU_NEe57+I9l1&dh^d10`w3ui+ z6heDEM+fdGLL6zJ@yh)i3KV*~>FK1?^Vk^a^}KPP-~=PnQS$NDi%a<3woh>hGU`kP ziH0Z?u05u439l1n{OsU+8_Qym0h!!*kwpws4O<0)fnTJ!G7Lf!Z2mk$4k)o=0^ecF z5Pr@ex{t!bSnOFcyFjQJtyyeOCRvG8GOcD=jrRo0BD|f2i0c#G*Hq`EKIFKD2R0na zV344$xkMYys!VNdQ&H7+_FE6zvxS=0R;>dIe zFlX;}z#|=eT1$P0czWrNvhmq8b=mB9A?D9mSE`IfbuklGSbYbyIUtAx zO`5|OZ-GdNI#vT%iTuh2s~W<1HA29}f6e(sVNP`%mSLzVjG@d9= z>@Q4E6nx9P-?IUTUz*jQ*gPs?PoeFVrb^5Z&l*}g*<$3KXQ#x0Lh|+}dMaqPRh*oc zOJg~Hi2z$1%2|KkW9seK!Bn(QVfzTR7IK}xL<^%&R|8!;(g~Df7AF<~E~7Q1;MMf2 zc}1E1R#$cHL|rajid#{{;g%d31QB4q*R5J!T8&Z2C&1JLt*ek({uS z$AB`f;AGR!F9Iz$C=g%{NwXzJ?j33*C(+^QRbGT6T! zLytX}ROf&FRbD3bV~5f^Uvy2=Bp<`7q@hHzG|5_G=TaBc)bHnf&o$;T8z&D8q06L3|lw; zhbB2#dt5jBJCAPMVYS7kmAv(N)goCNqfaf;UKqkGI4#oKbf9FzrGnl^Cr4;~XQLr5 zCfPD!sYn-pYO~1?6tMrsP89*-q=V@gm{B&AWOWARCocU^l-l8bg zxpeFF?3N*GDyp*Ei>m=mZ~HBYWJ!x2k9MW_g^hq~Jl$DR?Vp;8*_ARu*Ni!x51yTI z=8H`yf(tfXliTZ8ot3CP{_G6Wi>lqj1)I(a$y_JMyepx-i&HDF8?oy_JD;sB!d7oS za=i>}iS1W#G5Yg+6dQQ@D3#XK37pZQXSF8hIRC9PjvK>K$yu|qF4w_wy|}N=@f77n zp4)+Di==QqDn)?fDPc6O*e*QwvJdj5Qw-HuQ>x7@Ci6CvuS^w}$LKcHc}3$Zjt`H{ zQ^UXU(^qv8vP5tDMu^!$T6I2Nyr5-*pVUP4W_sPiZVYg?#z|0>HAROB0e@pjs;0;m-IELLtNIg%^7 z8d|9n64u|=X`~8Q;_F()U+BC-DppNSIE|}1)TgirNij26!tv?K_>+=<@ zx^g~CJcP6Jnm(|6lhU-#a%K5pC?)*L-EvON}46^=^ zJonNzovyIz7mln+!h*3iWaF)O)P<8@aw$4)W%G|n7;h2()kkJ*(P$tTUuH` zD~sKD|u5P=%UhCctW2 zvDH?L%S)m8oI?uzF_i)?Yec1UVoPTxao#daARe4hd~mPq@=;Bj4lSLbk&tFv>^nJK zF+aiedT#WpWVVKlPRYJvwdi`N)~cpBhs9X#Q+Ci9o13mFu#;=6lZH1#0hN2`q3XA({>70EDJx<3dVsLL$}8nb8g4dCCC6?V6{s4P3|M(>-nHg#V!+A- zuEG|tiq(W)s_5ru;iVi*kD$UXsd-6{a)fGRmInXPlQQW4h$DLSUL=E-Z}tyMKeBXv zu+_+=ht3J(_P6~oXC4l+7UkoM>kiCJ=Ya17>;IhOSM>YhtSI6pf+d>(Db^RH{^b#7 z0^!h?ByH+)kV(qd*GI2%%DmU; z?RtQyzRD3>`>%;(UQiA^CVjn*Dj=cJ+}moh4%ihQ%9Np0YDGKgQg@~-?KBcE%QZJT=>s0}y{_2;q1*mJme z$WA5xosut1xt3e4%`M2yLk$~z@hR(32v!6oiaf#VfB+wUw8y`Ly+_*rU=66Be^$9x zpR3_N>40~2XRBY$k|dmMHrDTJL~`r~&&)hpx$z%HJ|YbaoLp<&7lxV+pX=n}8GTp! zEwqZFGBl(W4bqrX@|jnsSFllPUE1qQtiJL-S%Ns=dwYyaG&C;es|{nvmE$d5Cn!cS z)mRHl8fcB9kw?Pk|5%P&&;|e=)i0X}cVeWoL0N0{ddjBtdZI=QbSBhL+Nj0#YolKL z=LR1H%=}Bzb@)ls7k~`TW*|lj_zK}FugVH7WH%2B(W1X;X^Xy^y}IJ%;~{*2&|63e zh3%)xB$h7Xd=YHj%*l?sYE}g(VtK?O6lOM2cYd-CX5*#qk`3Y3X%+X$Ekm`Li&Dw} z{U+yaBf}T!S_BZXgLl3hNC|U9VpWuNO1ji1fq!03_l5cIE61i2lm2xF>X%PTBsPWV zD}>gD&2RS9_p0Rq0to;;D6*t|YdRE5c(YEbvF|>+ERax{Wkau!@w=4QWHSojbuN($ z4z1nQbAb>k?*lV9;>rvb%r*a*q{Mc1)TFgZUK4vqvuOdo%hT|Ch+^@1Pl5gGX0u!~ zqs#8IereK_@O=|z4_6L}96FavrpQQPYbup$`pw5nk55&$=&9ROtKM}MQqR;=(W$|l}r7ve({iZg+Dv-Dp^GYWcZhDP9 z(KPA{w=~G!BW_KWht{UF%&E{8L5&3|n!eM_csH^#Zy)8to5U$GMfvfOD3tShouUmR zJDXnD;nOv2iODfGT~$LK1b&N8n5BL(l*%3(h>T;86)A(TxwB!*vkvr_PI6Y{%F)EX zqzQ#tH_8$$7}pHs2&Wu)DXPXk2TEg`SwA+WBPDkY(r<1q;O_H%e)y^NfNNTU+i-mXm+ zSext4eKRn+FAZu;k7K2Q+JqIQtCe#_kTU|}XEN4KoE>oJqE zGG3NM7Hu~=3WxCG9cc%o~=5wIIo9?bBwi44GM?)U z3faK>TOz78 zXuzyk3GI8hHoN_#!qmKVQi;Z50jOJ>V<+Jee62i{1GnydVAJNatC3-;>4>T(s)Rca zirJ{~zcL@q&h07zDMOCa=BuD*kq6tH@3U*%AVi+yS^$+hvlKE5BOunUt@0k==)A2b zF(n)DQE-?-iWcAwsHZh)OVXrNDpO7n&OTeZw>5hckuOY4clrHbc9~WfYPFaZ8?7PY z6GClz@)20|ElV+L(Z7{F{3p@`HBjN0fk9Sizt$VqHFA8*Z^Le?+~%NHY*QS4#xE|p z)^c*(T$a|pRqpbV=@h45gPpx2f3b6IEy)^bI- zXjeb<(-8)E;pG-X;BOYFUGf1#zyb(?zj_r+@Y8eBEQBOclK3#Ov0N2gflu zn#o*32?tbQDl@M8#Euld0kYM_PV+t=-@5y(K5w|;ttg&Jm)+K?!}Gz3g`jK1p51T~ z$>YeUhOKdB7~xAZ-ueFU%xDJpqn+FLH++|3JILrP56fz4J~H;$0&s#>Q+>_(&@wlh zDZlz>pCrjN#R~Bn`(`2d##+{;va5AL+!0-9))V&F*Plqs#g%G6*ZAWywN%!`bdd^| zJu_@~;m0Y3XRj=>Q3kI*md$rfG>KTGO|iKmc#8>qV7#N$S|te*Mgh7~#Us&de&jBW z`Faw0Wjdlgyh3p$v-WCjaipKIGWv;ggy6_1Dg=Ovj%aCQD;y}9A?ov*eaq4eA!_ujlCFB&;4930AT276<`Bpk7ug=Xk>WA z6sC3obfBUtIk7@OE!*r7>S77%>5C>@1mbsuTpSWqtC)a=&VX~hkmjPL@b-D(JSKcw z|Ep_u8r%ioP3#$2b>q0vkgW&xRF+V)*^FcDfI7EsP1gvFp*>pWbt|@h!cm2QEa=sv z2VA_hmVuKtJ%EQ-o}4X0hgVL=uw_8|8@4<~_Y+4(39aA<9U5}-;NarU&-BU(so~T- zLErgY%kuWTbdSKytG zdFF>Ej~}mjECFxk5H*^ozMZ;%X>K>NCnNsW^nZ(OvSb+YRG`;Mss>ULtdLK-5PN{> z6u|Mtv5lwLqV-g+^klzY{MpJG9aT+opZOLy@_~;dFs|$whNKzly`Z^_)JmZLWTD~q z5pqbcr$%-JwF`JPXUc^b{bDUi!~1V()kPBGOz|a7G0u! zjYm<-eej$rp^?d!(>D64abk@NgH#$1o6|OwcA!zqpjA$+XmQy(y+mO?pYD^k{gTn< z;N7yEX18|1ZdiJH6fGlN)zM%UU~wQ39Y5ov&Zd8}8qce(lRNjV@{}pm=mlrDo587_ zfjzthB)fvQANLDH&b1exUa^6Pmk1H5<;5a0j3nA*Zl?3%%m}ZoirPWxqjd48NSB2|_yq(Y`HZ8N$=XyC^-y6oEr)jhed|Ln&#jGfQF&CSQ^b z4KTM(jIKw)2roL?pVFVW>e;avcr|S9mD%(MM4>*j&>{FB18~F3F1XomhGkO-T+S0w zdMqXb|M@-JRfQ*5M$D21URB~r=G5>qTPMW$SK|WcOV8(gc0I#=xL8S4jVrfK%Edi{ zH>&+Y2rt(0ev;J`VJ$H?G^enw&bUnr4F zB`0MYLe*8%9+0oo598zjz(1_WZ;Qg>sHk38AQZQG(O4#Po(IZ)Dx2|?$cYG&p9 zKYMUSr7s~BaWzE~dfu)xpIy-WuP$f2PQ}<2y7Fp1%B5e>ZDfdSEaGJJJJFX54>30& zpKWwe#TAtZGg;f{d!;;75i4A!q6u5`rL6h4YX#DPa8WA@IssN5M`!Fny2mG-UEuHf@+=Y9cW{z*cQ@5Ld+bPZOy!` z=($#pa8)&|_|Qt&6!RwW*qi z>T!Lk24m4@+69uh0V$n4_*@i{xvI%WB0M4g*De#KijP>I|08Dn-Ans;e(yx$4@=IU z^C!m`YsQ+o(=E3hvB2rsF}Pu_vAf-4u|a{dKLCO zy#E`()Bo~3gbe4arJv_q@+YAd*l@uAsg1HN&laF6HU=~;>dwx0=W_UgVq=TqtE!m^ zs>INoap+$nZEP&S`a0}*085e~D?wyFWygH2vum|SL1n2g&HvN_pwv=Ty-d~-yfHyJ zv773~UVX2XZT~|Hib0{S!RTxb6Vs+#hA9s8h@i_ydGTMHw!*?{g%ygQt$ooel*e%SJVhp6P zmH%E%vLR*&PErj`p3k)6C$5!nQI}$_L6}%7g^HeIEr&aGP0$Ntr(KWVMR>hAE~_|r zXLTJx1yZ6_Ad99?ILu(aVQIN&O|OuRM`yQop}7|0BQ*Er9ZJQw)TyjMwS7JJ=8)sz zet9U}GJX?p`sH8>+a_F^T!sH~va~F9nAUJ0yJXQ8v8XqMuFpwyS-1lOCstq89}+d07s*QW3f|mi4}^ArFxiBiu5!?QLGu_ByAH+($*MX z)?n~Rt_2m!d*LdF!op%93Ht&ERfTo!8K+N=U26345F=>#mx|Ix?RDkT%N_&9sivVj z{c^Pe%PIX=YGYtH&GCVuBU>0(iepOxZE{QFpq^2~B$h6c-iKkloFOo52cqUzR^mBm zAN+Jh4F~Q#oGE(Qj+rlE6=z-Jhk~wzX@J6?NUO^6e4?KdGY+VVM_WTNi)Kyl_AFt4 zi+|x=w4st7wf{rA{baJbabt~?%Hy;}oVo0Bo_!P#O<+~)GyWG`eRYrY)ggCtr+>cq+pwGKXoSl-yMGZOGjI;g=<&$>OS)Ncj~-n zJ=BwW`<9WUdPW<{PFVfH>90oJCW-HtE71>+ zPEjW7@!s!>P3K20OpW7L=6bG1yGy6uo&vh?Yy8J;3&}R?2qr$2cq&9yl%%B2E_In! zJ418F1x}V?q_n`b07+@1*%<$P2-5PwGYIFK3-agma0*gl&C7GaG@BDzmojB7YEdNs z0x6$j8ZAZ*#p5S&l6zp-8y9yr>u_LS)C|mX{m?e5&wB{j{6rp@@3ojaV zKog;qYLDNFKBK7~GNAqc_ygIcs^HQ4`PjKFG5YpZ50M%CN}Scs zl_}`lDziIjg$RkYtx_I87@F-GnVOzs7n#(VBYx)#S_|O7_i^bO7Tc0nxh@=) zLxo(Bar0rEqW+8(Boj&!;A6A`$Vq6?zFAdr-7T6r(L3^@LWcIgQCCn23{0k@ZC_z5 z^dHI-wpjF4A~JC9O-*cB{Od7$1u-r!jFLDk@mZD#U4})eT-$DHB~4nt{n8tscGIUK z37^cv+rGhe_;Sr0wXa*xyGf|syFwPXI4PjEbsBxct9BT>I}Tkuk~ z)jcw%92`cS%7OX|giCE&`~(`3L&Y>*7<#&dqB9hgk7q^PfNc)z z0cDnrl9u`HH2FZv1wmyPruO2l&?{?QE|4PCneVB3IUgxoAWJI;FFjw8d_^b3no1jg zl}CT}TK-Bmk-8*D&ZP=c9`F!dG(3^|R`b!haK~v7ofNM7EdupI>*1S^YZ5(##@v^? zwmdK|+p#Q?(L^F3T3)+ucMZcY6^?RHb?%Ybs1QRGT zOkCMF1h9c9N-|qiCW-VTCbBCcJ%t5Q;DeU$ZX(K>&ZjCa&1759>hUy*CwU-Jirovo z(Jq}NyXm|%^HV$poOzUJ>e%YadJKRG*W+(mUbaWv?huhZhRQH|ypdiuoLAOda@+ z!g6(IuA+U;GIrAQA{q>r=rm@BpcsM}(O$iDDZfo+mkUbwU@K&k)XO;Hpzvp&* z<$oJtrsprX9MR`m9Gl2@#ZHn+9ER=hZxJ8n_egEZkP>(G^dpItZNC*<_NPYu{YA;D z3azo|(*yENHyg21Zybsqfq*wqHU)Oh8;MpcVxK0O-yiX>l+wra;$L|}^qJkkw4wE6 z)UatBO97fa&Dh?$157fhzFgFht>(HqFQh+a@-R| zaxcA;U5H7zKq|aAp|Il5%m@aa1hYGVN4+!*rAd`MMr<&LMYP#mp}G<-b8~4(UB>D@ z(2R_GyH0i*@4>bMYiF16C|g=Bg4N&TQ&PkC>TcI(h#En~zm_tG5ZJX3D?&?p76m{`Z15)L~XI zr`{BBHQi#WV?1(?C%I{Yz2!CG@`B!H8Nt>HovtdxkaH zZT*9EktQv45J*4>y?3Q0Bp^shLPsD32?)}wg)Y4WLKUQi9(o6*caV;BrK*4^AQmjo zYZ>{xctDKFpW-kn2izS-aeK*4lfO-=eE@cyUAea6Z}?Hipv}ep}b?2l9X+ zm)?_Q%TC#sCN%Xdv6ROpiAYVrCaM74HRR7H9t8f*{yCzGo=>V3L%n~Af@Z|h#<)la zhb*?bZ0=6xat)-8-e4VdZ@2oHvhMdgmsqQ&`9PNuSM0VG&C4|#6)m>vm!mDV=Ra10 ziw+r=&z2)!rFXJw>Zfv!=R(iC*sLrr3v#SxECr`)2vniv;8l`}^cXZ@ph?T~AZ*qM zs7jM>-wROg>X-m@Ep?*n?`8#0K-Um7`sqj`sg+mqTV^q-Cf)M$cUgjm9Yhkoy68^% zWCj|`D=F2N``xfT;#Uc^3FQAJQSP?;N@ilfa&^7!NYh9bQ7=RC=cdnjefyK3 zKWfeLuTm7tag+g_LB?yM!YRSnHx02NN%bf?03~LTLnMZJkd;>`Qaz$dVlK`mO|1IW zD9KA34pNISnT5Dz!VpMer--{5(6wa8eU%jz<!yF}viexT&ZQ^bvza^0i|620}};u$dhI)9vMSzARQ!m(#9 z>Y?=f4MYOL%8Ov)-IP9F8P?EjAoe&Fe}4(Y(oKz1VM%v*=lHZ;n=visxe{vyt@@+e z2P49L=wjhgCdHkiB`FTO@uiled$=-<;Y@v=T8FVRF!Y|L4L(Ey>UJotr-j*3WUi9? z_2(ieUpiZ+*9dv@9gyck<<7(9%^CC_Qb5Wh?E8#w1w7BK-#pJe&$3w3 zO#fZsHz%YSp%&{+A>jmJ=SWq8m|Y;uEOU!CGF}Qqst6M~?Bmy7xAZKn>#9&y1q_S% zv&fH{b@G<`&YOM(WZi;ROc=0B7`-&PcyNWueW3$qpqGkBZ-ff`9vSU@K6A@TcdqK^ z;<)z(^EJ6-|D|N#RiaqSZm)$2oxyeKu}`KZSIWi}TU;;l`PojiHG1llGn5k_O=w9c ziJ3C4%YU{uPwKcnH;|h<&vox zagg0vART|df)~PS4@$-;U3E7Qa<~%%f}bUM=4Xw)#cU*4**hO?-mPxAE9o51w${{E z?uk&mJ+g9aj?>HJlrL*yG%xhzGQg)x+ECNv#zMs^Q&{)}MdE*Ko_tWe=Kk|bbp1D> zk?4SAr|F|{pb??I^g8>6w57?KHx<`)+dGKV9{1VHl#TuoXG?>EQo@>!b2`?6XKXGp z;==MuUQ-_PqqjR$EP^hna3fn1w``}D>g6rG@58Mntmc2OycNUCq`ufe6gNxCqh6Lb zF}xV?e{?pQe@9)ZwQJa3J?-2KB{mIbpKl-}Ib2nI0 z=6bD-Yj$U*04;3ewo2<%w#^_OknRev!xFe?3gm$)Gk(?U@_&_ITdZ z;mEj9+>~&p^$p4x!qUpiD@ymWY$QTc@=AZdy7pK>Uj0he`j_2>1am8K^Vig7p{M8q zP<(>YwcyH?dC-vt%FA8*TuBab{!=9{J5^S%$F#Em<@ zrM{l>SM5PM=UI1=bB{z3Rme{oPQJc#z+~N$RNqQ6r?+lV!py#(dQ~`K$zS!+bJtfm zd~f&wj;)70*&CI(3WTT#|Z zcFs^n14X^zRxO8*d2QB9JKIY0+Es%D5~F%E&D$Kuo*RDdycdeC{x{h4R3LxBFXM#mZn__t?RK ztJZ!z$q_)!ej6+9ZLC&m3#MP2*tlA>rCCblg_H6;VF1zH8qzGzvc?s)4CXn z7b-Aj2`#tAU&(jac<|<@zH%2Vb}zuG1LH^wOds6eU(yJSyFH-i^KOub@QC4-vgT7T zHPRHoqK(i7Xq(a~z$K`%)@6*vOEe9cRo$0|3Ehiy^!v`!ZYMScPrcX2T?#~ht{L7X z5&R0=C`>%f%8m}y;4 ztKzf)+ue8}ztp zaRByu-=gZ+^mHRBFRH4TX5CWgNkW4bpZT!=qL$5VyCkNmIPKv5yUn2cbsEEq8b7ee zSfQTgThd&!9E9LxW*^xRXR89w`Sh#&~;-cfF3VnB&8SQaCV=4Wdt-?`SfZR(H$bpf@0CidEa*!>}?P zRnqNwK7-+G1rd#p6J+PLR9cNy2G$zNG2w?ta}Hc5=+&T%JB^_Jh(25W&+wHr=`Tu* zya{O_1F{D4)QpdE2U}%kLm$UYIW!nxr*3lI0o-USJp!y+98ctB-8cm(@z=^Lag}9S z%~JG1&(s2}hJBv#BNED_rWk~3rN?T`wNKv!CNlAb#;v3Zi{HZ;D3=H)WVt$1RBmMG zq|W`Q-$W~9XVHHoEW3j@JqKF$&3;EPxfE(UJ<_oG+TByTI+3Y4fB|S|I0@%&jLgpP zCB>@VKw^5#PiH!I6}XBCw@UBVnLzK>qNUB-ZLqq0G+ms*YYSa3BqT9`319}m!h+dofHnvA=qVkf&AkG!*uSpD(mx7MvoyWQIs zPqna&BsVPRVyEiOqA%4qKa@HBX;Q&|m3FA{{T7wuhipWRn4P`417+x^Q9oC(y4~|%5GyTxZLYxH2I-w# z?bY%t8w0#gc+iW&N!$j1k&T7)&d~VAmyh%6(;*C&dqU#s9|Jl)JjsWe`yR++2$6FH ziQ}%kq>uXKYRfsD`d1}f%P?8U2X!$naNTZQ%UJniP!c#j+ekr*UCqj2AJHSnlHW>z zC>(0RTalkw_Hv_Q*g2-o=B`jEjIli^90Ggf3g=10UtWr`UyKXaKUUh75Vhf^icG(< z%sLij63YyjhA(hB86&^2;s8MByb&WSR&KYx*H%{fAb1)H=7+&}DHT|jx z7twM9+XhMrD(~~OZX;4-<5}`$7@Z1AR(%6mQ6YvfZEy#xHeEWdYjo!Y{W^22 zng_bgJuARdjmRGx1KdZml(w(3tHm=A{UJjmuqbOt+?F=jQ;AN;K5Q=wVy^u58sD7@ z7X!VnU9hudx3P=7Q4L=Y&1Yt^R`4&Y%N=oUN|p^6pI*nJvrFzccW^ZLSjn@eawA+V z&ol9QiA5Q#o%W=whb{;`I($Omsj7d602WJ{qiOA|WbU@9Wp5S(3^nU4+hwimr@xPX zXT7$_gMR3HxIYE^&`40V3W2okpMP0klXX^a=B6>UGt!~6g}PcyJ-7bT*L2n+U+Dxb zOUFBzy151MIzweZDI>Kf$3}n0W#Ql(yD}1kg7xZ}7%R(9L#yL^@l_pN%3-#Tzf%1W zN+V2OIOLN|jk3Z;0*=o2q;*paTUSwK`3Q3JJMvE)SC7Y&2;xq9B6JpWgqNR0?Z*v#%N>)GAbHbs&XI{lt(}g1HO+J$o`jKCrn6_2f02!X>m2U4h!kT5 z;7y0;5zZ9V_a3`eF@AB0=TMzBy|q!ZTO%`^&$Wri7^w-Na{3z$)GX*pmY&o>GW z9i>eSV{YU`$lgz#&f)+Igl~Q0kN$*QU{VR~Ami}45pyW>TF~0Wq9B9}*QA^jlFvci zpaIx{M>mQuF1p%!2dT3O;@Jz&`PW=7A=01DrfKYXzBlEH-gA9F-;yffO0OVCgamcp zZ-Ugg+xO97iUpM*!6^fopV-3Z0++$-!aYHX*;(nOX`_5vmb}bPDfK>Gn+gmRp+nnB z!n<&@ZjI}?56+627hmO_^T;uyTa?Qpc2`nY82?|GDu$RH+*ikCu(w&e3oFIygEnXc zVXe+>`hJ*Bt7I#wg2rZnhmC?=HwuT)p-N_xxo;D+ATB8fX;ngWLsh;fH5I(&_854d z$FAJx4k+plBpeJfg;~<|$#1Dv_OaLxKWuwVxF;UEAF)zdy$g_D5#!0^FMG z7=KcXd2Kn&apI5)KWoHL*^lo>b^D)%?xjbHee(*^8hmK+s&gmLT+7dJ26(OYc91_d z9$fl|{%O=3LeP_$Z)-ih`}Nz2ey&EbK{c(J{-$|BR~R5}KkZ#LejWM!@*?FpkaiBv zrO(bhlr(oC(Dq{_Y~u+*Z@olJfohHY!8f0BEkN3Hg8r>e@kKgi*g z%MTOS7p$#q;GzK~v`Yy=I!dYBl8eF`_I?@Hfs-1yjhmwTm2!GKrV%f_P_bfh$|RvTNZ1Q~(C`NKVI(mK+0 zbMwC%mY5EFDkOCf1Hq|#R)WV>aFw_3|V6VlcC6`^Z3LDRe)!8La z4fqD3rJ-PAzI#_zIMsZS`MH|tU0ZACSbNx>Z!$8VYQ(e@gf_84eH6c8H3XECjGh$4 z8UxTP&y?pzwJMoP3#p1DuL5Q6d!kD_M99ZUv2Pic0s5i*~uk(32m3cTaHbf&Q!TpOklU>skIa;NMjiN;`7@gA{3yh<`TuuipQgCVx-& zKMDVjmHgjS{l_BzHU0lN%YPFCGRF@^8OeYKvZszZ4Fv?OzK_2s{-xkB`j82Iom-_v z-2z_u_73u}6t}hZ^&{{3yW;?yR#&cdsR>v5#?lI7cJHG`sO?U+0&rx}u~yogk&8lO z_)+m>i;*9T^1M4l%Cd$(|Blx0l<=ZVEM`B`#s$t9sAE&S*83P#?3-qCD(+j1Xrz-a zsjL@N3zMxw`c7zfO0huzjjd=)PdF&u#Sv`?9-De6qrxxdg5~oWRP>DkR*#j!CsfaB zo1tqS3}<7Nz&wEDSEkjI1C>$3jK9cMoPylWPAQIA-v+O{&8BI)GE8U#uW7b<+%21V zV#pfTs$ot@oSxSZkIof!(_2(_K_RoVRoEbPehEhRzg6xE2mnbwG^Ap=9MxtdrQVL zcNYC?3GXH$!aBLwQV7ZUknWYpE;g&8=Z8 z;$3pahFE{2<-?a6wUfLnxl$sS$EnQ6;%FvnBsyrt*c!+va=!D8+?0Rds=x~Ck|YqC zBh~C})G(PoP!6kAkO4tDZV9~wmwI4^6)|IWznRIC%Hu9gnRBtH-|74U=F~bfpvNo5 z^nEELNv86U=L7#9J@^cTUIFp&T>U_Ff=$#Kw3&&-w0_BK8dXztU%0A}zvXsUX2>N$ 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%0DMT@@?D`qzx0BkqG$M2>uVU$8 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

N)%lq( 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 ZI-I7@p>Fa3XA - - -The Prodigy integration will require a nightly version of Prodigy that supports -spaCy v3+. You can already use annotations created with Prodigy in spaCy v3 by -exporting your data with -[`data-to-spacy`](https://prodi.gy/docs/recipes#data-to-spacy) and running -[`spacy convert`](/api/cli#convert) to convert it to the binary format. - - - [Prodigy](https://prodi.gy) is a modern annotation tool for creating training data for machine learning models, developed by us. It integrates with spaCy out-of-the-box and provides many different @@ -776,17 +766,23 @@ with and without a model in the loop. If Prodigy is installed in your project, you can start the annotation server from your `project.yml` for a tight feedback loop between data development and training. -The following example command starts the Prodigy app using the -[`ner.correct`](https://prodi.gy/docs/recipes#ner-correct) recipe and streams in -suggestions for the given entity labels produced by a pretrained model. You can -then correct the suggestions manually in the UI. After you save and exit the -server, the full dataset is exported in spaCy's format and split into a training -and evaluation set. + + +This integration requires [Prodigy v1.11](https://prodi.gy/docs/changelog#v1.11) +or higher. If you're using an older version of Prodigy, you can still use your +annotations in spaCy v3 by exporting your data with +[`data-to-spacy`](https://prodi.gy/docs/recipes#data-to-spacy) and running +[`spacy convert`](/api/cli#convert) to convert it to the binary format. + + + +The following example shows a workflow for merging and exporting NER annotations +collected with Prodigy and training a spaCy pipeline: > #### Example usage > > ```cli -> $ python -m spacy project run annotate +> $ python -m spacy project run all > ``` @@ -794,36 +790,71 @@ and evaluation set. ### project.yml vars: prodigy: - dataset: 'ner_articles' - labels: 'PERSON,ORG,PRODUCT' - model: 'en_core_web_md' + train_dataset: "fashion_brands_training" + eval_dataset: "fashion_brands_eval" + +workflows: + all: + - data-to-spacy + - train_spacy commands: - - name: annotate - - script: - - 'python -m prodigy ner.correct ${vars.prodigy.dataset} ${vars.prodigy.model} ./assets/raw_data.jsonl --labels ${vars.prodigy.labels}' - - 'python -m prodigy data-to-spacy ./corpus/train.json ./corpus/eval.json --ner ${vars.prodigy.dataset}' - - 'python -m spacy convert ./corpus/train.json ./corpus/train.spacy' - - 'python -m spacy convert ./corpus/eval.json ./corpus/eval.spacy' - - deps: - - 'assets/raw_data.jsonl' - - outputs: - - 'corpus/train.spacy' - - 'corpus/eval.spacy' + - name: "data-to-spacy" + help: "Merge your annotations and create data in spaCy's binary format" + script: + - "python -m prodigy data-to-spacy corpus/ --ner ${vars.prodigy.train_dataset},eval:${vars.prodigy.eval_dataset}" + outputs: + - "corpus/train.spacy" + - "corpus/dev.spacy" + - name: "train_spacy" + help: "Train a named entity recognition model with spaCy" + script: + - "python -m spacy train configs/config.cfg --output training/ --paths.train corpus/train.spacy --paths.dev corpus/dev.spacy" + deps: + - "corpus/train.spacy" + - "corpus/dev.spacy" + outputs: + - "training/model-best" ``` -You can use the same approach for other types of projects and annotation +> #### Example train curve output +> +> [![Screenshot of train curve terminal output](../images/prodigy_train_curve.jpg)](https://prodi.gy/docs/recipes#train-curve) + +The [`train-curve`](https://prodi.gy/docs/recipes#train-curve) recipe is another +cool workflow you can include in your project. It will run the training with +different portions of the data, e.g. 25%, 50%, 75% and 100%. As a rule of thumb, +if accuracy increases in the last segment, this could indicate that collecting +more annotations of the same type might improve the model further. + + +```yaml +### project.yml (excerpt) +- name: "train_curve" + help: "Train the model with Prodigy by using different portions of training examples to evaluate if more annotations can potentially improve the performance" + script: + - "python -m prodigy train-curve --ner ${vars.prodigy.train_dataset},eval:${vars.prodigy.eval_dataset} --config configs/${vars.config} --show-plot" +``` + +You can use the same approach for various types of projects and annotation workflows, including -[text classification](https://prodi.gy/docs/recipes#textcat), -[dependency parsing](https://prodi.gy/docs/recipes#dep), +[named entity recognition](https://prodi.gy/docs/named-entity-recognition), +[span categorization](https://prodi.gy/docs/span-categorization), +[text classification](https://prodi.gy/docs/text-classification), +[dependency parsing](https://prodi.gy/docs/dependencies-relations), [part-of-speech tagging](https://prodi.gy/docs/recipes#pos) or fully -[custom recipes](https://prodi.gy/docs/custom-recipes) – for instance, an A/B -evaluation workflow that lets you compare two different models and their -results. +[custom recipes](https://prodi.gy/docs/custom-recipes). You can also use spaCy +project templates to quickly start the annotation server to collect more +annotations and add them to your Prodigy dataset. - +Get started with spaCy and Prodigy using our project template. It includes +commands to create a merged training corpus from your Prodigy annotations, +training and packaging a spaCy pipeline and analyzing if more annotations may +improve performance. + + --- From 8448c7dbc54f18a3283f8218a72c57987e4c43a8 Mon Sep 17 00:00:00 2001 From: Adriane Boyd Date: Thu, 12 Aug 2021 13:54:02 +0200 Subject: [PATCH 05/70] Update da trf recommendation (#8921) Update the da trf recommendation to the same model used in the pretrained pipelines. --- spacy/cli/templates/quickstart_training_recommendations.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spacy/cli/templates/quickstart_training_recommendations.yml b/spacy/cli/templates/quickstart_training_recommendations.yml index dac3a26c1..a7bf9b74a 100644 --- a/spacy/cli/templates/quickstart_training_recommendations.yml +++ b/spacy/cli/templates/quickstart_training_recommendations.yml @@ -41,10 +41,10 @@ da: word_vectors: da_core_news_lg transformer: efficiency: - name: DJSammy/bert-base-danish-uncased_BotXO,ai + name: Maltehb/danish-bert-botxo size_factor: 3 accuracy: - name: DJSammy/bert-base-danish-uncased_BotXO,ai + name: Maltehb/danish-bert-botxo size_factor: 3 de: word_vectors: de_core_news_lg From 92071326d814379e5f3a2cbc66aa3ca22a433c46 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 13 Aug 2021 11:48:38 +0200 Subject: [PATCH 06/70] Auto-format code with black (#8950) Co-authored-by: explosion-bot --- spacy/tests/pipeline/test_spancat.py | 1 - 1 file changed, 1 deletion(-) diff --git a/spacy/tests/pipeline/test_spancat.py b/spacy/tests/pipeline/test_spancat.py index bf1c00041..7633fcac3 100644 --- a/spacy/tests/pipeline/test_spancat.py +++ b/spacy/tests/pipeline/test_spancat.py @@ -92,7 +92,6 @@ def test_simple_train(): assert scores[f"spans_{SPAN_KEY}_f"] == 1.0 - def test_ngram_suggester(en_tokenizer): # test different n-gram lengths for size in [1, 2, 3]: From 195e4e48c38b278b28b1378df66c842252654f7b Mon Sep 17 00:00:00 2001 From: Lasse Date: Fri, 13 Aug 2021 14:35:18 +0200 Subject: [PATCH 07/70] add textdescriptives to universe --- .github/contributors/hlasse.md | 106 +++++++++++++++++++++++++++++++++ website/meta/universe.json | 30 ++++++++++ 2 files changed, 136 insertions(+) create mode 100644 .github/contributors/hlasse.md diff --git a/.github/contributors/hlasse.md b/.github/contributors/hlasse.md new file mode 100644 index 000000000..b64b3c6a6 --- /dev/null +++ b/.github/contributors/hlasse.md @@ -0,0 +1,106 @@ +# spaCy contributor agreement + +This spaCy Contributor Agreement (**"SCA"**) is based on the +[Oracle Contributor Agreement](http://www.oracle.com/technetwork/oca-405177.pdf). +The SCA applies to any contribution that you make to any product or project +managed by us (the **"project"**), and sets out the intellectual property rights +you grant to us in the contributed materials. The term **"us"** shall mean +[ExplosionAI GmbH](https://explosion.ai/legal). The term +**"you"** shall mean the person or entity identified below. + +If you agree to be bound by these terms, fill in the information requested +below and include the filled-in version with your first pull request, under the +folder [`.github/contributors/`](/.github/contributors/). The name of the file +should be your GitHub username, with the extension `.md`. For example, the user +example_user would create the file `.github/contributors/example_user.md`. + +Read this agreement carefully before signing. These terms and conditions +constitute a binding legal agreement. + +## Contributor Agreement + +1. The term "contribution" or "contributed materials" means any source code, +object code, patch, tool, sample, graphic, specification, manual, +documentation, or any other material posted or submitted by you to the project. + +2. With respect to any worldwide copyrights, or copyright applications and +registrations, in your contribution: + + * you hereby assign to us joint ownership, and to the extent that such + assignment is or becomes invalid, ineffective or unenforceable, you hereby + grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge, + royalty-free, unrestricted license to exercise all rights under those + copyrights. This includes, at our option, the right to sublicense these same + rights to third parties through multiple levels of sublicensees or other + licensing arrangements; + + * you agree that each of us can do all things in relation to your + contribution as if each of us were the sole owners, and if one of us makes + a derivative work of your contribution, the one who makes the derivative + work (or has it made will be the sole owner of that derivative work; + + * you agree that you will not assert any moral rights in your contribution + against us, our licensees or transferees; + + * you agree that we may register a copyright in your contribution and + exercise all ownership rights associated with it; and + + * you agree that neither of us has any duty to consult with, obtain the + consent of, pay or render an accounting to the other for any use or + distribution of your contribution. + +3. With respect to any patents you own, or that you can license without payment +to any third party, you hereby grant to us a perpetual, irrevocable, +non-exclusive, worldwide, no-charge, royalty-free license to: + + * make, have made, use, sell, offer to sell, import, and otherwise transfer + your contribution in whole or in part, alone or in combination with or + included in any product, work or materials arising out of the project to + which your contribution was submitted, and + + * at our option, to sublicense these same rights to third parties through + multiple levels of sublicensees or other licensing arrangements. + +4. Except as set out above, you keep all right, title, and interest in your +contribution. The rights that you grant to us under these terms are effective +on the date you first submitted a contribution to us, even if your submission +took place before the date you sign these terms. + +5. You covenant, represent, warrant and agree that: + + * Each contribution that you submit is and shall be an original work of + authorship and you can legally grant the rights set out in this SCA; + + * to the best of your knowledge, each contribution will not violate any + third party's copyrights, trademarks, patents, or other intellectual + property rights; and + + * each contribution shall be in compliance with U.S. export control laws and + other applicable export and import laws. You agree to notify us if you + become aware of any circumstance which would make any of the foregoing + representations inaccurate in any respect. We may publicly disclose your + participation in the project, including the fact that you have signed the SCA. + +6. This SCA is governed by the laws of the State of California and applicable +U.S. Federal law. Any choice of law rules will not apply. + +7. Please place an “x” on one of the applicable statement below. Please do NOT +mark both statements: + + * [X] I am signing on behalf of myself as an individual and no other person + or entity, including my employer, has or will have rights with respect to my + contributions. + + * [ ] I am signing on behalf of my employer or a legal entity and I have the + actual authority to contractually bind that entity. + +## Contributor Details + +| Field | Entry | +|------------------------------- | -------------------------- | +| Name | Lasse Hansen | +| Company name (if applicable) | | +| Title or role (if applicable) | | +| Date | 2021-08-11 | +| GitHub username | HLasse | +| Website (optional) | www.lassehansen.me | diff --git a/website/meta/universe.json b/website/meta/universe.json index 84e14a9f6..c36a6c314 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -939,6 +939,36 @@ "category": ["pipeline"], "tags": ["pipeline", "danish"] }, + { + "id": "textdescriptives", + "title": "TextDescriptives", + "slogan": "Extraction of descriptive stats, readability, and syntactic complexity measures", + "description": "Pipeline component for spaCy v.3 that calculates descriptive statistics, readability metrics, and syntactic complexity (dependency distance).", + "github": "HLasse/TextDescriptives", + "pip": "textdescriptives", + "code_example": [ + "import spacy", + "import textdescriptives as td", + "nlp = spacy.load('en_core_web_sm')", + "nlp.add_pipe('textdescriptives')", + "doc = nlp('This is a short test text')", + "doc._.readability # access some of the values", + "td.extract_df(doc) # extract all metrics to DataFrame" + ], + "author": "Lasse Hansen, Kenneth Enevoldsen, Ludvig Olsen", + "author_links": { + "github": "HLasse" + }, + "category": [ + "pipeline" + ], + "tags": [ + "pipeline", + "readability", + "syntactic complexity", + "descriptive statistics" + ] + }, { "id": "wmd-relax", "slogan": "Calculates word mover's distance insanely fast", From 839ea0f98765fc74ab67bedda008150b8010a799 Mon Sep 17 00:00:00 2001 From: Lasse Date: Fri, 13 Aug 2021 14:40:08 +0200 Subject: [PATCH 08/70] change tags formatting to match --- website/meta/universe.json | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/website/meta/universe.json b/website/meta/universe.json index c36a6c314..850f86ab4 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -962,12 +962,7 @@ "category": [ "pipeline" ], - "tags": [ - "pipeline", - "readability", - "syntactic complexity", - "descriptive statistics" - ] + "tags": ["pipeline", "readability", "syntactic complexity", "descriptive statistics"] }, { "id": "wmd-relax", From 9391998c7779081226b65888a08b51798f94b5d2 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Tue, 17 Aug 2021 00:37:21 +0900 Subject: [PATCH 09/70] Add notes on preparing training data to docs (#8964) * Add training data section Not entirely sure this is in the right location on the page - maybe it should be after quickstart? * Add pointer from binary format to training data section * Minor cleanup * Add to ToC, fix filename * Update website/docs/usage/training.md Co-authored-by: Ines Montani * Update website/docs/usage/training.md Co-authored-by: Sofie Van Landeghem * Update website/docs/usage/training.md Co-authored-by: Sofie Van Landeghem * Move the training data section further down the page * Update website/docs/usage/training.md Co-authored-by: Sofie Van Landeghem * Update website/docs/usage/training.md Co-authored-by: Sofie Van Landeghem * Run prettier Co-authored-by: Ines Montani Co-authored-by: Sofie Van Landeghem --- website/docs/api/data-formats.md | 4 +++ website/docs/usage/training.md | 54 ++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/website/docs/api/data-formats.md b/website/docs/api/data-formats.md index 1bdeb509a..001455f33 100644 --- a/website/docs/api/data-formats.md +++ b/website/docs/api/data-formats.md @@ -283,6 +283,10 @@ CLI [`train`](/api/cli#train) command. The built-in of the `.conllu` format used by the [Universal Dependencies corpora](https://github.com/UniversalDependencies). +Note that while this is the format used to save training data, you do not have +to understand the internal details to use it or create training data. See the +section on [preparing training data](/usage/training#training-data). + ### JSON training format {#json-input tag="deprecated"} diff --git a/website/docs/usage/training.md b/website/docs/usage/training.md index 6deba3761..0fe34f2a2 100644 --- a/website/docs/usage/training.md +++ b/website/docs/usage/training.md @@ -6,6 +6,7 @@ menu: - ['Introduction', 'basics'] - ['Quickstart', 'quickstart'] - ['Config System', 'config'] + - ['Training Data', 'training-data'] - ['Custom Training', 'config-custom'] - ['Custom Functions', 'custom-functions'] - ['Initialization', 'initialization'] @@ -355,6 +356,59 @@ that reference this variable. +## Preparing Training Data {#training-data} + +Training data for NLP projects comes in many different formats. For some common +formats such as CoNLL, spaCy provides [converters](/api/cli#convert) you can use +from the command line. In other cases you'll have to prepare the training data +yourself. + +When converting training data for use in spaCy, the main thing is to create +[`Doc`](/api/doc) objects just like the results you want as output from the +pipeline. For example, if you're creating an NER pipeline, loading your +annotations and setting them as the `.ents` property on a `Doc` is all you need +to worry about. On disk the annotations will be saved as a +[`DocBin`](/api/docbin) in the +[`.spacy` format](/api/data-formats#binary-training), but the details of that +are handled automatically. + +Here's an example of creating a `.spacy` file from some NER annotations. + +```python +### preprocess.py +import spacy +from spacy.tokens import DocBin + +nlp = spacy.blank("en") +training_data = [ + ("Tokyo Tower is 333m tall.", [(0, 11, "BUILDING")]), +] +# the DocBin will store the example documents +db = DocBin() +for text, annotations in training_data: + doc = nlp(text) + ents = [] + for start, end, label in annotations: + span = doc.char_span(start, end, label=label) + ents.append(span) + doc.ents = ents + db.add(doc) +db.to_disk("./train.spacy") +``` + +For more examples of how to convert training data from a wide variety of formats +for use with spaCy, look at the preprocessing steps in the +[tutorial projects](https://github.com/explosion/projects/tree/v3/tutorials). + + + +In spaCy v2, the recommended way to store training data was in +[a particular JSON format](/api/data-formats#json-input), but in v3 this format +is deprecated. It's fine as a readable storage format, but there's no need to +convert your data to JSON before creating a `.spacy` file. + + + ## Customizing the pipeline and training {#config-custom} ### Defining pipeline components {#config-components} From 593a22cf2d76630c992de96f20b28ee429fe5357 Mon Sep 17 00:00:00 2001 From: Ines Montani Date: Tue, 17 Aug 2021 17:38:15 +1000 Subject: [PATCH 10/70] Add development docs for Language and code conventions (#8745) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * WIP: add dev docs for Language / config [ci skip] * Add section on initialization [ci skip] * Fix wording [ci skip] * Add code conventions WIP [ci skip] * Update code convention docs [ci skip] * Update contributing guide and conventions [ci skip] * Update Code Conventions.md [ci skip] * Clarify sourced components + vectors * Apply suggestions from code review [ci skip] Co-authored-by: Sofie Van Landeghem * Update wording and add link [ci skip] * restructure slightly + extended index * remove paragraph that breaks flow and is repeated in more detail later * fix anchors Co-authored-by: Adriane Boyd Co-authored-by: Sofie Van Landeghem Co-authored-by: svlandeg --- CONTRIBUTING.md | 10 +- extra/DEVELOPER_DOCS/Code Conventions.md | 546 +++++++++++++++++++++++ extra/DEVELOPER_DOCS/Language.md | 150 +++++++ extra/DEVELOPER_DOCS/README.md | 7 + 4 files changed, 704 insertions(+), 9 deletions(-) create mode 100644 extra/DEVELOPER_DOCS/Code Conventions.md create mode 100644 extra/DEVELOPER_DOCS/Language.md create mode 100644 extra/DEVELOPER_DOCS/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a94b9b67..7b6a38eef 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -185,7 +185,6 @@ Each time a `git commit` is initiated, `black` and `flake8` will run automatical In case of error, or when `black` modified a file, the modified file needs to be `git add` once again and a new `git commit` has to be issued. - ### Code formatting [`black`](https://github.com/ambv/black) is an opinionated Python code @@ -414,14 +413,7 @@ all test files and test functions need to be prefixed with `test_`. When adding tests, make sure to use descriptive names, keep the code short and concise and only test for one behavior at a time. Try to `parametrize` test cases wherever possible, use our pre-defined fixtures for spaCy components and -avoid unnecessary imports. - -Extensive tests that take a long time should be marked with `@pytest.mark.slow`. -Tests that require the model to be loaded should be marked with -`@pytest.mark.models`. Loading the models is expensive and not necessary if -you're not actually testing the model performance. If all you need is a `Doc` -object with annotations like heads, POS tags or the dependency parse, you can -use the `Doc` constructor to construct it manually. +avoid unnecessary imports. Extensive tests that take a long time should be marked with `@pytest.mark.slow`. 📖 **For more guidelines and information on how to add tests, check out the [tests README](spacy/tests/README.md).** diff --git a/extra/DEVELOPER_DOCS/Code Conventions.md b/extra/DEVELOPER_DOCS/Code Conventions.md new file mode 100644 index 000000000..7a3f6996f --- /dev/null +++ b/extra/DEVELOPER_DOCS/Code Conventions.md @@ -0,0 +1,546 @@ +# Code Conventions + +For a general overview of code conventions for contributors, see the [section in the contributing guide](https://github.com/explosion/spaCy/blob/master/CONTRIBUTING.md#code-conventions). + +1. [Code compatibility](#code-compatibility) +2. [Auto-formatting](#auto-formatting) +3. [Linting](#linting) +4. [Documenting code](#documenting-code) +5. [Type hints](#type-hints) +6. [Structuring logic](#structuring-logic) +7. [Naming](#naming) +8. [Error handling](#error-handling) +9. [Writing tests](#writing-tests) + +## Code compatibility + +spaCy supports **Python 3.6** and above, so all code should be written compatible with 3.6. This means that there are certain new syntax features that we won't be able to use until we drop support for older Python versions. Some newer features provide backports that we can conditionally install for older versions, although we only want to do this if it's absolutely necessary. If we need to use conditional imports based on the Python version or other custom compatibility-specific helpers, those should live in `compat.py`. + +## Auto-formatting + +spaCy uses `black` for auto-formatting (which is also available as a pre-commit hook). It's recommended to configure your editor to perform this automatically, either triggered manually or whenever you save a file. We also have a GitHub action that regularly formats the code base and submits a PR if changes are available. Note that auto-formatting is currently only available for `.py` (Python) files, not for `.pyx` (Cython). + +As a rule of thumb, if the auto-formatting produces output that looks messy, it can often indicate that there's a better way to structure the code to make it more concise. + +```diff +- range_suggester = registry.misc.get("spacy.ngram_range_suggester.v1")( +- min_size=1, max_size=3 +- ) ++ suggester_factory = registry.misc.get("spacy.ngram_range_suggester.v1") ++ range_suggester = suggester_factory(min_size=1, max_size=3) +``` + +In some specific cases, e.g. in the tests, it can make sense to disable auto-formatting for a specific block. You can do this by wrapping the code in `# fmt: off` and `# fmt: on`: + +```diff ++ # fmt: off +text = "I look forward to using Thingamajig. I've been told it will make my life easier..." +deps = ["nsubj", "ROOT", "advmod", "prep", "pcomp", "dobj", "punct", "", + "nsubjpass", "aux", "auxpass", "ROOT", "nsubj", "aux", "ccomp", + "poss", "nsubj", "ccomp", "punct"] ++ # fmt: on +``` + +## Linting + +[`flake8`](http://flake8.pycqa.org/en/latest/) is a tool for enforcing code style. It scans one or more files and outputs errors and warnings. This feedback can help you stick to general standards and conventions, and can be very useful for spotting potential mistakes and inconsistencies in your code. Code you write should be compatible with our flake8 rules and not cause any warnings. + +```bash +flake8 spacy +``` + +The most common problems surfaced by linting are: + +- **Trailing or missing whitespace.** This is related to formatting and should be fixed automatically by running `black`. +- **Unused imports.** Those should be removed if the imports aren't actually used. If they're required, e.g. to expose them so they can be imported from the given module, you can add a comment and `# noqa: F401` exception (see details below). +- **Unused variables.** This can often indicate bugs, e.g. a variable that's declared and not correctly passed on or returned. To prevent ambiguity here, your code shouldn't contain unused variables. If you're unpacking a list of tuples and end up with variables you don't need, you can call them `_` to indicate that they're unused. +- **Redefinition of function.** This can also indicate bugs, e.g. a copy-pasted function that you forgot to rename and that now replaces the original function. +- **Repeated dictionary keys.** This either indicates a bug or unnecessary duplication. +- **Comparison with `True`, `False`, `None`**. This is mostly a stylistic thing: when checking whether a value is `True`, `False` or `None`, you should be using `is` instead of `==`. For example, `if value is None`. + +### Ignoring linter rules for special cases + +To ignore a given line, you can add a comment like `# noqa: F401`, specifying the code of the error or warning we want to ignore. It's also possible to ignore several comma-separated codes at once, e.g. `# noqa: E731,E123`. In general, you should always **specify the code(s)** you want to ignore – otherwise, you may end up missing actual problems. + +```python +# The imported class isn't used in this file, but imported here, so it can be +# imported *from* here by another module. +from .submodule import SomeClass # noqa: F401 + +try: + do_something() +except: # noqa: E722 + # This bare except is justified, for some specific reason + do_something_else() +``` + +## Documenting code + +All functions and methods you write should be documented with a docstring inline. The docstring can contain a simple summary, and an overview of the arguments and their (simplified) types. Modern editors will show this information to users when they call the function or method in their code. + +If it's part of the public API and there's a documentation section available, we usually add the link as `DOCS:` at the end. This allows us to keep the docstrings simple and concise, while also providing additional information and examples if necessary. + +```python +def has_pipe(self, name: str) -> bool: + """Check if a component name is present in the pipeline. Equivalent to + `name in nlp.pipe_names`. + + name (str): Name of the component. + RETURNS (bool): Whether a component of the name exists in the pipeline. + + DOCS: https://spacy.io/api/language#has_pipe + """ + ... +``` + +We specifically chose this approach of maintaining the docstrings and API reference separately, instead of auto-generating the API docs from the docstrings like other packages do. We want to be able to provide extensive explanations and examples in the documentation and use our own custom markup for it that would otherwise clog up the docstrings. We also want to be able to update the documentation independently of the code base. It's slightly more work, but it's absolutely worth it in terms of user and developer experience. + +### Inline code comments + +We don't expect you to add inline comments for everything you're doing – this should be obvious from reading the code. If it's not, the first thing to check is whether your code can be improved to make it more explicit. That said, if your code includes complex logic or aspects that may be unintuitive at first glance (or even included a subtle bug that you ended up fixing), you should leave a quick comment that provides more context. + +```diff +token_index = indices[value] ++ # Index describes Token.i of last token but Span indices are inclusive +span = doc[prev_token_index:token_index + 1] +``` + +```diff ++ # To create the components we need to use the final interpolated config ++ # so all values are available (if component configs use variables). ++ # Later we replace the component config with the raw config again. +interpolated = filled.interpolate() if not filled.is_interpolated else filled +``` + +Don't be shy about including comments for tricky parts that _you_ found hard to implement or get right – those may come in handy for the next person working on this code, or even future you! + +If your change implements a fix to a specific issue, it can often be helpful to include the issue number in the comment, especially if it's a relatively straightforward adjustment: + +```diff ++ # Ensure object is a Span, not a Doc (#1234) +if isinstance(obj, Doc): + obj = obj[obj.start:obj.end] +``` + +### Including TODOs + +It's fine to include code comments that indicate future TODOs, using the `TODO:` prefix. Modern editors typically format this in a different color, so it's easy to spot. TODOs don't necessarily have to be things that are absolutely critical to fix fight now – those should already be addressed in your pull request once it's ready for review. But they can include notes about potential future improvements. + +```diff ++ # TODO: this is currently pretty slow +dir_checksum = hashlib.md5() +for sub_file in sorted(fp for fp in path.rglob("*") if fp.is_file()): + dir_checksum.update(sub_file.read_bytes()) +``` + +If any of the TODOs you've added are important and should be fixed soon, you should add a task for this on Explosion's internal Ora board or an issue on the public issue tracker to make sure we don't forget to address it. + +## Type hints + +We use Python type hints across the `.py` files wherever possible. This makes it easy to understand what a function expects and returns, and modern editors will be able to show this information to you when you call an annotated function. Type hints are not currently used in the `.pyx` (Cython) code, except for definitions of registered functions and component factories, where they're used for config validation. + +If possible, you should always use the more descriptive type hints like `List[str]` or even `List[Any]` instead of only `list`. We also annotate arguments and return types of `Callable` – although, you can simplify this if the type otherwise gets too verbose (e.g. functions that return factories to create callbacks). Remember that `Callable` takes two values: a **list** of the argument type(s) in order, and the return values. + +```diff +- def func(some_arg: dict) -> None: ++ def func(some_arg: Dict[str, Any]) -> None: + ... +``` + +```python +def create_callback(some_arg: bool) -> Callable[[str, int], List[str]]: + def callback(arg1: str, arg2: int) -> List[str]: + ... + + return callback +``` + +For model architectures, Thinc also provides a collection of [custom types](https://thinc.ai/docs/api-types), including more specific types for arrays and model inputs/outputs. Even outside of static type checking, using these types will make the code a lot easier to read and follow, since it's always clear what array types are expected (and what might go wrong if the output is different from the expected type). + +```python +def build_tagger_model( + tok2vec: Model[List[Doc], List[Floats2d]], nO: Optional[int] = None +) -> Model[List[Doc], List[Floats2d]]: + ... +``` + +If you need to use a type hint that refers to something later declared in the same module, or the class that a method belongs to, you can use a string value instead: + +```python +class SomeClass: + def from_bytes(self, data: bytes) -> "SomeClass": + ... +``` + +In some cases, you won't be able to import a class from a different module to use it as a type hint because it'd cause circular imports. For instance, `spacy/util.py` includes various helper functions that return an instance of `Language`, but we couldn't import it, because `spacy/language.py` imports `util` itself. In this case, we can provide `"Language"` as a string and make the import conditional on `typing.TYPE_CHECKING` so it only runs when the code is evaluated by a type checker: + +```python +from typing TYPE_CHECKING + +if TYPE_CHECKING: + from .language import Language + +def load_model(name: str) -> "Language": + ... +``` + +## Structuring logic + +### Positional and keyword arguments + +We generally try to avoid writing functions and methods with too many arguments, and use keyword-only arguments wherever possible. Python lets you define arguments as keyword-only by separating them with a `, *`. If you're writing functions with additional arguments that customize the behavior, you typically want to make those arguments keyword-only, so their names have to be provided explicitly. + +```diff +- def do_something(name: str, validate: bool = False): ++ def do_something(name: str, *, validate: bool = False): + ... + +- do_something("some_name", True) ++ do_something("some_name", validate=True) +``` + +This makes the function calls easier to read, because it's immediately clear what the additional values mean. It also makes it easier to extend arguments or change their order later on, because you don't end up with any function calls that depend on a specific positional order. + +### Avoid mutable default arguments + +A common Python gotcha are [mutable default arguments](https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments): if your argument defines a mutable default value like `[]` or `{}` and then goes and mutates it, the default value is created _once_ when the function is created and the same object is then mutated every time the function is called. This can be pretty unintuitive when you first encounter it. We therefore avoid writing logic that does this. + +If your arguments need to default to an empty list or dict, you can use the `SimpleFrozenList` and `SimpleFrozenDict` helpers provided by spaCy. They are simple frozen implementations that raise an error if they're being mutated to prevent bugs and logic that accidentally mutates default arguments. + +```diff +- def to_bytes(self, *, exclude: List[str] = []): ++ def to_bytes(self, *, exclude: List[str] = SimpleFrozenList()): + ... +``` + +```diff +def do_something(values: List[str] = SimpleFrozenList()): + if some_condition: +- values.append("foo") # raises an error ++ values = [*values, "foo"] + return values +``` + +### Don't use `try`/`except` for control flow + +We strongly discourage using `try`/`except` blocks for anything that's not third-party error handling or error handling that we otherwise have little control over. There's typically always a way to anticipate the _actual_ problem and **check for it explicitly**, which makes the code easier to follow and understand, and prevents bugs: + +```diff +- try: +- token = doc[i] +- except IndexError: +- token = doc[-1] + ++ if i < len(doc): ++ token = doc[i] ++ else: ++ token = doc[-1] +``` + +Even if you end up having to check for multiple conditions explicitly, this is still preferred over a catch-all `try`/`except`. It can be very helpful to think about the exact scenarios you need to cover, and what could go wrong at each step, which often leads to better code and fewer bugs. `try/except` blocks can also easily mask _other_ bugs and problems that raise the same errors you're catching, which is obviously bad. + +If you have to use `try`/`except`, make sure to only include what's **absolutely necessary** in the `try` block and define the exception(s) explicitly. Otherwise, you may end up masking very different exceptions caused by other bugs. + +```diff +- try: +- value1 = get_some_value() +- value2 = get_some_other_value() +- score = external_library.compute_some_score(value1, value2) +- except: +- score = 0.0 + ++ value1 = get_some_value() ++ value2 = get_some_other_value() ++ try: ++ score = external_library.compute_some_score(value1, value2) ++ except ValueError: ++ score = 0.0 +``` + +### Avoid lambda functions + +`lambda` functions can be useful for defining simple anonymous functions in a single line, but they also introduce problems: for instance, they require [additional logic](https://stackoverflow.com/questions/25348532/can-python-pickle-lambda-functions) in order to be pickled and are pretty ugly to type-annotate. So we typically avoid them in the code base and only use them in the serialization handlers and within tests for simplicity. Instead of `lambda`s, check if your code can be refactored to not need them, or use helper functions instead. + +```diff +- split_string: Callable[[str], List[str]] = lambda value: [v.strip() for v in value.split(",")] + ++ def split_string(value: str) -> List[str]: ++ return [v.strip() for v in value.split(",")] +``` + +### Iteration and comprehensions + +We generally avoid using built-in functions like `filter` or `map` in favor of list or generator comprehensions. + +```diff +- filtered = filter(lambda x: x in ["foo", "bar"], values) ++ filtered = (x for x in values if x in ["foo", "bar"]) +- filtered = list(filter(lambda x: x in ["foo", "bar"], values)) ++ filtered = [x for x in values if x in ["foo", "bar"]] + +- result = map(lambda x: { x: x in ["foo", "bar"]}, values) ++ result = ({x: x in ["foo", "bar"]} for x in values) +- result = list(map(lambda x: { x: x in ["foo", "bar"]}, values)) ++ result = [{x: x in ["foo", "bar"]} for x in values] +``` + +If your logic is more complex, it's often better to write a loop instead, even if it adds more lines of code in total. The result will be much easier to follow and understand. + +```diff +- result = [{"key": key, "scores": {f"{i}": score for i, score in enumerate(scores)}} for key, scores in values] + ++ result = [] ++ for key, scores in values: ++ scores_dict = {f"{i}": score for i, score in enumerate(scores)} ++ result.append({"key": key, "scores": scores_dict}) +``` + +### Composition vs. inheritance + +Although spaCy uses a lot of classes, **inheritance is viewed with some suspicion** — it's seen as a mechanism of last resort. You should discuss plans to extend the class hierarchy before implementing. Unless you're implementing a new data structure or pipeline component, you typically shouldn't have to use classes at all. + +### Don't use `print` + +The core library never `print`s anything. While we encourage using `print` statements for simple debugging (it's the most straightforward way of looking at what's happening), make sure to clean them up once you're ready to submit your pull request. If you want to output warnings or debugging information for users, use the respective dedicated mechanisms for this instead (see sections on warnings and logging for details). + +The only exceptions are the CLI functions, which pretty-print messages for the user, and methods that are explicitly intended for printing things, e.g. `Language.analyze_pipes` with `pretty=True` enabled. For this, we use our lightweight helper library [`wasabi`](https://github.com/ines/wasabi). + +## Naming + +Naming is hard and often a topic of long internal discussions. We don't expect you to come up with the perfect names for everything you write – finding the right names is often an iterative and collaborative process. That said, we do try to follow some basic conventions. + +Consistent with general Python conventions, we use `CamelCase` for class names including dataclasses, `snake_case` for methods, functions and variables, and `UPPER_SNAKE_CASE` for constants, typically defined at the top of a module. We also avoid using variable names that shadow the names of built-in functions, e.g. `input`, `help` or `list`. + +### Naming variables + +Variable names should always make it clear _what exactly_ the variable is and what it's used for. Instances of common classes should use the same consistent names. For example, you should avoid naming a text string (or anything else that's not a `Doc` object) `doc`. The most common class-to-variable mappings are: + +| Class | Variable | Example | +| ---------- | --------------------- | ------------------------------------------- | +| `Language` | `nlp` | `nlp = spacy.blank("en")` | +| `Doc` | `doc` | `doc = nlp("Some text")` | +| `Span` | `span`, `ent`, `sent` | `span = doc[1:4]`, `ent = doc.ents[0]` | +| `Token` | `token` | `token = doc[0]` | +| `Lexeme` | `lexeme`, `lex` | `lex = nlp.vocab["foo"]` | +| `Vocab` | `vocab` | `vocab = Vocab()` | +| `Example` | `example`, `eg` | `example = Example.from_dict(doc, gold)` | +| `Config` | `config`, `cfg` | `config = Config().from_disk("config.cfg")` | + +We try to avoid introducing too many temporary variables, as these clutter your namespace. It's okay to re-assign to an existing variable, but only if the value has the same type. + +```diff +ents = get_a_list_of_entities() +ents = [ent for ent in doc.ents if ent.label_ == "PERSON"] +- ents = {(ent.start, ent.end): ent.label_ for ent in ents} ++ ent_mappings = {(ent.start, ent.end): ent.label_ for ent in ents} +``` + +### Naming methods and functions + +Try choosing short and descriptive names wherever possible and imperative verbs for methods that do something, e.g. `disable_pipes`, `add_patterns` or `get_vector`. Private methods and functions that are not intended to be part of the user-facing API should be prefixed with an underscore `_`. It's often helpful to look at the existing classes for inspiration. + +Objects that can be serialized, e.g. data structures and pipeline components, should implement the same consistent methods for serialization. Those usually include at least `to_disk`, `from_disk`, `to_bytes` and `from_bytes`. Some objects can also implement more specific methods like `{to/from}_dict` or `{to/from}_str`. + +## Error handling + +We always encourage writing helpful and detailed custom error messages for everything we can anticipate going wrong, and including as much detail as possible. spaCy provides a directory of error messages in `errors.py` with unique codes for each message. This allows us to keep the code base more concise and avoids long and nested blocks of texts throughout the code that disrupt the reading flow. The codes make it easy to find references to the same error in different places, and also helps identify problems reported by users (since we can just search for the error code). + +Errors can be referenced via their code, e.g. `Errors.E123`. Messages can also include placeholders for values, that can be populated by formatting the string with `.format()`. + +```python +class Errors: + E123 = "Something went wrong" + E456 = "Unexpected value: {value}" +``` + +```diff +if something_went_wrong: +- raise ValueError("Something went wrong!") ++ raise ValueError(Errors.E123) + +if not isinstance(value, int): +- raise ValueError(f"Unexpected value: {value}") ++ raise ValueError(Errors.E456.format(value=value)) +``` + +As a general rule of thumb, all error messages raised within the **core library** should be added to `Errors`. The only place where we write errors and messages as strings is `spacy.cli`, since these functions typically pretty-print and generate a lot of output that'd otherwise be very difficult to separate from the actual logic. + +### Re-raising exceptions + +If we anticipate possible errors in third-party code that we don't control, or our own code in a very different context, we typically try to provide custom and more specific error messages if possible. If we need to re-raise an exception within a `try`/`except` block, we can re-raise a custom exception. + +[Re-raising `from`](https://docs.python.org/3/tutorial/errors.html#exception-chaining) the original caught exception lets us chain the exceptions, so the user sees both the original error, as well as the custom message with a note "The above exception was the direct cause of the following exception". + +```diff +try: + run_third_party_code_that_might_fail() +except ValueError as e: ++ raise ValueError(Errors.E123) from e +``` + +In some cases, it makes sense to suppress the original exception, e.g. if we know what it is and know that it's not particularly helpful. In that case, we can raise `from None`. This prevents clogging up the user's terminal with multiple and irrelevant chained exceptions. + +```diff +try: + run_our_own_code_that_might_fail_confusingly() +except ValueError: ++ raise ValueError(Errors.E123) from None +``` + +### Avoid using naked `assert` + +During development, it can sometimes be helpful to add `assert` statements throughout your code to make sure that the values you're working with are what you expect. However, as you clean up your code, those should either be removed or replaced by more explicit error handling: + +```diff +- assert score >= 0.0 ++ if score < 0.0: ++ raise ValueError(Errors.789.format(score=score)) +``` + +Otherwise, the user will get to see a naked `AssertionError` with no further explanation, which is very unhelpful. Instead of adding an error message to `assert`, it's always better to `raise` more explicit errors for specific conditions. If you're checking for something that _has to be right_ and would otherwise be a bug in spaCy, you can express this in the error message: + +```python +E161 = ("Found an internal inconsistency when predicting entity links. " + "This is likely a bug in spaCy, so feel free to open an issue: " + "https://github.com/explosion/spaCy/issues") +``` + +### Warnings + +Instead of raising an error, some parts of the code base can raise warnings to notify the user of a potential problem. This is done using Python's `warnings.warn` and the messages defined in `Warnings` in the `errors.py`. Whether or not warnings are shown can be controlled by the user, including custom filters for disabling specific warnings using a regular expression matching our internal codes, e.g. `W123`. + +```diff +- print("Warning: No examples provided for validation") ++ warnings.warn(Warnings.W123) +``` + +When adding warnings, make sure you're not calling `warnings.warn` repeatedly, e.g. in a loop, which will clog up the terminal output. Instead, you can collect the potential problems first and then raise a single warning. If the problem is critical, consider raising an error instead. + +```diff ++ n_empty = 0 +for spans in lots_of_annotations: + if len(spans) == 0: +- warnings.warn(Warnings.456) ++ n_empty += 1 ++ warnings.warn(Warnings.456.format(count=n_empty)) +``` + +### Logging + +Log statements can be added via spaCy's `logger`, which uses Python's native `logging` module under the hood. We generally only use logging for debugging information that **the user may choose to see** in debugging mode or that's **relevant during training** but not at runtime. + +```diff ++ logger.info("Set up nlp object from config") +config = nlp.config.interpolate() +``` + +`spacy train` and similar CLI commands will enable all log statements of level `INFO` by default (which is not the case at runtime). This allows outputting specific information within certain parts of the core library during training, without having it shown at runtime. `DEBUG`-level logs are only shown if the user enables `--verbose` logging during training. They can be used to provide more specific and potentially more verbose details, especially in areas that can indicate bugs or problems, or to surface more details about what spaCy does under the hood. You should only use logging statements if absolutely necessary and important. + +## Writing tests + +spaCy uses the [`pytest`](http://doc.pytest.org/) framework for testing. Tests for spaCy modules and classes live in their own directories of the same name and all test files should be prefixed with `test_`. Tests included in the core library only cover the code and do not depend on any trained pipelines. When implementing a new feature or fixing a bug, it's usually good to start by writing some tests that describe what _should_ happen. As you write your code, you can then keep running the relevant tests until all of them pass. + +### Test suite structure + +When adding tests, make sure to use descriptive names and only test for one behavior at a time. Tests should be grouped into modules dedicated to the same type of functionality and some test modules are organized as directories of test files related to the same larger area of the library, e.g. `matcher` or `tokenizer`. + +Regression tests are tests that refer to bugs reported in specific issues. They should live in the `regression` module and are named according to the issue number (e.g. `test_issue1234.py`). This system allows us to relate tests for specific bugs back to the original reported issue, which is especially useful if we introduce a regression and a previously passing regression tests suddenly fails again. When fixing a bug, it's often useful to create a regression test for it first. Every once in a while, we go through the `regression` module and group tests together into larger files by issue number, in groups of 500 to 1000 numbers. This prevents us from ending up with too many individual files over time. + +The test suite also provides [fixtures](https://github.com/explosion/spaCy/blob/master/spacy/tests/conftest.py) for different language tokenizers that can be used as function arguments of the same name and will be passed in automatically. Those should only be used for tests related to those specific languages. We also have [test utility functions](https://github.com/explosion/spaCy/blob/master/spacy/tests/util.py) for common operations, like creating a temporary file. + +### Constructing objects and state + +Test functions usually follow the same simple structure: they set up some state, perform the operation you want to test and `assert` conditions that you expect to be true, usually before and after the operation. + +Tests should focus on exactly what they're testing and avoid dependencies on other unrelated library functionality wherever possible. If all your test needs is a `Doc` object with certain annotations set, you should always construct it manually: + +```python +def test_doc_creation_with_pos(): + doc = Doc(Vocab(), words=["hello", "world"], pos=["NOUN", "VERB"]) + assert doc[0].pos_ == "NOUN" + assert doc[1].pos_ == "VERB" +``` + +### Parametrizing tests + +If you need to run the same test function over different input examples, you usually want to parametrize the test cases instead of using a loop within your test. This lets you keep a better separation between test cases and test logic, and it'll result in more useful output because `pytest` will be able to tell you which exact test case failed. + +The `@pytest.mark.parametrize` decorator takes two arguments: a string defining one or more comma-separated arguments that should be passed to the test function and a list of corresponding test cases (or a list of tuples to provide multiple arguments). + +```python +@pytest.mark.parametrize("words", [["hello", "world"], ["this", "is", "a", "test"]]) +def test_doc_length(words): + doc = Doc(Vocab(), words=words) + assert len(doc) == len(words) +``` + +```python +@pytest.mark.parametrize("text,expected_len", [("hello world", 2), ("I can't!", 4)]) +def test_token_length(en_tokenizer, text, expected_len): # en_tokenizer is a fixture + doc = en_tokenizer(text) + assert len(doc) == expected_len +``` + +You can also stack `@pytest.mark.parametrize` decorators, although this is not recommended unless it's absolutely needed or required for the test. When stacking decorators, keep in mind that this will run the test with all possible combinations of the respective parametrized values, which is often not what you want and can slow down the test suite. + +### Handling failing tests + +`xfail` means that a test **should pass but currently fails**, i.e. is expected to fail. You can mark a test as currently xfailing by adding the `@pytest.mark.xfail` decorator. This should only be used for tests that don't yet work, not for logic that cause errors we raise on purpose (see the section on testing errors for this). It's often very helpful to implement tests for edge cases that we don't yet cover and mark them as `xfail`. You can also provide a `reason` keyword argument to the decorator with an explanation of why the test currently fails. + +```diff ++ @pytest.mark.xfail(reason="Issue #225 - not yet implemented") +def test_en_tokenizer_splits_em_dash_infix(en_tokenizer): + doc = en_tokenizer("Will this road take me to Puddleton?\u2014No.") + assert doc[8].text == "\u2014" +``` + +When you run the test suite, you may come across tests that are reported as `xpass`. This means that they're marked as `xfail` but didn't actually fail. This is worth looking into: sometimes, it can mean that we have since fixed a bug that caused the test to previously fail, so we can remove the decorator. In other cases, especially when it comes to machine learning model implementations, it can also indicate that the **test is flaky**: it sometimes passes and sometimes fails. This can be caused by a bug, or by constraints being too narrowly defined. If a test shows different behavior depending on whether its run in isolation or not, this can indicate that it reacts to global state set in a previous test, which is unideal and should be avoided. + +### Writing slow tests + +If a test is useful but potentially quite slow, you can mark it with the `@pytest.mark.slow` decorator. This is a special marker we introduced and tests decorated with it only run if you run the test suite with `--slow`, but not as part of the main CI process. Before introducing a slow test, double-check that there isn't another and more efficient way to test for the behavior. You should also consider adding a simpler test with maybe only a subset of the test cases that can always run, so we at least have some coverage. + +### Skipping tests + +The `@pytest.mark.skip` decorator lets you skip tests entirely. You only want to do this for failing tests that may be slow to run or cause memory errors or segfaults, which would otherwise terminate the entire process and wouldn't be caught by `xfail`. We also sometimes use the `skip` decorator for old and outdated regression tests that we want to keep around but that don't apply anymore. When using the `skip` decorator, make sure to provide the `reason` keyword argument with a quick explanation of why you chose to skip this test. + +### Testing errors and warnings + +`pytest` lets you check whether a given error is raised by using the `pytest.raises` contextmanager. This is very useful when implementing custom error handling, so make sure you're not only testing for the correct behavior but also for errors resulting from incorrect inputs. If you're testing errors, you should always check for `pytest.raises` explicitly and not use `xfail`. + +```python +words = ["a", "b", "c", "d", "e"] +ents = ["Q-PERSON", "I-PERSON", "O", "I-PERSON", "I-GPE"] +with pytest.raises(ValueError): + Doc(Vocab(), words=words, ents=ents) +``` + +You can also use the `pytest.warns` contextmanager to check that a given warning type is raised. The first argument is the warning type or `None` (which will capture a list of warnings that you can `assert` is empty). + +```python +def test_phrase_matcher_validation(en_vocab): + doc1 = Doc(en_vocab, words=["Test"], deps=["ROOT"]) + doc2 = Doc(en_vocab, words=["Test"]) + matcher = PhraseMatcher(en_vocab, validate=True) + with pytest.warns(UserWarning): + # Warn about unnecessarily parsed document + matcher.add("TEST1", [doc1]) + with pytest.warns(None) as record: + matcher.add("TEST2", [docs]) + assert not record.list +``` + +Keep in mind that your tests will fail if you're using the `pytest.warns` contextmanager with a given warning and the warning is _not_ shown. So you should only use it to check that spaCy handles and outputs warnings correctly. If your test outputs a warning that's expected but not relevant to what you're testing, you can use the `@pytest.mark.filterwarnings` decorator and ignore specific warnings starting with a given code: + +```python +@pytest.mark.filterwarnings("ignore:\\[W036") +def test_matcher_empty(en_vocab): + matcher = Matcher(en_vocab) + matcher(Doc(en_vocab, words=["test"])) +``` + +### Testing trained pipelines + +Our regular test suite does not depend on any of the trained pipelines, since their outputs can vary and aren't generally required to test the library functionality. We test pipelines separately using the tests included in the [`spacy-models`](https://github.com/explosion/spacy-models) repository, which run whenever we train a new suite of models. The tests here mostly focus on making sure that the packages can be loaded and that the predictions seam reasonable, and they include checks for common bugs we encountered previously. If your test does not primarily focus on verifying a model's predictions, it should be part of the core library tests and construct the required objects manually, instead of being added to the models tests. + +Keep in mind that specific predictions may change, and we can't test for all incorrect predictions reported by users. Different models make different mistakes, so even a model that's significantly more accurate overall may end up making wrong predictions that it previously didn't. However, some surprising incorrect predictions may indicate deeper bugs that we definitely want to investigate. diff --git a/extra/DEVELOPER_DOCS/Language.md b/extra/DEVELOPER_DOCS/Language.md new file mode 100644 index 000000000..f4fc85095 --- /dev/null +++ b/extra/DEVELOPER_DOCS/Language.md @@ -0,0 +1,150 @@ +# Language + +> Reference: `spacy/language.py` + +1. [Constructing the `nlp` object from a config](#1-constructing-the-nlp-object-from-a-config) + - [A. Overview of `Language.from_config`](#1a-overview) + - [B. Component factories](#1b-how-pipeline-component-factories-work-in-the-config) + - [C. Sourcing a component](#1c-sourcing-a-pipeline-component) + - [D. Tracking components as they're modified](#1d-tracking-components-as-theyre-modified) + - [E. spaCy's config utility function](#1e-spacys-config-utility-functions) +2. [Initialization](#initialization) + - [A. Initialization for training](#2a-initialization-for-training): `init_nlp` + - [B. Initializing the `nlp` object](#2b-initializing-the-nlp-object): `Language.initialize` + - [C. Initializing the vocab](#2c-initializing-the-vocab): `init_vocab` + +## 1. Constructing the `nlp` object from a config + +### 1A. Overview + +Most of the functions referenced in the config are regular functions with arbitrary arguments registered via the function registry. However, the pipeline components are a bit special: they don't only receive arguments passed in via the config file, but also the current `nlp` object and the string `name` of the individual component instance (so a user can have multiple components created with the same factory, e.g. `ner_one` and `ner_two`). This name can then be used by the components to add to the losses and scores. This special requirement means that pipeline components can't just be resolved via the config the "normal" way: we need to retrieve the component functions manually and pass them their arguments, plus the `nlp` and `name`. + +The `Language.from_config` classmethod takes care of constructing the `nlp` object from a config. It's the single place where this happens and what `spacy.load` delegates to under the hood. Its main responsibilities are: + +- **Load and validate the config**, and optionally **auto-fill** all missing values that we either have defaults for in the config template or that registered function arguments define defaults for. This helps ensure backwards-compatibility, because we're able to add a new argument `foo: str = "bar"` to an existing function, without breaking configs that don't specity it. +- **Execute relevant callbacks** for pipeline creation, e.g. optional functions called before and after creation of the `nlp` object and pipeline. +- **Initialize language subclass and create tokenizer**. The `from_config` classmethod will always be called on a language subclass, e.g. `English`, not on `Language` directly. Initializing the subclass takes a callback to create the tokenizer. +- **Set up the pipeline components**. Components can either refer to a component factory or a `source`, i.e. an existing pipeline that's loaded and that the component is then copied from. We also need to ensure that we update the information about which components are disabled. +- **Manage listeners.** If sourced components "listen" to other components (`tok2vec`, `transformer`), we need to ensure that the references are valid. If the config specifies that listeners should be replaced by copies (e.g. to give the `ner` component its own `tok2vec` model instead of listening to the shared `tok2vec` component in the pipeline), we also need to take care of that. + +Note that we only resolve and load **selected sections** in `Language.from_config`, i.e. only the parts that are relevant at runtime, which is `[nlp]` and `[components]`. We don't want to be resolving anything related to training or initialization, since this would mean loading and constructing unnecessary functions, including functions that require information that isn't necessarily available at runtime, like `paths.train`. + +### 1B. How pipeline component factories work in the config + +As opposed to regular registered functions that refer to a registry and function name (e.g. `"@misc": "foo.v1"`), pipeline components follow a different format and refer to their component `factory` name. This corresponds to the name defined via the `@Language.component` or `@Language.factory` decorator. We need this decorator to define additional meta information for the components, like their default config and score weights. + +```ini +[components.my_component] +factory = "foo" +some_arg = "bar" +other_arg = ${paths.some_path} +``` + +This means that we need to create and resolve the `config["components"]` separately from the rest of the config. There are some important considerations and things we need to manage explicitly to avoid unexpected behavior: + +#### Variable interpolation + +When a config is resolved, references to variables are replaced, so that the functions receive the correct value instead of just the variable name. To interpolate a config, we need it in its entirety: we couldn't just interpolate a subsection that refers to variables defined in a different subsection. So we first interpolate the entire config. + +However, the `nlp.config` should include the original config with variables intact – otherwise, loading a pipeline and saving it to disk will destroy all logic implemented via variables and hard-code the values all over the place. This means that when we create the components, we need to keep two versions of the config: the interpolated config with the "real" values and the `raw_config` including the variable references. + +#### Factory registry + +Component factories are special and use the `@Language.factory` or `@Language.component` decorator to register themselves and their meta. When the decorator runs, it performs some basic validation, stores the meta information for the factory on the `Language` class (default config, scores etc.) and then adds the factory function to `registry.factories`. The `component` decorator can be used for registering simple functions that just take a `Doc` object and return it so in that case, we create the factory for the user automatically. + +There's one important detail to note about how factories are registered via entry points: A package that wants to expose spaCy components still needs to register them via the `@Language` decorators so we have the component meta information and can perform required checks. All we care about here is that the decorated function is **loaded and imported**. When it is, the `@Language` decorator takes care of everything, including actually registering the component factory. + +Normally, adding to the registry via an entry point will just add the function to the registry under the given name. But for `spacy_factories`, we don't actually want that: all we care about is that the function decorated with `@Language` is imported so the decorator runs. So we only exploit Python's entry point system to automatically import the function, and the `spacy_factories` entry point group actually adds to a **separate registry**, `registry._factories`, under the hood. Its only purpose is that the functions are imported. The decorator then runs, creates the factory if needed and adds it to the `registry.factories` registry. + +#### Language-specific factories + +spaCy supports registering factories on the `Language` base class, as well as language-specific subclasses like `English` or `German`. This allows providing different factories depending on the language, e.g. a different default lemmatizer. The `Language.get_factory_name` classmethod constructs the factory name as `{lang}.{name}` if a language is available (i.e. if it's a subclass) and falls back to `{name}` otherwise. So `@German.factory("foo")` will add a factory `de.foo` under the hood. If you add `nlp.add_pipe("foo")`, we first check if there's a factory for `{nlp.lang}.foo` and if not, we fall back to checking for a factory `foo`. + +#### Creating a pipeline component from a factory + +`Language.add_pipe` takes care of adding a pipeline component, given its factory name, its config. If no source pipeline to copy the component from is provided, it delegates to `Language.create_pipe`, which sets up the actual component function. + +- Validate the config and make sure that the factory was registered via the decorator and that we have meta for it. +- Update the component config with any defaults specified by the component's `default_config`, if available. This is done by merging the values we receive into the defaults. It ensures that you can still add a component without having to specify its _entire_ config including more complex settings like `model`. If no `model` is defined, we use the default. +- Check if we have a language-specific factory for the given `nlp.lang` and if not, fall back to the global factory. +- Construct the component config, consisting of whatever arguments were provided, plus the current `nlp` object and `name`, which are default expected arguments of all factories. We also add a reference to the `@factories` registry, so we can resolve the config via the registry, like any other config. With the added `nlp` and `name`, it should now include all expected arguments of the given function. +- Fill the config to make sure all unspecified defaults from the function arguments are added and update the `raw_config` (uninterpolated with variables intact) with that information, so the component config we store in `nlp.config` is up to date. We do this by adding the `raw_config` _into_ the filled config – otherwise, the references to variables would be overwritten. +- Resolve the config and create all functions it refers to (e.g. `model`). This gives us the actual component function that we can insert into the pipeline. + +### 1C. Sourcing a pipeline component + +```ini +[components.ner] +source = "en_core_web_sm" +``` + +spaCy also allows ["sourcing" a component](https://spacy.io/usage/processing-pipelines#sourced-components), which will copy it over from an existing pipeline. In this case, `Language.add_pipe` will delegate to `Language.create_pipe_from_source`. In order to copy a component effectively and validate it, the source pipeline first needs to be loaded. This is done in `Language.from_config`, so a source pipeline only has to be loaded once if multiple components source from it. Sourcing a component will perform the following checks and modifications: + +- For each sourced pipeline component loaded in `Language.from_config`, a hash of the vectors data from the source pipeline is stored in the pipeline meta so we're able to check whether the vectors match and warn if not (since different vectors that are used as features in components can lead to degraded performance). Because the vectors are not loaded at the point when components are sourced, the check is postponed to `init_vocab` as part of `Language.initialize`. +- If the sourced pipeline component is loaded through `Language.add_pipe(source=)`, the vectors are already loaded and can be compared directly. The check compares the shape and keys first and finally falls back to comparing the actual byte representation of the vectors (which is slower). +- Ensure that the component is available in the pipeline. +- Interpolate the entire config of the source pipeline so all variables are replaced and the component's config that's copied over doesn't include references to variables that are not available in the destination config. +- Add the source `vocab.strings` to the destination's `vocab.strings` so we don't end up with unavailable strings in the final pipeline (which would also include labels used by the sourced component). + +Note that there may be other incompatibilities that we're currently not checking for and that could cause a sourced component to not work in the destination pipeline. We're interested in adding more checks here but there'll always be a small number of edge cases we'll never be able to catch, including a sourced component depending on other pipeline state that's not available in the destination pipeline. + +### 1D. Tracking components as they're modified + +The `Language` class implements methods for removing, replacing or renaming pipeline components. Whenever we make these changes, we need to update the information stored on the `Language` object to ensure that it matches the current state of the pipeline. If a user just writes to `nlp.config` manually, we obviously can't ensure that the config matches the reality – but since we offer modification via the pipe methods, it's expected that spaCy keeps the config in sync under the hood. Otherwise, saving a modified pipeline to disk and loading it back wouldn't work. The internal attributes we need to keep in sync here are: + +| Attribute | Type | Description | +| ------------------------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Language._components` | `List[Tuple[str, Callable]]` | All pipeline components as `(name, func)` tuples. This is used as the source of truth for `Language.pipeline`, `Language.pipe_names` and `Language.components`. | +| `Language._pipe_meta` | `Dict[str, FactoryMeta]` | The meta information of a component's factory, keyed by component name. This can include multiple components referring to the same factory meta. | +| `Language._pipe_configs` | `Dict[str, Config]` | The component's config, keyed by component name. | +| `Language._disabled` | `Set[str]` | Names of components that are currently disabled. | +| `Language._config` | `Config` | The underlying config. This is only internals and will be used as the basis for constructing the config in the `Language.config` property. | + +In addition to the actual component settings in `[components]`, the config also allows specifying component-specific arguments via the `[initialize.components]` block, which are passed to the component's `initialize` method during initialization if it's available. So we also need to keep this in sync in the underlying config. + +### 1E. spaCy's config utility functions + +When working with configs in spaCy, make sure to use the utility functions provided by spaCy if available, instead of calling the respective `Config` methods. The utilities take care of providing spaCy-specific error messages and ensure a consistent order of config sections by setting the `section_order` argument. This ensures that exported configs always have the same consistent format. + +- `util.load_config`: load a config from a file +- `util.load_config_from_str`: load a confirm from a string representation +- `util.copy_config`: deepcopy a config + +## 2. Initialization + +Initialization is a separate step of the [config lifecycle](https://spacy.io/usage/training#config-lifecycle) that's not performed at runtime. It's implemented via the `training.initialize.init_nlp` helper and calls into `Language.initialize` method, which sets up the pipeline and component models before training. The `initialize` method takes a callback that returns a sample of examples, which is used to initialize the component models, add all required labels and perform shape inference if applicable. + +Components can also define custom initialization setting via the `[initialize.components]` block, e.g. if they require external data like lookup tables to be loaded in. All config settings defined here will be passed to the component's `initialize` method, if it implements one. Components are expected to handle their own serialization after they're initialized so that any data or settings they require are saved with the pipeline and will be available from disk when the pipeline is loaded back at runtime. + +### 2A. Initialization for training + +The `init_nlp` function is called before training and returns an initialized `nlp` object that can be updated with the examples. It only needs the config and does the following: + +- Load and validate the config. In order to validate certain settings like the `seed`, we also interpolate the config to get the final value (because in theory, a user could provide this via a variable). +- Set up the GPU allocation, if required. +- Create the `nlp` object from the raw, uninterpolated config, which delegates to `Language.from_config`. Since this method may modify and auto-fill the config and pipeline component settings, we then use the interpolated version of `nlp.config` going forward, to ensure that what we're training with is up to date. +- Resolve the `[training]` block of the config and perform validation, e.g. to check that the corpora are available. +- Determine the components that should be frozen (not updated during training) or resumed (sourced components from a different pipeline that should be updated from the examples and not reset and re-initialized). To resume training, we can call the `nlp.resume_training` method. +- Initialize the `nlp` object via `nlp.initialize` and pass it a `get_examples` callback that returns the training corpus (used for shape inference, setting up labels etc.). If the training corpus is streamed, we only provide a small sample of the data, which can potentially be infinite. `nlp.initialize` will delegate to the components as well and pass the data sample forward. +- Check the listeners and warn about components dependencies, e.g. if a frozen component listens to a component that is retrained, or vice versa (which can degrade results). + +### 2B. Initializing the `nlp` object + +The `Language.initialize` method does the following: + +- **Resolve the config** defined in the `[initialize]` block separately (since everything else is already available in the loaded `nlp` object), based on the fully interpolated config. +- **Execute callbacks**, i.e. `before_init` and `after_init`, if they're defined. +- **Initialize the vocab**, including vocab data, lookup tables and vectors. +- **Initialize the tokenizer** if it implements an `initialize` method. This is not the case for the default tokenizers, but it allows custom tokenizers to depend on external data resources that are loaded in on initialization. +- **Initialize all pipeline components** if they implement an `initialize` method and pass them the `get_examples` callback, the current `nlp` object as well as well additional initialization config settings provided in the component-specific block. +- **Initialize pretraining** if a `[pretraining]` block is available in the config. This allows loading pretrained tok2vec weights in `spacy pretrain`. +- **Register listeners** if token-to-vector embedding layers of a component model "listen" to a previous component (`tok2vec`, `transformer`) in the pipeline. +- **Create an optimizer** on the `Language` class, either by adding the optimizer passed as `sgd` to `initialize`, or by creating the optimizer defined in the config's training settings. + +### 2C. Initializing the vocab + +Vocab initialization is handled in the `training.initialize.init_vocab` helper. It takes the relevant loaded functions and values from the config and takes care of the following: + +- Add lookup tables defined in the config initialization, e.g. custom lemmatization tables. Those will be added to `nlp.vocab.lookups` from where they can be accessed by components. +- Add JSONL-formatted [vocabulary data](https://spacy.io/api/data-formats#vocab-jsonl) to pre-populate the lexical attributes. +- Load vectors into the pipeline. Vectors are defined as a name or path to a saved `nlp` object containing the vectors, e.g. `en_vectors_web_lg`. It's loaded and the vectors are ported over, while ensuring that all source strings are available in the destination strings. We also warn if there's a mismatch between sourced vectors, since this can lead to problems. diff --git a/extra/DEVELOPER_DOCS/README.md b/extra/DEVELOPER_DOCS/README.md new file mode 100644 index 000000000..8ff505dc6 --- /dev/null +++ b/extra/DEVELOPER_DOCS/README.md @@ -0,0 +1,7 @@ + + +# Developer Documentation + +This directory includes additional documentation and explanations of spaCy's internals. It's mostly intended for the spaCy core development team and contributors interested in the more complex parts of the library. The documents generally focus on more abstract implementation details and how specific methods and algorithms work, and they assume knowledge of what's already available in the [usage documentation](https://spacy.io/usage) and [API reference](https://spacy.io/api). + +If you're looking to contribute to spaCy, make sure to check out the documentation and [contributing guide](https://github.com/explosion/spaCy/blob/master/CONTRIBUTING.md) first. From 0a6b68848f275a07e319edb0f19fa865c7332918 Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Tue, 17 Aug 2021 10:36:34 +0200 Subject: [PATCH 11/70] Fix making span_group (#8975) * fix _make_span_group * fix imports --- spacy/pipeline/spancat.py | 5 ++- spacy/tests/pipeline/test_spancat.py | 55 +++++++++++++++++++++++++++- 2 files changed, 58 insertions(+), 2 deletions(-) diff --git a/spacy/pipeline/spancat.py b/spacy/pipeline/spancat.py index e2f53be0d..2ca652f6f 100644 --- a/spacy/pipeline/spancat.py +++ b/spacy/pipeline/spancat.py @@ -411,7 +411,10 @@ class SpanCategorizer(TrainablePipe): keeps = scores >= threshold ranked = (scores * -1).argsort() - keeps[ranked[:, max_positive:]] = False + if max_positive is not None: + filter = ranked[:, max_positive:] + for i, row in enumerate(filter): + keeps[i, row] = False spans.attrs["scores"] = scores[keeps].flatten() indices = self.model.ops.to_numpy(indices) diff --git a/spacy/tests/pipeline/test_spancat.py b/spacy/tests/pipeline/test_spancat.py index 7633fcac3..638df68b1 100644 --- a/spacy/tests/pipeline/test_spancat.py +++ b/spacy/tests/pipeline/test_spancat.py @@ -1,5 +1,6 @@ import pytest -from numpy.testing import assert_equal, assert_array_equal +import numpy +from numpy.testing import assert_equal, assert_array_equal, assert_almost_equal from thinc.api import get_current_ops from spacy.language import Language from spacy.training import Example @@ -71,6 +72,55 @@ def test_explicit_labels(): assert spancat.labels == ("PERSON", "LOC") +@pytest.mark.parametrize( + "max_positive,nr_results", [(None, 4), (1, 2), (2, 3), (3, 4), (4, 4)] +) +def test_make_spangroup(max_positive, nr_results): + fix_random_seed(0) + nlp = Language() + spancat = nlp.add_pipe( + "spancat", + config={"spans_key": SPAN_KEY, "threshold": 0.5, "max_positive": max_positive}, + ) + doc = nlp.make_doc("Greater London") + ngram_suggester = registry.misc.get("spacy.ngram_suggester.v1")(sizes=[1, 2]) + indices = ngram_suggester([doc])[0].dataXd + assert_array_equal(indices, numpy.asarray([[0, 1], [1, 2], [0, 2]])) + labels = ["Thing", "City", "Person", "GreatCity"] + scores = numpy.asarray( + [[0.2, 0.4, 0.3, 0.1], [0.1, 0.6, 0.2, 0.4], [0.8, 0.7, 0.3, 0.9]], dtype="f" + ) + spangroup = spancat._make_span_group(doc, indices, scores, labels) + assert len(spangroup) == nr_results + + # first span is always the second token "London" + assert spangroup[0].text == "London" + assert spangroup[0].label_ == "City" + assert_almost_equal(0.6, spangroup.attrs["scores"][0], 5) + + # second span depends on the number of positives that were allowed + assert spangroup[1].text == "Greater London" + if max_positive == 1: + assert spangroup[1].label_ == "GreatCity" + assert_almost_equal(0.9, spangroup.attrs["scores"][1], 5) + else: + assert spangroup[1].label_ == "Thing" + assert_almost_equal(0.8, spangroup.attrs["scores"][1], 5) + + if nr_results > 2: + assert spangroup[2].text == "Greater London" + if max_positive == 2: + assert spangroup[2].label_ == "GreatCity" + assert_almost_equal(0.9, spangroup.attrs["scores"][2], 5) + else: + assert spangroup[2].label_ == "City" + assert_almost_equal(0.7, spangroup.attrs["scores"][2], 5) + + assert spangroup[-1].text == "Greater London" + assert spangroup[-1].label_ == "GreatCity" + assert_almost_equal(0.9, spangroup.attrs["scores"][-1], 5) + + def test_simple_train(): fix_random_seed(0) nlp = Language() @@ -90,6 +140,9 @@ def test_simple_train(): scores = nlp.evaluate(get_examples()) assert f"spans_{SPAN_KEY}_f" in scores assert scores[f"spans_{SPAN_KEY}_f"] == 1.0 + # also test that the spancat works for just a single entity in a sentence + doc = nlp("London") + assert len(doc.spans[spancat.key]) == 1 def test_ngram_suggester(en_tokenizer): From d94ddd568691cfa9d56b353173237afe1f328b43 Mon Sep 17 00:00:00 2001 From: Ines Montani Date: Tue, 17 Aug 2021 22:05:13 +1000 Subject: [PATCH 12/70] Auto-detect package dependencies in spacy package (#8948) * Auto-detect package dependencies in spacy package * Add simple get_third_party_dependencies test * Import packages_distributions explicitly * Inline packages_distributions * Fix docstring [ci skip] * Relax catalogue requirement * Move importlib_metadata to spacy.compat with note * Include license information [ci skip] --- licenses/3rd_party_licenses.txt | 23 +++++++++++++ spacy/cli/package.py | 60 ++++++++++++++++++++++++++++++++- spacy/compat.py | 8 +++++ spacy/language.py | 2 +- spacy/tests/test_cli.py | 8 +++++ spacy/util.py | 44 +++++++++++++++++------- 6 files changed, 130 insertions(+), 15 deletions(-) diff --git a/licenses/3rd_party_licenses.txt b/licenses/3rd_party_licenses.txt index 7bc3d4547..d58da9c4a 100644 --- a/licenses/3rd_party_licenses.txt +++ b/licenses/3rd_party_licenses.txt @@ -104,3 +104,26 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + + +importlib_metadata +------------------ + +* Files: util.py + +The implementation of packages_distributions() is adapted from +importlib_metadata, which is distributed under the following license: + +Copyright 2017-2019 Jason R. Coombs, Barry Warsaw + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/spacy/cli/package.py b/spacy/cli/package.py index 342baa8ab..b6b993267 100644 --- a/spacy/cli/package.py +++ b/spacy/cli/package.py @@ -2,6 +2,8 @@ from typing import Optional, Union, Any, Dict, List, Tuple import shutil from pathlib import Path from wasabi import Printer, MarkdownRenderer, get_raw_input +from thinc.api import Config +from collections import defaultdict import srsly import sys @@ -99,6 +101,12 @@ def package( msg.fail("Can't load pipeline meta.json", meta_path, exits=1) meta = srsly.read_json(meta_path) meta = get_meta(input_dir, meta) + if meta["requirements"]: + msg.good( + f"Including {len(meta['requirements'])} package requirement(s) from " + f"meta and config", + ", ".join(meta["requirements"]), + ) if name is not None: meta["name"] = name if version is not None: @@ -175,6 +183,51 @@ def has_wheel() -> bool: return False +def get_third_party_dependencies( + config: Config, exclude: List[str] = util.SimpleFrozenList() +) -> List[str]: + """If the config includes references to registered functions that are + provided by third-party packages (spacy-transformers, other libraries), we + want to include them in meta["requirements"] so that the package specifies + them as dependencies and the user won't have to do it manually. + + We do this by: + - traversing the config to check for registered function (@ keys) + - looking up the functions and getting their module + - looking up the module version and generating an appropriate version range + + config (Config): The pipeline config. + exclude (list): List of packages to exclude (e.g. that already exist in meta). + RETURNS (list): The versioned requirements. + """ + own_packages = ("spacy", "spacy-nightly", "thinc", "srsly") + distributions = util.packages_distributions() + funcs = defaultdict(set) + for path, value in util.walk_dict(config): + if path[-1].startswith("@"): # collect all function references by registry + funcs[path[-1][1:]].add(value) + modules = set() + for reg_name, func_names in funcs.items(): + sub_registry = getattr(util.registry, reg_name) + for func_name in func_names: + func_info = sub_registry.find(func_name) + module_name = func_info.get("module") + if module_name: # the code is part of a module, not a --code file + modules.add(func_info["module"].split(".")[0]) + dependencies = [] + for module_name in modules: + if module_name in distributions: + dist = distributions.get(module_name) + if dist: + pkg = dist[0] + if pkg in own_packages or pkg in exclude: + continue + version = util.get_package_version(pkg) + version_range = util.get_minor_version_range(version) + dependencies.append(f"{pkg}{version_range}") + return dependencies + + def get_build_formats(formats: List[str]) -> Tuple[bool, bool]: supported = ["sdist", "wheel", "none"] for form in formats: @@ -208,7 +261,7 @@ def get_meta( nlp = util.load_model_from_path(Path(model_path)) meta.update(nlp.meta) meta.update(existing_meta) - meta["spacy_version"] = util.get_model_version_range(about.__version__) + meta["spacy_version"] = util.get_minor_version_range(about.__version__) meta["vectors"] = { "width": nlp.vocab.vectors_length, "vectors": len(nlp.vocab.vectors), @@ -217,6 +270,11 @@ def get_meta( } if about.__title__ != "spacy": meta["parent_package"] = about.__title__ + meta.setdefault("requirements", []) + # Update the requirements with all third-party packages in the config + existing_reqs = [util.split_requirement(req)[0] for req in meta["requirements"]] + reqs = get_third_party_dependencies(nlp.config, exclude=existing_reqs) + meta["requirements"].extend(reqs) return meta diff --git a/spacy/compat.py b/spacy/compat.py index 6eca18b80..92ed23c0e 100644 --- a/spacy/compat.py +++ b/spacy/compat.py @@ -27,6 +27,14 @@ try: # Python 3.8+ except ImportError: from typing_extensions import Literal # noqa: F401 +# Important note: The importlib_metadata "backport" includes functionality +# that's not part of the built-in importlib.metadata. We should treat this +# import like the built-in and only use what's available there. +try: # Python 3.8+ + import importlib.metadata as importlib_metadata +except ImportError: + from catalogue import _importlib_metadata as importlib_metadata # noqa: F401 + from thinc.api import Optimizer # noqa: F401 pickle = pickle diff --git a/spacy/language.py b/spacy/language.py index a8cad1259..99d55df81 100644 --- a/spacy/language.py +++ b/spacy/language.py @@ -199,7 +199,7 @@ class Language: DOCS: https://spacy.io/api/language#meta """ - spacy_version = util.get_model_version_range(about.__version__) + spacy_version = util.get_minor_version_range(about.__version__) if self.vocab.lang: self._meta.setdefault("lang", self.vocab.lang) else: diff --git a/spacy/tests/test_cli.py b/spacy/tests/test_cli.py index 6f0fdcfa5..1841de317 100644 --- a/spacy/tests/test_cli.py +++ b/spacy/tests/test_cli.py @@ -14,6 +14,7 @@ from spacy import about from spacy.util import get_minor_version from spacy.cli.validate import get_model_pkgs from spacy.cli.download import get_compatibility, get_version +from spacy.cli.package import get_third_party_dependencies from thinc.api import ConfigValidationError, Config import srsly import os @@ -532,3 +533,10 @@ def test_init_labels(component_name): assert len(nlp2.get_pipe(component_name).labels) == 0 nlp2.initialize() assert len(nlp2.get_pipe(component_name).labels) == 4 + + +def test_get_third_party_dependencies_runs(): + # We can't easily test the detection of third-party packages here, but we + # can at least make sure that the function and its importlib magic runs. + nlp = Dutch() + assert get_third_party_dependencies(nlp.config) == [] diff --git a/spacy/util.py b/spacy/util.py index 421287ce2..6638e94ce 100644 --- a/spacy/util.py +++ b/spacy/util.py @@ -20,8 +20,10 @@ import sys import warnings from packaging.specifiers import SpecifierSet, InvalidSpecifier from packaging.version import Version, InvalidVersion +from packaging.requirements import Requirement import subprocess from contextlib import contextmanager +from collections import defaultdict import tempfile import shutil import shlex @@ -33,11 +35,6 @@ try: except ImportError: cupy = None -try: # Python 3.8 - import importlib.metadata as importlib_metadata -except ImportError: - from catalogue import _importlib_metadata as importlib_metadata - # These are functions that were previously (v2.x) available from spacy.util # and have since moved to Thinc. We're importing them here so people's code # doesn't break, but they should always be imported from Thinc from now on, @@ -46,7 +43,7 @@ from thinc.api import fix_random_seed, compounding, decaying # noqa: F401 from .symbols import ORTH -from .compat import cupy, CudaStream, is_windows +from .compat import cupy, CudaStream, is_windows, importlib_metadata from .errors import Errors, Warnings, OLD_MODEL_SHORTCUTS from . import about @@ -639,13 +636,18 @@ def is_unconstrained_version( return True -def get_model_version_range(spacy_version: str) -> str: - """Generate a version range like >=1.2.3,<1.3.0 based on a given spaCy - version. Models are always compatible across patch versions but not - across minor or major versions. +def split_requirement(requirement: str) -> Tuple[str, str]: + """Split a requirement like spacy>=1.2.3 into ("spacy", ">=1.2.3").""" + req = Requirement(requirement) + return (req.name, str(req.specifier)) + + +def get_minor_version_range(version: str) -> str: + """Generate a version range like >=1.2.3,<1.3.0 based on a given version + (e.g. of spaCy). """ - release = Version(spacy_version).release - return f">={spacy_version},<{release[0]}.{release[1] + 1}.0" + release = Version(version).release + return f">={version},<{release[0]}.{release[1] + 1}.0" def get_model_lower_version(constraint: str) -> Optional[str]: @@ -733,7 +735,7 @@ def load_meta(path: Union[str, Path]) -> Dict[str, Any]: model=f"{meta['lang']}_{meta['name']}", model_version=meta["version"], version=meta["spacy_version"], - example=get_model_version_range(about.__version__), + example=get_minor_version_range(about.__version__), ) warnings.warn(warn_msg) return meta @@ -1549,3 +1551,19 @@ def to_ternary_int(val) -> int: return 0 else: return -1 + + +# The following implementation of packages_distributions() is adapted from +# importlib_metadata, which is distributed under the Apache 2.0 License. +# Copyright (c) 2017-2019 Jason R. Coombs, Barry Warsaw +# See licenses/3rd_party_licenses.txt +def packages_distributions() -> Dict[str, List[str]]: + """Return a mapping of top-level packages to their distributions. We're + inlining this helper from the importlib_metadata "backport" here, since + it's not available in the builtin importlib.metadata. + """ + pkg_to_dist = defaultdict(list) + for dist in importlib_metadata.distributions(): + for pkg in (dist.read_text("top_level.txt") or "").split(): + pkg_to_dist[pkg].append(dist.metadata["Name"]) + return dict(pkg_to_dist) From b18cb1cd2af832c7c21262623bc07204029a1391 Mon Sep 17 00:00:00 2001 From: Steele Farnsworth <32915757+swfarnsworth@users.noreply.github.com> Date: Wed, 18 Aug 2021 03:55:45 -0400 Subject: [PATCH 13/70] Refactor dependencymatcher.pyx to use list comps and enumerate. (#8956) * Refactor to use list comps and enumerate. Replace loops that append to a list with a list comprehensions where this does not change the behavior; replace range(len(...)) loops with enumerate. Correct one typo in a comment. Replace a call to set() with a set literal. * Undo double assignment. Expand `tokens_to_key[j] = k = self._get_matcher_key(key, i, j)` to two statements. Co-authored-by: Sofie Van Landeghem * Sign contributors agreement Co-authored-by: Sofie Van Landeghem --- .github/contributors/swfarnsworth.md | 88 ++++++++++++++++++++++++++++ spacy/matcher/dependencymatcher.pyx | 35 +++-------- 2 files changed, 97 insertions(+), 26 deletions(-) create mode 100644 .github/contributors/swfarnsworth.md diff --git a/.github/contributors/swfarnsworth.md b/.github/contributors/swfarnsworth.md new file mode 100644 index 000000000..c289e6658 --- /dev/null +++ b/.github/contributors/swfarnsworth.md @@ -0,0 +1,88 @@ +## Contributor Agreement + +1. The term "contribution" or "contributed materials" means any source code, +object code, patch, tool, sample, graphic, specification, manual, +documentation, or any other material posted or submitted by you to the project. + +2. With respect to any worldwide copyrights, or copyright applications and +registrations, in your contribution: + + * you hereby assign to us joint ownership, and to the extent that such + assignment is or becomes invalid, ineffective or unenforceable, you hereby + grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge, + royalty-free, unrestricted license to exercise all rights under those + copyrights. This includes, at our option, the right to sublicense these same + rights to third parties through multiple levels of sublicensees or other + licensing arrangements; + + * you agree that each of us can do all things in relation to your + contribution as if each of us were the sole owners, and if one of us makes + a derivative work of your contribution, the one who makes the derivative + work (or has it made will be the sole owner of that derivative work; + + * you agree that you will not assert any moral rights in your contribution + against us, our licensees or transferees; + + * you agree that we may register a copyright in your contribution and + exercise all ownership rights associated with it; and + + * you agree that neither of us has any duty to consult with, obtain the + consent of, pay or render an accounting to the other for any use or + distribution of your contribution. + +3. With respect to any patents you own, or that you can license without payment +to any third party, you hereby grant to us a perpetual, irrevocable, +non-exclusive, worldwide, no-charge, royalty-free license to: + + * make, have made, use, sell, offer to sell, import, and otherwise transfer + your contribution in whole or in part, alone or in combination with or + included in any product, work or materials arising out of the project to + which your contribution was submitted, and + + * at our option, to sublicense these same rights to third parties through + multiple levels of sublicensees or other licensing arrangements. + +4. Except as set out above, you keep all right, title, and interest in your +contribution. The rights that you grant to us under these terms are effective +on the date you first submitted a contribution to us, even if your submission +took place before the date you sign these terms. + +5. You covenant, represent, warrant and agree that: + + * Each contribution that you submit is and shall be an original work of + authorship and you can legally grant the rights set out in this SCA; + + * to the best of your knowledge, each contribution will not violate any + third party's copyrights, trademarks, patents, or other intellectual + property rights; and + + * each contribution shall be in compliance with U.S. export control laws and + other applicable export and import laws. You agree to notify us if you + become aware of any circumstance which would make any of the foregoing + representations inaccurate in any respect. We may publicly disclose your + participation in the project, including the fact that you have signed the SCA. + +6. This SCA is governed by the laws of the State of California and applicable +U.S. Federal law. Any choice of law rules will not apply. + +7. Please place an “x” on one of the applicable statement below. Please do NOT +mark both statements: + + * [x] I am signing on behalf of myself as an individual and no other person + or entity, including my employer, has or will have rights with respect to my + contributions. + + * [ ] I am signing on behalf of my employer or a legal entity and I have the + actual authority to contractually bind that entity. + +## Contributor Details + +| Field | Entry | +|------------------------------- | -------------------- | +| Name | Steele Farnsworth | +| Company name (if applicable) | | +| Title or role (if applicable) | | +| Date | 13 August, 2021 | +| GitHub username | swfarnsworth | +| Website (optional) | | + diff --git a/spacy/matcher/dependencymatcher.pyx b/spacy/matcher/dependencymatcher.pyx index 9e0842d59..0cda37012 100644 --- a/spacy/matcher/dependencymatcher.pyx +++ b/spacy/matcher/dependencymatcher.pyx @@ -3,7 +3,6 @@ from typing import List from collections import defaultdict from itertools import product -import numpy import warnings from .matcher cimport Matcher @@ -122,9 +121,7 @@ cdef class DependencyMatcher: raise ValueError(Errors.E099.format(key=key)) visited_nodes[relation["RIGHT_ID"]] = True else: - required_keys = set( - ("RIGHT_ID", "RIGHT_ATTRS", "REL_OP", "LEFT_ID") - ) + required_keys = {"RIGHT_ID", "RIGHT_ATTRS", "REL_OP", "LEFT_ID"} relation_keys = set(relation.keys()) missing = required_keys - relation_keys if missing: @@ -179,28 +176,22 @@ cdef class DependencyMatcher: self._callbacks[key] = on_match # Add 'RIGHT_ATTRS' to self._patterns[key] - _patterns = [] - for pattern in patterns: - token_patterns = [] - for i in range(len(pattern)): - token_pattern = [pattern[i]["RIGHT_ATTRS"]] - token_patterns.append(token_pattern) - _patterns.append(token_patterns) + _patterns = [[[pat["RIGHT_ATTRS"]] for pat in pattern] for pattern in patterns] self._patterns[key].extend(_patterns) # Add each node pattern of all the input patterns individually to the # matcher. This enables only a single instance of Matcher to be used. # Multiple adds are required to track each node pattern. tokens_to_key_list = [] - for i in range(len(_patterns)): + for i, current_patterns in enumerate(_patterns): # Preallocate list space - tokens_to_key = [None]*len(_patterns[i]) + tokens_to_key = [None] * len(current_patterns) # TODO: Better ways to hash edges in pattern? - for j in range(len(_patterns[i])): + for j, _pattern in enumerate(current_patterns): k = self._get_matcher_key(key, i, j) - self._matcher.add(k, [_patterns[i][j]]) + self._matcher.add(k, [_pattern]) tokens_to_key[j] = k tokens_to_key_list.append(tokens_to_key) @@ -337,7 +328,7 @@ cdef class DependencyMatcher: # position of the matched tokens for candidate_match in product(*all_positions): - # A potential match is a valid match if all relationhips between the + # A potential match is a valid match if all relationships between the # matched tokens are satisfied. is_valid = True for left_idx in range(len(candidate_match)): @@ -424,18 +415,10 @@ cdef class DependencyMatcher: return [] def _right_sib(self, doc, node): - candidate_children = [] - for child in list(doc[node].head.children): - if child.i > node: - candidate_children.append(doc[child.i]) - return candidate_children + return [doc[child.i] for child in doc[node].head.children if child.i > node] def _left_sib(self, doc, node): - candidate_children = [] - for child in list(doc[node].head.children): - if child.i < node: - candidate_children.append(doc[child.i]) - return candidate_children + return [doc[child.i] for child in doc[node].head.children if child.i < node] def _normalize_key(self, key): if isinstance(key, basestring): From 6722dc3dc5a08f17388561f04da4c1456151e7a9 Mon Sep 17 00:00:00 2001 From: Adriane Boyd Date: Wed, 18 Aug 2021 09:56:56 +0200 Subject: [PATCH 14/70] Fix allow_overlap default for spancat scoring (#8970) * Remove irrelevant default options --- spacy/pipeline/spancat.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/spacy/pipeline/spancat.py b/spacy/pipeline/spancat.py index 2ca652f6f..3bc2d98a4 100644 --- a/spacy/pipeline/spancat.py +++ b/spacy/pipeline/spancat.py @@ -386,9 +386,7 @@ class SpanCategorizer(TrainablePipe): kwargs = dict(kwargs) attr_prefix = "spans_" kwargs.setdefault("attr", f"{attr_prefix}{self.key}") - kwargs.setdefault("labels", self.labels) - kwargs.setdefault("multi_label", True) - kwargs.setdefault("threshold", self.cfg["threshold"]) + kwargs.setdefault("allow_overlap", True) kwargs.setdefault( "getter", lambda doc, key: doc.spans.get(key[len(attr_prefix) :], []) ) From 71e65fe9437ebbbe04fccb4d082e71f665056206 Mon Sep 17 00:00:00 2001 From: Baltazar Date: Thu, 19 Aug 2021 21:29:25 +0200 Subject: [PATCH 15/70] added spacy api v3 docker --- website/meta/universe.json | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/website/meta/universe.json b/website/meta/universe.json index 850f86ab4..31e277296 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -3369,6 +3369,29 @@ "description": "Episodes about spaCy or interviews with the spaCy team" } ] + }, + { + "id": "spacy-api-docker-v3", + "slogan": "spaCy v3 REST API, wrapped in a Docker container", + "github": "bbieniek/spacy-api-docker", + "url": "https://hub.docker.com/r/bbieniek/spacyapi/", + "thumb": "https://i.imgur.com/NRnDKyj.jpg", + "code_example": [ + "version: '3'", + "", + "services:", + " spacyapi:", + " image: bbieniek/spacyapi:en_v3", + " ports:", + " - \"127.0.0.1:8080:80\"", + " restart: always" + ], + "code_language": "docker", + "author": "Baltazar Bieniek", + "author_links": { + "github": "bbieniek" + }, + "category": ["apis"] } ] } From 4d85cb88a5830066539025ccb11eda93dc42510f Mon Sep 17 00:00:00 2001 From: Baltazar Date: Thu, 19 Aug 2021 21:45:18 +0200 Subject: [PATCH 16/70] added contribution license --- .github/contributors/bbieniek.md | 106 +++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 .github/contributors/bbieniek.md diff --git a/.github/contributors/bbieniek.md b/.github/contributors/bbieniek.md new file mode 100644 index 000000000..4050946aa --- /dev/null +++ b/.github/contributors/bbieniek.md @@ -0,0 +1,106 @@ +# spaCy contributor agreement + +This spaCy Contributor Agreement (**"SCA"**) is based on the +[Oracle Contributor Agreement](http://www.oracle.com/technetwork/oca-405177.pdf). +The SCA applies to any contribution that you make to any product or project +managed by us (the **"project"**), and sets out the intellectual property rights +you grant to us in the contributed materials. The term **"us"** shall mean +[ExplosionAI GmbH](https://explosion.ai/legal). The term +**"you"** shall mean the person or entity identified below. + +If you agree to be bound by these terms, fill in the information requested +below and include the filled-in version with your first pull request, under the +folder [`.github/contributors/`](/.github/contributors/). The name of the file +should be your GitHub username, with the extension `.md`. For example, the user +example_user would create the file `.github/contributors/example_user.md`. + +Read this agreement carefully before signing. These terms and conditions +constitute a binding legal agreement. + +## Contributor Agreement + +1. The term "contribution" or "contributed materials" means any source code, +object code, patch, tool, sample, graphic, specification, manual, +documentation, or any other material posted or submitted by you to the project. + +2. With respect to any worldwide copyrights, or copyright applications and +registrations, in your contribution: + + * you hereby assign to us joint ownership, and to the extent that such + assignment is or becomes invalid, ineffective or unenforceable, you hereby + grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge, + royalty-free, unrestricted license to exercise all rights under those + copyrights. This includes, at our option, the right to sublicense these same + rights to third parties through multiple levels of sublicensees or other + licensing arrangements; + + * you agree that each of us can do all things in relation to your + contribution as if each of us were the sole owners, and if one of us makes + a derivative work of your contribution, the one who makes the derivative + work (or has it made will be the sole owner of that derivative work; + + * you agree that you will not assert any moral rights in your contribution + against us, our licensees or transferees; + + * you agree that we may register a copyright in your contribution and + exercise all ownership rights associated with it; and + + * you agree that neither of us has any duty to consult with, obtain the + consent of, pay or render an accounting to the other for any use or + distribution of your contribution. + +3. With respect to any patents you own, or that you can license without payment +to any third party, you hereby grant to us a perpetual, irrevocable, +non-exclusive, worldwide, no-charge, royalty-free license to: + + * make, have made, use, sell, offer to sell, import, and otherwise transfer + your contribution in whole or in part, alone or in combination with or + included in any product, work or materials arising out of the project to + which your contribution was submitted, and + + * at our option, to sublicense these same rights to third parties through + multiple levels of sublicensees or other licensing arrangements. + +4. Except as set out above, you keep all right, title, and interest in your +contribution. The rights that you grant to us under these terms are effective +on the date you first submitted a contribution to us, even if your submission +took place before the date you sign these terms. + +5. You covenant, represent, warrant and agree that: + + * Each contribution that you submit is and shall be an original work of + authorship and you can legally grant the rights set out in this SCA; + + * to the best of your knowledge, each contribution will not violate any + third party's copyrights, trademarks, patents, or other intellectual + property rights; and + + * each contribution shall be in compliance with U.S. export control laws and + other applicable export and import laws. You agree to notify us if you + become aware of any circumstance which would make any of the foregoing + representations inaccurate in any respect. We may publicly disclose your + participation in the project, including the fact that you have signed the SCA. + +6. This SCA is governed by the laws of the State of California and applicable +U.S. Federal law. Any choice of law rules will not apply. + +7. Please place an “x” on one of the applicable statement below. Please do NOT +mark both statements: + + * [X] I am signing on behalf of myself as an individual and no other person + or entity, including my employer, has or will have rights with respect to my + contributions. + + * [ ] I am signing on behalf of my employer or a legal entity and I have the + actual authority to contractually bind that entity. + +## Contributor Details + +| Field | Entry | +|------------------------------- | -------------------- | +| Name | Baltazar Bieniek | +| Company name (if applicable) | | +| Title or role (if applicable) | | +| Date | 2021.08.19 | +| GitHub username | bbieniek | +| Website (optional) | https://baltazar.bieniek.org.pl/ | \ No newline at end of file From f2b61b77a5c566f446905b19bebd63d67f2d2170 Mon Sep 17 00:00:00 2001 From: Ines Montani Date: Fri, 20 Aug 2021 11:26:29 +1000 Subject: [PATCH 17/70] Fix universe.json [ci skip] --- website/meta/universe.json | 50 ++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 26 deletions(-) diff --git a/website/meta/universe.json b/website/meta/universe.json index 31e277296..64fc811b4 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -959,9 +959,7 @@ "author_links": { "github": "HLasse" }, - "category": [ - "pipeline" - ], + "category": ["pipeline"], "tags": ["pipeline", "readability", "syntactic complexity", "descriptive statistics"] }, { @@ -3286,6 +3284,29 @@ }, "category": ["pipeline", "standalone"], "tags": ["pipeline"] + }, + { + "id": "spacy-api-docker-v3", + "slogan": "spaCy v3 REST API, wrapped in a Docker container", + "github": "bbieniek/spacy-api-docker", + "url": "https://hub.docker.com/r/bbieniek/spacyapi/", + "thumb": "https://i.imgur.com/NRnDKyj.jpg", + "code_example": [ + "version: '3'", + "", + "services:", + " spacyapi:", + " image: bbieniek/spacyapi:en_v3", + " ports:", + " - \"127.0.0.1:8080:80\"", + " restart: always" + ], + "code_language": "docker", + "author": "Baltazar Bieniek", + "author_links": { + "github": "bbieniek" + }, + "category": ["apis"] } ], @@ -3369,29 +3390,6 @@ "description": "Episodes about spaCy or interviews with the spaCy team" } ] - }, - { - "id": "spacy-api-docker-v3", - "slogan": "spaCy v3 REST API, wrapped in a Docker container", - "github": "bbieniek/spacy-api-docker", - "url": "https://hub.docker.com/r/bbieniek/spacyapi/", - "thumb": "https://i.imgur.com/NRnDKyj.jpg", - "code_example": [ - "version: '3'", - "", - "services:", - " spacyapi:", - " image: bbieniek/spacyapi:en_v3", - " ports:", - " - \"127.0.0.1:8080:80\"", - " restart: always" - ], - "code_language": "docker", - "author": "Baltazar Bieniek", - "author_links": { - "github": "bbieniek" - }, - "category": ["apis"] } ] } From 37fe847af4c1991110ce16b3e0a0c3010e6743bc Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Fri, 20 Aug 2021 15:34:22 +0900 Subject: [PATCH 18/70] Fix type annotation in docs --- website/docs/api/doc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/api/doc.md b/website/docs/api/doc.md index 9358507dc..0b5ef56c0 100644 --- a/website/docs/api/doc.md +++ b/website/docs/api/doc.md @@ -212,7 +212,7 @@ alignment mode `"strict". | Name | Description | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `start` | The index of the first character of the span. ~~int~~ | -| `end` | The index of the last character after the span. ~int~~ | +| `end` | The index of the last character after the span. ~~int~~ | | `label` | A label to attach to the span, e.g. for named entities. ~~Union[int, str]~~ | | `kb_id` 2.2 | An ID from a knowledge base to capture the meaning of a named entity. ~~Union[int, str]~~ | | `vector` | A meaning representation of the span. ~~numpy.ndarray[ndim=1, dtype=float32]~~ | From de025beb5fa1f9c02b61cec617fa8068e15ccf0d Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Fri, 20 Aug 2021 11:06:19 +0200 Subject: [PATCH 19/70] Warn and document spangroup.doc weakref (#8980) * test for error after Doc has been garbage collected * warn about using a SpanGroup when the Doc has been garbage collected * add warning to the docs * rephrase slightly * raise error instead of warning * update * move warning to doc property --- spacy/errors.py | 4 ++++ spacy/tests/pipeline/test_spancat.py | 21 ++++++++++++++++++++- spacy/tokens/span_group.pyx | 8 +++++++- website/docs/api/spangroup.md | 10 ++++++++++ 4 files changed, 41 insertions(+), 2 deletions(-) diff --git a/spacy/errors.py b/spacy/errors.py index 9264ca6d1..36331fe15 100644 --- a/spacy/errors.py +++ b/spacy/errors.py @@ -521,6 +521,10 @@ class Errors: E202 = ("Unsupported alignment mode '{mode}'. Supported modes: {modes}.") # New errors added in v3.x + E866 = ("A SpanGroup is not functional after the corresponding Doc has " + "been garbage collected. To keep using the spans, make sure that " + "the corresponding Doc object is still available in the scope of " + "your function.") E867 = ("The 'textcat' component requires at least two labels because it " "uses mutually exclusive classes where exactly one label is True " "for each doc. For binary classification tasks, you can use two " diff --git a/spacy/tests/pipeline/test_spancat.py b/spacy/tests/pipeline/test_spancat.py index 638df68b1..974994372 100644 --- a/spacy/tests/pipeline/test_spancat.py +++ b/spacy/tests/pipeline/test_spancat.py @@ -1,8 +1,10 @@ import pytest import numpy -from numpy.testing import assert_equal, assert_array_equal, assert_almost_equal +from numpy.testing import assert_array_equal, assert_almost_equal from thinc.api import get_current_ops from spacy.language import Language +from spacy.tokens.doc import SpanGroups +from spacy.tokens import SpanGroup from spacy.training import Example from spacy.util import fix_random_seed, registry @@ -72,6 +74,23 @@ def test_explicit_labels(): assert spancat.labels == ("PERSON", "LOC") +def test_doc_gc(): + # If the Doc object is garbage collected, the spans won't be functional afterwards + nlp = Language() + spancat = nlp.add_pipe("spancat", config={"spans_key": SPAN_KEY}) + spancat.add_label("PERSON") + nlp.initialize() + texts = ["Just a sentence.", "I like London and Berlin", "I like Berlin", "I eat ham."] + all_spans = [doc.spans for doc in nlp.pipe(texts)] + for text, spangroups in zip(texts, all_spans): + assert isinstance(spangroups, SpanGroups) + for key, spangroup in spangroups.items(): + assert isinstance(spangroup, SpanGroup) + assert len(spangroup) > 0 + with pytest.raises(RuntimeError): + span = spangroup[0] + + @pytest.mark.parametrize( "max_positive,nr_results", [(None, 4), (1, 2), (2, 3), (3, 4), (4, 4)] ) diff --git a/spacy/tokens/span_group.pyx b/spacy/tokens/span_group.pyx index 081685c25..eb9221584 100644 --- a/spacy/tokens/span_group.pyx +++ b/spacy/tokens/span_group.pyx @@ -1,6 +1,8 @@ import weakref import struct import srsly + +from spacy.errors import Errors from .span cimport Span from libc.stdint cimport uint64_t, uint32_t, int32_t @@ -58,7 +60,11 @@ cdef class SpanGroup: DOCS: https://spacy.io/api/spangroup#doc """ - return self._doc_ref() + doc = self._doc_ref() + if doc is None: + # referent has been garbage collected + raise RuntimeError(Errors.E866) + return doc @property def has_overlap(self): diff --git a/website/docs/api/spangroup.md b/website/docs/api/spangroup.md index ba248f376..654067eb1 100644 --- a/website/docs/api/spangroup.md +++ b/website/docs/api/spangroup.md @@ -46,6 +46,16 @@ Create a `SpanGroup`. The [`Doc`](/api/doc) object the span group is referring to. + + +When a `Doc` object is garbage collected, any related `SpanGroup` object won't +be functional anymore, as these objects use a `weakref` to refer to the +document. An error will be raised as the internal `doc` object will be `None`. +To avoid this, make sure that the original `Doc` objects are still available in +the scope of your function. + + + > #### Example > > ```python From 9cc3dc2b67ef41963b78c0d553cfd7175d998d66 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Fri, 20 Aug 2021 19:04:02 +0900 Subject: [PATCH 20/70] Add glossary entry for _SP (#8983) --- spacy/glossary.py | 1 + 1 file changed, 1 insertion(+) diff --git a/spacy/glossary.py b/spacy/glossary.py index 0dc075ca7..e45704fc5 100644 --- a/spacy/glossary.py +++ b/spacy/glossary.py @@ -95,6 +95,7 @@ GLOSSARY = { "XX": "unknown", "BES": 'auxiliary "be"', "HVS": 'forms of "have"', + "_SP": "whitespace", # POS Tags (German) # TIGER Treebank # http://www.ims.uni-stuttgart.de/forschung/ressourcen/korpora/TIGERCorpus/annotation/tiger_introduction.pdf From 4d52d7051cda8492c54acf43a4e76fafd1aef6ec Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Fri, 20 Aug 2021 12:37:50 +0200 Subject: [PATCH 21/70] Fix spancat training on nested entities (#9007) * overfitting test on non-overlapping entities * add failing overfitting test for overlapping entities * failing test for list comprehension * remove test that was put in separate PR * bugfix * cleanup --- spacy/pipeline/spancat.py | 2 +- spacy/tests/pipeline/test_spancat.py | 140 ++++++++++++++++++++------- 2 files changed, 106 insertions(+), 36 deletions(-) diff --git a/spacy/pipeline/spancat.py b/spacy/pipeline/spancat.py index 3bc2d98a4..4cdaf3d83 100644 --- a/spacy/pipeline/spancat.py +++ b/spacy/pipeline/spancat.py @@ -398,7 +398,7 @@ class SpanCategorizer(TrainablePipe): pass def _get_aligned_spans(self, eg: Example): - return eg.get_aligned_spans_y2x(eg.reference.spans.get(self.key, [])) + return eg.get_aligned_spans_y2x(eg.reference.spans.get(self.key, []), allow_overlap=True) def _make_span_group( self, doc: Doc, indices: Ints2d, scores: Floats2d, labels: List[str] diff --git a/spacy/tests/pipeline/test_spancat.py b/spacy/tests/pipeline/test_spancat.py index 974994372..3da5816ab 100644 --- a/spacy/tests/pipeline/test_spancat.py +++ b/spacy/tests/pipeline/test_spancat.py @@ -2,11 +2,14 @@ import pytest import numpy from numpy.testing import assert_array_equal, assert_almost_equal from thinc.api import get_current_ops + +from spacy import util +from spacy.lang.en import English from spacy.language import Language from spacy.tokens.doc import SpanGroups from spacy.tokens import SpanGroup from spacy.training import Example -from spacy.util import fix_random_seed, registry +from spacy.util import fix_random_seed, registry, make_tempdir OPS = get_current_ops() @@ -20,17 +23,21 @@ TRAIN_DATA = [ ), ] +TRAIN_DATA_OVERLAPPING = [ + ("Who is Shaka Khan?", {"spans": {SPAN_KEY: [(7, 17, "PERSON")]}}), + ( + "I like London and Berlin", + {"spans": {SPAN_KEY: [(7, 13, "LOC"), (18, 24, "LOC"), (7, 24, "DOUBLE_LOC")]}}, + ), +] -def make_get_examples(nlp): + +def make_examples(nlp, data=TRAIN_DATA): train_examples = [] - for t in TRAIN_DATA: + for t in data: eg = Example.from_dict(nlp.make_doc(t[0]), t[1]) train_examples.append(eg) - - def get_examples(): - return train_examples - - return get_examples + return train_examples def test_no_label(): @@ -57,9 +64,7 @@ def test_implicit_labels(): nlp = Language() spancat = nlp.add_pipe("spancat", config={"spans_key": SPAN_KEY}) assert len(spancat.labels) == 0 - train_examples = [] - for t in TRAIN_DATA: - train_examples.append(Example.from_dict(nlp.make_doc(t[0]), t[1])) + train_examples = make_examples(nlp) nlp.initialize(get_examples=lambda: train_examples) assert spancat.labels == ("PERSON", "LOC") @@ -140,30 +145,6 @@ def test_make_spangroup(max_positive, nr_results): assert_almost_equal(0.9, spangroup.attrs["scores"][-1], 5) -def test_simple_train(): - fix_random_seed(0) - nlp = Language() - spancat = nlp.add_pipe("spancat", config={"spans_key": SPAN_KEY}) - get_examples = make_get_examples(nlp) - nlp.initialize(get_examples) - sgd = nlp.create_optimizer() - assert len(spancat.labels) != 0 - for i in range(40): - losses = {} - nlp.update(list(get_examples()), losses=losses, drop=0.1, sgd=sgd) - doc = nlp("I like London and Berlin.") - assert doc.spans[spancat.key] == doc.spans[SPAN_KEY] - assert len(doc.spans[spancat.key]) == 2 - assert len(doc.spans[spancat.key].attrs["scores"]) == 2 - assert doc.spans[spancat.key][0].text == "London" - scores = nlp.evaluate(get_examples()) - assert f"spans_{SPAN_KEY}_f" in scores - assert scores[f"spans_{SPAN_KEY}_f"] == 1.0 - # also test that the spancat works for just a single entity in a sentence - doc = nlp("London") - assert len(doc.spans[spancat.key]) == 1 - - def test_ngram_suggester(en_tokenizer): # test different n-gram lengths for size in [1, 2, 3]: @@ -282,3 +263,92 @@ def test_ngram_sizes(en_tokenizer): range_suggester = suggester_factory(min_size=2, max_size=4) ngrams_3 = range_suggester(docs) assert_array_equal(OPS.to_numpy(ngrams_3.lengths), [0, 1, 3, 6, 9]) + + +def test_overfitting_IO(): + # Simple test to try and quickly overfit the spancat component - ensuring the ML models work correctly + fix_random_seed(0) + nlp = English() + spancat = nlp.add_pipe("spancat", config={"spans_key": SPAN_KEY}) + train_examples = make_examples(nlp) + optimizer = nlp.initialize(get_examples=lambda: train_examples) + assert spancat.model.get_dim("nO") == 2 + assert set(spancat.labels) == {"LOC", "PERSON"} + + for i in range(50): + losses = {} + nlp.update(train_examples, sgd=optimizer, losses=losses) + assert losses["spancat"] < 0.01 + + # test the trained model + test_text = "I like London and Berlin" + doc = nlp(test_text) + assert doc.spans[spancat.key] == doc.spans[SPAN_KEY] + spans = doc.spans[SPAN_KEY] + assert len(spans) == 2 + assert len(spans.attrs["scores"]) == 2 + assert min(spans.attrs["scores"]) > 0.9 + assert set([span.text for span in spans]) == {"London", "Berlin"} + assert set([span.label_ for span in spans]) == {"LOC"} + + # Also test the results are still the same after IO + with make_tempdir() as tmp_dir: + nlp.to_disk(tmp_dir) + nlp2 = util.load_model_from_path(tmp_dir) + doc2 = nlp2(test_text) + spans2 = doc2.spans[SPAN_KEY] + assert len(spans2) == 2 + assert len(spans2.attrs["scores"]) == 2 + assert min(spans2.attrs["scores"]) > 0.9 + assert set([span.text for span in spans2]) == {"London", "Berlin"} + assert set([span.label_ for span in spans2]) == {"LOC"} + + # Test scoring + scores = nlp.evaluate(train_examples) + assert f"spans_{SPAN_KEY}_f" in scores + assert scores[f"spans_{SPAN_KEY}_p"] == 1.0 + assert scores[f"spans_{SPAN_KEY}_r"] == 1.0 + assert scores[f"spans_{SPAN_KEY}_f"] == 1.0 + + # also test that the spancat works for just a single entity in a sentence + doc = nlp("London") + assert len(doc.spans[spancat.key]) == 1 + + +def test_overfitting_IO_overlapping(): + # Test for overfitting on overlapping entities + fix_random_seed(0) + nlp = English() + spancat = nlp.add_pipe("spancat", config={"spans_key": SPAN_KEY}) + + train_examples = make_examples(nlp, data=TRAIN_DATA_OVERLAPPING) + optimizer = nlp.initialize(get_examples=lambda: train_examples) + assert spancat.model.get_dim("nO") == 3 + assert set(spancat.labels) == {"PERSON", "LOC", "DOUBLE_LOC"} + + for i in range(50): + losses = {} + nlp.update(train_examples, sgd=optimizer, losses=losses) + assert losses["spancat"] < 0.01 + + # test the trained model + test_text = "I like London and Berlin" + doc = nlp(test_text) + spans = doc.spans[SPAN_KEY] + assert len(spans) == 3 + assert len(spans.attrs["scores"]) == 3 + assert min(spans.attrs["scores"]) > 0.9 + assert set([span.text for span in spans]) == {"London", "Berlin", "London and Berlin"} + assert set([span.label_ for span in spans]) == {"LOC", "DOUBLE_LOC"} + + # Also test the results are still the same after IO + with make_tempdir() as tmp_dir: + nlp.to_disk(tmp_dir) + nlp2 = util.load_model_from_path(tmp_dir) + doc2 = nlp2(test_text) + spans2 = doc2.spans[SPAN_KEY] + assert len(spans2) == 3 + assert len(spans2.attrs["scores"]) == 3 + assert min(spans2.attrs["scores"]) > 0.9 + assert set([span.text for span in spans2]) == {"London", "Berlin", "London and Berlin"} + assert set([span.label_ for span in spans2]) == {"LOC", "DOUBLE_LOC"} From e1f88de729f113f068958c824cf01026363bb110 Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Fri, 20 Aug 2021 12:41:09 +0200 Subject: [PATCH 22/70] bump to 3.1.2 (#9008) --- spacy/about.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spacy/about.py b/spacy/about.py index 51154dc1a..85b579f95 100644 --- a/spacy/about.py +++ b/spacy/about.py @@ -1,6 +1,6 @@ # fmt: off __title__ = "spacy" -__version__ = "3.1.1" +__version__ = "3.1.2" __download_url__ = "https://github.com/explosion/spacy-models/releases/download" __compatibility__ = "https://raw.githubusercontent.com/explosion/spacy-models/master/compatibility.json" __projects__ = "https://github.com/explosion/projects" From 4cd052e81d3b7cff9afaa7ca1870a04ef35adeda Mon Sep 17 00:00:00 2001 From: Ines Montani Date: Wed, 25 Aug 2021 22:58:01 +1000 Subject: [PATCH 23/70] Include component factories in third-party dependencies resolver (#9009) * Include component factories in third-party dependencies resolver * Increment catalogue and update test --- requirements.txt | 2 +- setup.cfg | 2 +- spacy/cli/package.py | 3 +++ spacy/tests/test_cli.py | 2 ++ 4 files changed, 7 insertions(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index ad8c70318..74dd11375 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,7 +8,7 @@ ml_datasets>=0.2.0,<0.3.0 murmurhash>=0.28.0,<1.1.0 wasabi>=0.8.1,<1.1.0 srsly>=2.4.1,<3.0.0 -catalogue>=2.0.4,<2.1.0 +catalogue>=2.0.6,<2.1.0 typer>=0.3.0,<0.4.0 pathy>=0.3.5 # Third party dependencies diff --git a/setup.cfg b/setup.cfg index 1fa5b828d..06ab3ca40 100644 --- a/setup.cfg +++ b/setup.cfg @@ -48,7 +48,7 @@ install_requires = blis>=0.4.0,<0.8.0 wasabi>=0.8.1,<1.1.0 srsly>=2.4.1,<3.0.0 - catalogue>=2.0.4,<2.1.0 + catalogue>=2.0.6,<2.1.0 typer>=0.3.0,<0.4.0 pathy>=0.3.5 # Third-party dependencies diff --git a/spacy/cli/package.py b/spacy/cli/package.py index b6b993267..9350b58e4 100644 --- a/spacy/cli/package.py +++ b/spacy/cli/package.py @@ -206,6 +206,9 @@ def get_third_party_dependencies( for path, value in util.walk_dict(config): if path[-1].startswith("@"): # collect all function references by registry funcs[path[-1][1:]].add(value) + for component in config.get("components", {}).values(): + if "factory" in component: + funcs["factories"].add(component["factory"]) modules = set() for reg_name, func_names in funcs.items(): sub_registry = getattr(util.registry, reg_name) diff --git a/spacy/tests/test_cli.py b/spacy/tests/test_cli.py index 1841de317..e84159b64 100644 --- a/spacy/tests/test_cli.py +++ b/spacy/tests/test_cli.py @@ -539,4 +539,6 @@ def test_get_third_party_dependencies_runs(): # We can't easily test the detection of third-party packages here, but we # can at least make sure that the function and its importlib magic runs. nlp = Dutch() + # Test with component factory based on Cython module + nlp.add_pipe("tagger") assert get_third_party_dependencies(nlp.config) == [] From 31e9b126a0beab0abeef1376676b0e9e7e7c2031 Mon Sep 17 00:00:00 2001 From: David Strouk Date: Wed, 25 Aug 2021 16:55:09 +0300 Subject: [PATCH 24/70] Fix verbs list in lang/fr/tokenizer_exceptions.py (#9033) --- spacy/lang/fr/tokenizer_exceptions.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spacy/lang/fr/tokenizer_exceptions.py b/spacy/lang/fr/tokenizer_exceptions.py index 6f429eecc..060f81879 100644 --- a/spacy/lang/fr/tokenizer_exceptions.py +++ b/spacy/lang/fr/tokenizer_exceptions.py @@ -82,7 +82,8 @@ for orth in [ for verb in [ "a", - "est" "semble", + "est", + "semble", "indique", "moque", "passe", From 94fb840443e9c2dbbfe19189b949637bec6c109c Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Wed, 25 Aug 2021 16:06:22 +0200 Subject: [PATCH 25/70] fix docs for Span constructor arguments (#9023) --- spacy/tokens/span.pyx | 7 ++++--- website/docs/api/span.md | 17 +++++++++-------- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/spacy/tokens/span.pyx b/spacy/tokens/span.pyx index 7087ba986..093e8c826 100644 --- a/spacy/tokens/span.pyx +++ b/spacy/tokens/span.pyx @@ -89,9 +89,10 @@ cdef class Span: start (int): The index of the first token of the span. end (int): The index of the first token after the span. label (uint64): A label to attach to the Span, e.g. for named entities. - kb_id (uint64): An identifier from a Knowledge Base to capture the meaning of a named entity. vector (ndarray[ndim=1, dtype='float32']): A meaning representation of the span. + vector_norm (float): The L2 norm of the span's vector representation. + kb_id (uint64): An identifier from a Knowledge Base to capture the meaning of a named entity. DOCS: https://spacy.io/api/span#init """ @@ -486,10 +487,10 @@ cdef class Span: """ if "vector_norm" in self.doc.user_span_hooks: return self.doc.user_span_hooks["vector"](self) - vector = self.vector - xp = get_array_module(vector) if self._vector_norm is None: + vector = self.vector total = (vector*vector).sum() + xp = get_array_module(vector) self._vector_norm = xp.sqrt(total) if total != 0. else 0. return self._vector_norm diff --git a/website/docs/api/span.md b/website/docs/api/span.md index 48e310979..2938b4253 100644 --- a/website/docs/api/span.md +++ b/website/docs/api/span.md @@ -18,14 +18,15 @@ Create a `Span` object from the slice `doc[start : end]`. > assert [t.text for t in span] == ["it", "back", "!"] > ``` -| Name | Description | -| -------- | --------------------------------------------------------------------------------------- | -| `doc` | The parent document. ~~Doc~~ | -| `start` | The index of the first token of the span. ~~int~~ | -| `end` | The index of the first token after the span. ~~int~~ | -| `label` | A label to attach to the span, e.g. for named entities. ~~Union[str, int]~~ | -| `kb_id` | A knowledge base ID to attach to the span, e.g. for named entities. ~~Union[str, int]~~ | -| `vector` | A meaning representation of the span. ~~numpy.ndarray[ndim=1, dtype=float32]~~ | +| Name | Description | +| ------------- | --------------------------------------------------------------------------------------- | +| `doc` | The parent document. ~~Doc~~ | +| `start` | The index of the first token of the span. ~~int~~ | +| `end` | The index of the first token after the span. ~~int~~ | +| `label` | A label to attach to the span, e.g. for named entities. ~~Union[str, int]~~ | +| `vector` | A meaning representation of the span. ~~numpy.ndarray[ndim=1, dtype=float32]~~ | +| `vector_norm` | The L2 norm of the document's vector representation. ~~float~~ | +| `kb_id` | A knowledge base ID to attach to the span, e.g. for named entities. ~~Union[str, int]~~ | ## Span.\_\_getitem\_\_ {#getitem tag="method"} From 4d39430b82b16b2d9c9afb553a7047fd9406a877 Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Thu, 26 Aug 2021 09:50:35 +0200 Subject: [PATCH 26/70] Document use-case of freezing tok2vec (#8992) * update error msg * add sentence to docs * expand note on frozen components --- spacy/errors.py | 12 +++++------- spacy/training/initialize.py | 3 ++- website/docs/usage/training.md | 25 ++++++++++++++++--------- 3 files changed, 23 insertions(+), 17 deletions(-) diff --git a/spacy/errors.py b/spacy/errors.py index 36331fe15..a206826ff 100644 --- a/spacy/errors.py +++ b/spacy/errors.py @@ -116,13 +116,11 @@ class Warnings: # New warnings added in v3.x W086 = ("Component '{listener}' will be (re)trained, but it needs the component " - "'{name}' which is frozen. You can either freeze both, or neither " - "of the two. If you're sourcing the component from " - "an existing pipeline, you can use the `replace_listeners` setting in " - "the config block to replace its token-to-vector listener with a copy " - "and make it independent. For example, `replace_listeners = " - "[\"model.tok2vec\"]` See the documentation for details: " - "https://spacy.io/usage/training#config-components-listeners") + "'{name}' which is frozen. If you want to prevent retraining '{name}' " + "but want to train '{listener}' on top of it, you should add '{name}' to the " + "list of 'annotating_components' in the 'training' block in the config. " + "See the documentation for details: " + "https://spacy.io/usage/training#annotating-components") W087 = ("Component '{name}' will be (re)trained, but the component '{listener}' " "depends on it via a listener and is frozen. This means that the " "performance of '{listener}' will be degraded. You can either freeze " diff --git a/spacy/training/initialize.py b/spacy/training/initialize.py index 04d030964..bd014f75f 100644 --- a/spacy/training/initialize.py +++ b/spacy/training/initialize.py @@ -95,7 +95,8 @@ def init_nlp(config: Config, *, use_gpu: int = -1) -> "Language": logger.warning(Warnings.W087.format(name=name, listener=listener)) # We always check this regardless, in case user freezes tok2vec if listener not in frozen_components and name in frozen_components: - logger.warning(Warnings.W086.format(name=name, listener=listener)) + if name not in T["annotating_components"]: + logger.warning(Warnings.W086.format(name=name, listener=listener)) return nlp diff --git a/website/docs/usage/training.md b/website/docs/usage/training.md index 0fe34f2a2..94fdad209 100644 --- a/website/docs/usage/training.md +++ b/website/docs/usage/training.md @@ -480,7 +480,10 @@ as-is. They are also excluded when calling > still impact your model's performance – for instance, a sentence boundary > detector can impact what the parser or entity recognizer considers a valid > parse. So the evaluation results should always reflect what your pipeline will -> produce at runtime. +> produce at runtime. If you want a frozen component to run (without updating) +> during training as well, so that downstream components can use its +> **predictions**, you can add it to the list of +> [`annotating_components`](/usage/training#annotating-components). ```ini [nlp] @@ -567,6 +570,10 @@ frozen_components = ["ner"] annotating_components = ["sentencizer", "ner"] ``` +Similarly, a pretrained `tok2vec` layer can be frozen and specified in the list +of `annotating_components` to ensure that a downstream component can use the +embedding layer without updating it. + Be aware that non-frozen annotating components with statistical models will @@ -699,14 +706,14 @@ excluded from the logs and the score won't be weighted. -| Name | Description | -| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| **Loss** | The training loss representing the amount of work left for the optimizer. Should decrease, but usually not to `0`. | -| **Precision** (P) | Percentage of predicted annotations that were correct. Should increase. | -| **Recall** (R) | Percentage of reference annotations recovered. Should increase. | -| **F-Score** (F) | Harmonic mean of precision and recall. Should increase. | -| **UAS** / **LAS** | Unlabeled and labeled attachment score for the dependency parser, i.e. the percentage of correct arcs. Should increase. | -| **Speed** | Prediction speed in words per second (WPS). Should stay stable. | +| Name | Description | +| ----------------- | ----------------------------------------------------------------------------------------------------------------------- | +| **Loss** | The training loss representing the amount of work left for the optimizer. Should decrease, but usually not to `0`. | +| **Precision** (P) | Percentage of predicted annotations that were correct. Should increase. | +| **Recall** (R) | Percentage of reference annotations recovered. Should increase. | +| **F-Score** (F) | Harmonic mean of precision and recall. Should increase. | +| **UAS** / **LAS** | Unlabeled and labeled attachment score for the dependency parser, i.e. the percentage of correct arcs. Should increase. | +| **Speed** | Prediction speed in words per second (WPS). Should stay stable. | Note that if the development data has raw text, some of the gold-standard entities might not align to the predicted tokenization. These tokenization From fb9c31fbdab28ba4b907e759cd799d8f186af1a0 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 27 Aug 2021 11:42:27 +0200 Subject: [PATCH 27/70] Auto-format code with black (#9065) Co-authored-by: explosion-bot --- spacy/pipeline/spancat.py | 4 +++- spacy/tests/pipeline/test_spancat.py | 19 ++++++++++++++++--- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/spacy/pipeline/spancat.py b/spacy/pipeline/spancat.py index 4cdaf3d83..052bd2874 100644 --- a/spacy/pipeline/spancat.py +++ b/spacy/pipeline/spancat.py @@ -398,7 +398,9 @@ class SpanCategorizer(TrainablePipe): pass def _get_aligned_spans(self, eg: Example): - return eg.get_aligned_spans_y2x(eg.reference.spans.get(self.key, []), allow_overlap=True) + return eg.get_aligned_spans_y2x( + eg.reference.spans.get(self.key, []), allow_overlap=True + ) def _make_span_group( self, doc: Doc, indices: Ints2d, scores: Floats2d, labels: List[str] diff --git a/spacy/tests/pipeline/test_spancat.py b/spacy/tests/pipeline/test_spancat.py index 3da5816ab..7b759f8f6 100644 --- a/spacy/tests/pipeline/test_spancat.py +++ b/spacy/tests/pipeline/test_spancat.py @@ -85,7 +85,12 @@ def test_doc_gc(): spancat = nlp.add_pipe("spancat", config={"spans_key": SPAN_KEY}) spancat.add_label("PERSON") nlp.initialize() - texts = ["Just a sentence.", "I like London and Berlin", "I like Berlin", "I eat ham."] + texts = [ + "Just a sentence.", + "I like London and Berlin", + "I like Berlin", + "I eat ham.", + ] all_spans = [doc.spans for doc in nlp.pipe(texts)] for text, spangroups in zip(texts, all_spans): assert isinstance(spangroups, SpanGroups) @@ -338,7 +343,11 @@ def test_overfitting_IO_overlapping(): assert len(spans) == 3 assert len(spans.attrs["scores"]) == 3 assert min(spans.attrs["scores"]) > 0.9 - assert set([span.text for span in spans]) == {"London", "Berlin", "London and Berlin"} + assert set([span.text for span in spans]) == { + "London", + "Berlin", + "London and Berlin", + } assert set([span.label_ for span in spans]) == {"LOC", "DOUBLE_LOC"} # Also test the results are still the same after IO @@ -350,5 +359,9 @@ def test_overfitting_IO_overlapping(): assert len(spans2) == 3 assert len(spans2.attrs["scores"]) == 3 assert min(spans2.attrs["scores"]) > 0.9 - assert set([span.text for span in spans2]) == {"London", "Berlin", "London and Berlin"} + assert set([span.text for span in spans2]) == { + "London", + "Berlin", + "London and Berlin", + } assert set([span.label_ for span in spans2]) == {"LOC", "DOUBLE_LOC"} From 1e974de837cb2f548faaf72ad00213e61107e8d7 Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Fri, 27 Aug 2021 11:44:31 +0200 Subject: [PATCH 28/70] config is not Optional (#9024) --- spacy/language.py | 13 ++++++------- website/docs/api/language.md | 4 ++-- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/spacy/language.py b/spacy/language.py index 99d55df81..08fb63d4c 100644 --- a/spacy/language.py +++ b/spacy/language.py @@ -605,7 +605,7 @@ class Language: factory_name: str, name: Optional[str] = None, *, - config: Optional[Dict[str, Any]] = SimpleFrozenDict(), + config: Dict[str, Any] = SimpleFrozenDict(), raw_config: Optional[Config] = None, validate: bool = True, ) -> Callable[[Doc], Doc]: @@ -615,8 +615,8 @@ class Language: factory_name (str): Name of component factory. name (Optional[str]): Optional name to assign to component instance. Defaults to factory name if not set. - config (Optional[Dict[str, Any]]): Config parameters to use for this - component. Will be merged with default config, if available. + config (Dict[str, Any]): Config parameters to use for this component. + Will be merged with default config, if available. raw_config (Optional[Config]): Internals: the non-interpolated config. validate (bool): Whether to validate the component config against the arguments and types expected by the factory. @@ -640,7 +640,6 @@ class Language: ) raise ValueError(err) pipe_meta = self.get_factory_meta(factory_name) - config = config or {} # This is unideal, but the alternative would mean you always need to # specify the full config settings, which is not really viable. if pipe_meta.default_config: @@ -722,7 +721,7 @@ class Language: first: Optional[bool] = None, last: Optional[bool] = None, source: Optional["Language"] = None, - config: Optional[Dict[str, Any]] = SimpleFrozenDict(), + config: Dict[str, Any] = SimpleFrozenDict(), raw_config: Optional[Config] = None, validate: bool = True, ) -> Callable[[Doc], Doc]: @@ -743,8 +742,8 @@ class Language: last (bool): If True, insert component last in the pipeline. source (Language): Optional loaded nlp object to copy the pipeline component from. - config (Optional[Dict[str, Any]]): Config parameters to use for this - component. Will be merged with default config, if available. + config (Dict[str, Any]): Config parameters to use for this component. + Will be merged with default config, if available. raw_config (Optional[Config]): Internals: the non-interpolated config. validate (bool): Whether to validate the component config against the arguments and types expected by the factory. diff --git a/website/docs/api/language.md b/website/docs/api/language.md index b09ae1aa2..0aa33b281 100644 --- a/website/docs/api/language.md +++ b/website/docs/api/language.md @@ -446,7 +446,7 @@ component, adds it to the pipeline and returns it. | `after` | Component name or index to insert component directly after. ~~Optional[Union[str, int]]~~ | | `first` | Insert component first / not first in the pipeline. ~~Optional[bool]~~ | | `last` | Insert component last / not last in the pipeline. ~~Optional[bool]~~ | -| `config` 3 | Optional config parameters to use for this component. Will be merged with the `default_config` specified by the component factory. ~~Optional[Dict[str, Any]]~~ | +| `config` 3 | Optional config parameters to use for this component. Will be merged with the `default_config` specified by the component factory. ~~Dict[str, Any]~~ | | `source` 3 | Optional source pipeline to copy component from. If a source is provided, the `factory_name` is interpreted as the name of the component in the source pipeline. Make sure that the vocab, vectors and settings of the source pipeline match the target pipeline. ~~Optional[Language]~~ | | `validate` 3 | Whether to validate the component config and arguments against the types expected by the factory. Defaults to `True`. ~~bool~~ | | **RETURNS** | The pipeline component. ~~Callable[[Doc], Doc]~~ | @@ -476,7 +476,7 @@ To create a component and add it to the pipeline, you should always use | `factory_name` | Name of the registered component factory. ~~str~~ | | `name` | Optional unique name of pipeline component instance. If not set, the factory name is used. An error is raised if the name already exists in the pipeline. ~~Optional[str]~~ | | _keyword-only_ | | -| `config` 3 | Optional config parameters to use for this component. Will be merged with the `default_config` specified by the component factory. ~~Optional[Dict[str, Any]]~~ | +| `config` 3 | Optional config parameters to use for this component. Will be merged with the `default_config` specified by the component factory. ~~Dict[str, Any]~~ | | `validate` 3 | Whether to validate the component config and arguments against the types expected by the factory. Defaults to `True`. ~~bool~~ | | **RETURNS** | The pipeline component. ~~Callable[[Doc], Doc]~~ | From 2613f0e98f6f5278e03a2e46e5df55efe45922ef Mon Sep 17 00:00:00 2001 From: Meenal Jhajharia Date: Sat, 28 Aug 2021 16:35:58 +0530 Subject: [PATCH 29/70] benepar usage example has deprecated imports --- website/meta/universe.json | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/website/meta/universe.json b/website/meta/universe.json index 64fc811b4..993e900ff 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -2064,11 +2064,9 @@ "github": "nikitakit/self-attentive-parser", "pip": "benepar", "code_example": [ - "import spacy", - "from benepar.spacy_plugin import BeneparComponent", - "", - "nlp = spacy.load('en')", - "nlp.add_pipe(BeneparComponent('benepar_en'))", + "import benepar, spacy", + "nlp = spacy.load('en_core_web_md')", + "nlp.add_pipe('benepar', config={'model': 'benepar_en3'})", "doc = nlp('The time for action is now. It is never too late to do something.')", "sent = list(doc.sents)[0]", "print(sent._.parse_string)", From 1e9b4b55ee5a423f4dfed447daa38a250ce85eb8 Mon Sep 17 00:00:00 2001 From: Adriane Boyd Date: Mon, 30 Aug 2021 09:23:54 +0200 Subject: [PATCH 30/70] Pass overrides to subcommands in workflows (#9059) * Pass overrides to subcommands in workflows * Add missing docstring --- spacy/cli/project/run.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spacy/cli/project/run.py b/spacy/cli/project/run.py index ececc2507..ef753d256 100644 --- a/spacy/cli/project/run.py +++ b/spacy/cli/project/run.py @@ -57,6 +57,7 @@ def project_run( project_dir (Path): Path to project directory. subcommand (str): Name of command to run. + overrides (Dict[str, Any]): Optional config overrides. force (bool): Force re-running, even if nothing changed. dry (bool): Perform a dry run and don't execute commands. capture (bool): Whether to capture the output and errors of individual commands. @@ -72,7 +73,7 @@ def project_run( if subcommand in workflows: msg.info(f"Running workflow '{subcommand}'") for cmd in workflows[subcommand]: - project_run(project_dir, cmd, force=force, dry=dry, capture=capture) + project_run(project_dir, cmd, overrides=overrides, force=force, dry=dry, capture=capture) else: cmd = commands[subcommand] for dep in cmd.get("deps", []): From 5af88427a2fa1a5f3cdb699872d775a5f2db5c57 Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Mon, 30 Aug 2021 14:56:35 +0200 Subject: [PATCH 31/70] Dev docs: listeners (#9061) * Start Listeners documentation * intro tabel of different architectures * initialization, linking, dim inference * internal comm (WIP) * expand internal comm section * frozen components and replacing listeners * various small fixes * fix content table * fix link --- extra/DEVELOPER_DOCS/Listeners.md | 220 ++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 extra/DEVELOPER_DOCS/Listeners.md diff --git a/extra/DEVELOPER_DOCS/Listeners.md b/extra/DEVELOPER_DOCS/Listeners.md new file mode 100644 index 000000000..3a71082e0 --- /dev/null +++ b/extra/DEVELOPER_DOCS/Listeners.md @@ -0,0 +1,220 @@ +# Listeners + +1. [Overview](#1-overview) +2. [Initialization](#2-initialization) + - [A. Linking listeners to the embedding component](#2a-linking-listeners-to-the-embedding-component) + - [B. Shape inference](#2b-shape-inference) +3. [Internal communication](#3-internal-communication) + - [A. During prediction](#3a-during-prediction) + - [B. During training](#3b-during-training) + - [C. Frozen components](#3c-frozen-components) +4. [Replacing listener with standalone](#4-replacing-listener-with-standalone) + +## 1. Overview + +Trainable spaCy components typically use some sort of `tok2vec` layer as part of the `model` definition. +This `tok2vec` layer produces embeddings and is either a standard `Tok2Vec` layer, or a Transformer-based one. +Both versions can be used either inline/standalone, which means that they are defined and used +by only one specific component (e.g. NER), or +[shared](https://spacy.io/usage/embeddings-transformers#embedding-layers), +in which case the embedding functionality becomes a separate component that can +feed embeddings to multiple components downstream, using a listener-pattern. + +| Type | Usage | Model Architecture | +| ------------- | ---------- | -------------------------------------------------------------------------------------------------- | +| `Tok2Vec` | standalone | [`spacy.Tok2Vec`](https://spacy.io/api/architectures#Tok2Vec) | +| `Tok2Vec` | listener | [`spacy.Tok2VecListener`](https://spacy.io/api/architectures#Tok2VecListener) | +| `Transformer` | standalone | [`spacy-transformers.Tok2VecTransformer`](https://spacy.io/api/architectures#Tok2VecTransformer) | +| `Transformer` | listener | [`spacy-transformers.TransformerListener`](https://spacy.io/api/architectures#TransformerListener) | + +Here we discuss the listener pattern and its implementation in code in more detail. + +## 2. Initialization + +### 2A. Linking listeners to the embedding component + +To allow sharing a `tok2vec` layer, a separate `tok2vec` component needs to be defined in the config: + +``` +[components.tok2vec] +factory = "tok2vec" + +[components.tok2vec.model] +@architectures = "spacy.Tok2Vec.v2" +``` + +A listener can then be set up by making sure the correct `upstream` name is defined, referring to the +name of the `tok2vec` component (which equals the factory name by default), or `*` as a wildcard: + +``` +[components.ner.model.tok2vec] +@architectures = "spacy.Tok2VecListener.v1" +upstream = "tok2vec" +``` + +When an [`nlp`](https://github.com/explosion/spaCy/blob/master/extra/DEVELOPER_DOCS/Language.md) object is +initialized or deserialized, it will make sure to link each `tok2vec` component to its listeners. This is +implemented in the method `nlp._link_components()` which loops over each +component in the pipeline and calls `find_listeners()` on a component if it's defined. +The [`tok2vec` component](https://github.com/explosion/spaCy/blob/master/spacy/pipeline/tok2vec.py)'s implementation +of this `find_listener()` method will specifically identify sublayers of a model definition that are of type +`Tok2VecListener` with a matching upstream name and will then add that listener to the internal `self.listener_map`. + +If it's a Transformer-based pipeline, a +[`transformer` component](https://github.com/explosion/spacy-transformers/blob/master/spacy_transformers/pipeline_component.py) +has a similar implementation but its `find_listener()` function will specifically look for `TransformerListener` +sublayers of downstream components. + +### 2B. Shape inference + +Typically, the output dimension `nO` of a listener's model equals the `nO` (or `width`) of the upstream embedding layer. +For a standard `Tok2Vec`-based component, this is typically known up-front and defined as such in the config: + +``` +[components.ner.model.tok2vec] +@architectures = "spacy.Tok2VecListener.v1" +width = ${components.tok2vec.model.encode.width} +``` + +A `transformer` component however only knows its `nO` dimension after the HuggingFace transformer +is set with the function `model.attrs["set_transformer"]`, +[implemented](https://github.com/explosion/spacy-transformers/blob/master/spacy_transformers/layers/transformer_model.py) +by `set_pytorch_transformer`. +This is why, upon linking of the transformer listeners, the `transformer` component also makes sure to set +the listener's output dimension correctly. + +This shape inference mechanism also needs to happen with resumed/frozen components, which means that for some CLI +commands (`assemble` and `train`), we need to call `nlp._link_components` even before initializing the `nlp` +object. To cover all use-cases and avoid negative side effects, the code base ensures that performing the +linking twice is not harmful. + +## 3. Internal communication + +The internal communication between a listener and its downstream components is organized by sending and +receiving information across the components - either directly or implicitly. +The details are different depending on whether the pipeline is currently training, or predicting. +Either way, the `tok2vec` or `transformer` component always needs to run before the listener. + +### 3A. During prediction + +When the `Tok2Vec` pipeline component is called, its `predict()` method is executed to produce the results, +which are then stored by `set_annotations()` in the `doc.tensor` field of the document(s). +Similarly, the `Transformer` component stores the produced embeddings +in `doc._.trf_data`. Next, the `forward` pass of a +[`Tok2VecListener`](https://github.com/explosion/spaCy/blob/master/spacy/pipeline/tok2vec.py) +or a +[`TransformerListener`](https://github.com/explosion/spacy-transformers/blob/master/spacy_transformers/layers/listener.py) +accesses these fields on the `Doc` directly. Both listener implementations have a fallback mechanism for when these +properties were not set on the `Doc`: in that case an all-zero tensor is produced and returned. +We need this fallback mechanism to enable shape inference methods in Thinc, but the code +is slightly risky and at times might hide another bug - so it's a good spot to be aware of. + +### 3B. During training + +During training, the `update()` methods of the `Tok2Vec` & `Transformer` components don't necessarily set the +annotations on the `Doc` (though since 3.1 they can if they are part of the `annotating_components` list in the config). +Instead, we rely on a caching mechanism between the original embedding component and its listener. +Specifically, the produced embeddings are sent to the listeners by calling `listener.receive()` and uniquely +identifying the batch of documents with a `batch_id`. This `receive()` call also sends the appropriate `backprop` +call to ensure that gradients from the downstream component flow back to the trainable `Tok2Vec` or `Transformer` +network. + +We rely on the `nlp` object properly batching the data and sending each batch through the pipeline in sequence, +which means that only one such batch needs to be kept in memory for each listener. +When the downstream component runs and the listener should produce embeddings, it accesses the batch in memory, +runs the backpropagation, and returns the results and the gradients. + +There are two ways in which this mechanism can fail, both are detected by `verify_inputs()`: + +- `E953` if a different batch is in memory than the requested one - signaling some kind of out-of-sync state of the + training pipeline. +- `E954` if no batch is in memory at all - signaling that the pipeline is probably not set up correctly. + +#### Training with multiple listeners + +One `Tok2Vec` or `Transformer` component may be listened to by several downstream components, e.g. +a tagger and a parser could be sharing the same embeddings. In this case, we need to be careful about how we do +the backpropagation. When the `Tok2Vec` or `Transformer` sends out data to the listener with `receive()`, they will +send an `accumulate_gradient` function call to all listeners, except the last one. This function will keep track +of the gradients received so far. Only the final listener in the pipeline will get an actual `backprop` call that +will initiate the backpropagation of the `tok2vec` or `transformer` model with the accumulated gradients. + +### 3C. Frozen components + +The listener pattern can get particularly tricky in combination with frozen components. To detect components +with listeners that are not frozen consistently, `init_nlp()` (which is called by `spacy train`) goes through +the listeners and their upstream components and warns in two scenarios. + +#### The Tok2Vec or Transformer is frozen + +If the `Tok2Vec` or `Transformer` was already trained, +e.g. by [pretraining](https://spacy.io/usage/embeddings-transformers#pretraining), +it could be a valid use-case to freeze the embedding architecture and only train downstream components such +as a tagger or a parser. This used to be impossible before 3.1, but has become supported since then by putting the +embedding component in the [`annotating_components`](https://spacy.io/usage/training#annotating-components) +list of the config. This works like any other "annotating component" because it relies on the `Doc` attributes. + +However, if the `Tok2Vec` or `Transformer` is frozen, and not present in `annotating_components`, and a related +listener isn't frozen, then a `W086` warning is shown and further training of the pipeline will likely end with `E954`. + +#### The upstream component is frozen + +If an upstream component is frozen but the underlying `Tok2Vec` or `Transformer` isn't, the performance of +the upstream component will be degraded after training. In this case, a `W087` warning is shown, explaining +how to use the `replace_listeners` functionality to prevent this problem. + +## 4. Replacing listener with standalone + +The [`replace_listeners`](https://spacy.io/api/language#replace_listeners) functionality changes the architecture +of a downstream component from using a listener pattern to a standalone `tok2vec` or `transformer` layer, +effectively making the downstream component independent of any other components in the pipeline. +It is implemented by `nlp.replace_listeners()` and typically executed by `nlp.from_config()`. +First, it fetches the original `Model` of the original component that creates the embeddings: + +``` +tok2vec = self.get_pipe(tok2vec_name) +tok2vec_model = tok2vec.model +``` + +Which is either a [`Tok2Vec` model](https://github.com/explosion/spaCy/blob/master/spacy/ml/models/tok2vec.py) or a +[`TransformerModel`](https://github.com/explosion/spacy-transformers/blob/master/spacy_transformers/layers/transformer_model.py). + +In the case of the `tok2vec`, this model can be copied as-is into the configuration and architecture of the +downstream component. However, for the `transformer`, this doesn't work. +The reason is that the `TransformerListener` architecture chains the listener with +[`trfs2arrays`](https://github.com/explosion/spacy-transformers/blob/master/spacy_transformers/layers/trfs2arrays.py): + +``` +model = chain( + TransformerListener(upstream_name=upstream) + trfs2arrays(pooling, grad_factor), +) +``` + +but the standalone `Tok2VecTransformer` has an additional `split_trf_batch` chained inbetween the model +and `trfs2arrays`: + +``` +model = chain( + TransformerModel(name, get_spans, tokenizer_config), + split_trf_batch(), + trfs2arrays(pooling, grad_factor), +) +``` + +So you can't just take the model from the listener, and drop that into the component internally. You need to +adjust the model and the config. To facilitate this, `nlp.replace_listeners()` will check whether additional +[functions](https://github.com/explosion/spacy-transformers/blob/master/spacy_transformers/layers/_util.py) are +[defined](https://github.com/explosion/spacy-transformers/blob/master/spacy_transformers/layers/transformer_model.py) +in `model.attrs`, and if so, it will essentially call these to make the appropriate changes: + +``` +replace_func = tok2vec_model.attrs["replace_listener_cfg"] +new_config = replace_func(tok2vec_cfg["model"], pipe_cfg["model"]["tok2vec"]) +... +new_model = tok2vec_model.attrs["replace_listener"](new_model) +``` + +The new config and model are then properly stored on the `nlp` object. +Note that this functionality (running the replacement for a transformer listener) was broken prior to +`spacy-transformers` 1.0.5. From 1a86d545af46e5e5b67fdb22b4859a91757d9a72 Mon Sep 17 00:00:00 2001 From: Ines Montani Date: Tue, 31 Aug 2021 10:03:38 +1000 Subject: [PATCH 32/70] Update references to contributor agreement [ci skip] --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CONTRIBUTING.md | 11 ----------- 2 files changed, 1 insertion(+), 12 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ec11b78bd..b48b2c51b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -14,6 +14,6 @@ or new feature, or a change to the documentation? --> ## Checklist -- [ ] I have submitted the spaCy Contributor Agreement. +- [ ] I confirm that I have the right to submit this contribution under the project's MIT license. - [ ] I ran the tests, and all new and existing tests passed. - [ ] My changes don't require a change to the documentation, or if they do, I've added all required information. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b6a38eef..3e2b3927b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -140,17 +140,6 @@ Changes to `.py` files will be effective immediately. 📖 **For more details and instructions, see the documentation on [compiling spaCy from source](https://spacy.io/usage/#source) and the [quickstart widget](https://spacy.io/usage/#section-quickstart) to get the right commands for your platform and Python version.** -### Contributor agreement - -If you've made a contribution to spaCy, you should fill in the -[spaCy contributor agreement](.github/CONTRIBUTOR_AGREEMENT.md) to ensure that -your contribution can be used across the project. If you agree to be bound by -the terms of the agreement, fill in the [template](.github/CONTRIBUTOR_AGREEMENT.md) -and include it with your pull request, or submit it separately to -[`.github/contributors/`](/.github/contributors). The name of the file should be -your GitHub username, with the extension `.md`. For example, the user -example_user would create the file `.github/contributors/example_user.md`. - ### Fixing bugs When fixing a bug, first create an From 1dd69be1f17682ea6662225457efd3054f9b6441 Mon Sep 17 00:00:00 2001 From: Davide Fiocco Date: Tue, 31 Aug 2021 10:55:44 +0200 Subject: [PATCH 33/70] Fix point typo on docbin docs (#9097) --- website/docs/api/docbin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/api/docbin.md b/website/docs/api/docbin.md index 3625ed790..b1d1798ba 100644 --- a/website/docs/api/docbin.md +++ b/website/docs/api/docbin.md @@ -16,7 +16,7 @@ document from the `DocBin`. The serialization format is gzipped msgpack, where the msgpack object has the following structure: ```python -### msgpack object structrue +### msgpack object structure { "version": str, # DocBin version number "attrs": List[uint64], # e.g. [TAG, HEAD, ENT_IOB, ENT_TYPE] From a17b06d18b9cdc74d455c2cce8f21fb522367ae9 Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Tue, 31 Aug 2021 12:53:51 +0200 Subject: [PATCH 34/70] allow typer 0.4 (#9089) --- requirements.txt | 2 +- setup.cfg | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index 74dd11375..49f49ad63 100644 --- a/requirements.txt +++ b/requirements.txt @@ -9,7 +9,7 @@ murmurhash>=0.28.0,<1.1.0 wasabi>=0.8.1,<1.1.0 srsly>=2.4.1,<3.0.0 catalogue>=2.0.6,<2.1.0 -typer>=0.3.0,<0.4.0 +typer>=0.3.0,<0.5.0 pathy>=0.3.5 # Third party dependencies numpy>=1.15.0 diff --git a/setup.cfg b/setup.cfg index 06ab3ca40..9517acfc2 100644 --- a/setup.cfg +++ b/setup.cfg @@ -49,7 +49,7 @@ install_requires = wasabi>=0.8.1,<1.1.0 srsly>=2.4.1,<3.0.0 catalogue>=2.0.6,<2.1.0 - typer>=0.3.0,<0.4.0 + typer>=0.3.0,<0.5.0 pathy>=0.3.5 # Third-party dependencies tqdm>=4.38.0,<5.0.0 From f803a8457177f9fb852467f1692f0db1547b58a3 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Wed, 1 Sep 2021 14:17:42 +0900 Subject: [PATCH 35/70] Fix inference of epoch_resume (#9084) * Fix inference of epoch_resume When an epoch_resume value is not specified individually, it can often be inferred from the filename. The value inference code was there but the value wasn't passed back to the training loop. This also adds a specific error in the case where no epoch_resume value is provided and it can't be inferred from the filename. * Add new error * Always use the epoch resume value if specified Before this the value in the filename was used if found --- spacy/errors.py | 2 ++ spacy/training/pretrain.py | 26 ++++++++++++++++---------- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/spacy/errors.py b/spacy/errors.py index a206826ff..0e1a294c3 100644 --- a/spacy/errors.py +++ b/spacy/errors.py @@ -869,6 +869,8 @@ class Errors: E1019 = ("`noun_chunks` requires the pos tagging, which requires a " "statistical model to be installed and loaded. For more info, see " "the documentation:\nhttps://spacy.io/usage/models") + E1020 = ("No `epoch_resume` value specified and could not infer one from " + "filename. Specify an epoch to resume from.") # Deprecated model shortcuts, only used in errors and warnings diff --git a/spacy/training/pretrain.py b/spacy/training/pretrain.py index 6d7850212..0228f2947 100644 --- a/spacy/training/pretrain.py +++ b/spacy/training/pretrain.py @@ -41,10 +41,11 @@ def pretrain( optimizer = P["optimizer"] # Load in pretrained weights to resume from if resume_path is not None: - _resume_model(model, resume_path, epoch_resume, silent=silent) + epoch_resume = _resume_model(model, resume_path, epoch_resume, silent=silent) else: # Without '--resume-path' the '--epoch-resume' argument is ignored epoch_resume = 0 + objective = model.attrs["loss"] # TODO: move this to logger function? tracker = ProgressTracker(frequency=10000) @@ -93,20 +94,25 @@ def ensure_docs(examples_or_docs: Iterable[Union[Doc, Example]]) -> List[Doc]: def _resume_model( model: Model, resume_path: Path, epoch_resume: int, silent: bool = True -) -> None: +) -> int: msg = Printer(no_print=silent) msg.info(f"Resume training tok2vec from: {resume_path}") with resume_path.open("rb") as file_: weights_data = file_.read() model.get_ref("tok2vec").from_bytes(weights_data) - # Parse the epoch number from the given weight file - model_name = re.search(r"model\d+\.bin", str(resume_path)) - if model_name: - # Default weight file name so read epoch_start from it by cutting off 'model' and '.bin' - epoch_resume = int(model_name.group(0)[5:][:-4]) + 1 - msg.info(f"Resuming from epoch: {epoch_resume}") - else: - msg.info(f"Resuming from epoch: {epoch_resume}") + + if epoch_resume is None: + # Parse the epoch number from the given weight file + model_name = re.search(r"model\d+\.bin", str(resume_path)) + if model_name: + # Default weight file name so read epoch_start from it by cutting off 'model' and '.bin' + epoch_resume = int(model_name.group(0)[5:][:-4]) + 1 + else: + # No epoch given and couldn't infer it + raise ValueError(Errors.E1020) + + msg.info(f"Resuming from epoch: {epoch_resume}") + return epoch_resume def make_update( From ba6a37d3588f3d532733e5f2df449aeecd3f47fa Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Wed, 1 Sep 2021 19:09:39 +0900 Subject: [PATCH 36/70] Document Assigned Attributes of Pipeline Components (#9041) * Add textcat docs * Add NER docs * Add Entity Linker docs * Add assigned fields docs for the tagger This also adds a preamble, since there wasn't one. * Add morphologizer docs * Add dependency parser docs * Update entityrecognizer docs This is a little weird because `Doc.ents` is the only thing assigned to, but it's actually a bidirectional property. * Add token fields for entityrecognizer * Fix section name * Add entity ruler docs * Add lemmatizer docs * Add sentencizer/recognizer docs * Update website/docs/api/entityrecognizer.md Co-authored-by: Adriane Boyd * Update website/docs/api/entityruler.md Co-authored-by: Adriane Boyd * Update website/docs/api/tagger.md Co-authored-by: Adriane Boyd * Update website/docs/api/entityruler.md Co-authored-by: Adriane Boyd * Update type for Doc.ents This was `Tuple[Span, ...]` everywhere but `Tuple[Span]` seems to be correct. * Run prettier * Apply suggestions from code review Co-authored-by: Sofie Van Landeghem * Run prettier * Add transformers section This basically just moves and renames the "custom attributes" section from the bottom of the page to be consistent with "assigned attributes" on other pages. I looked at moving the paragraph just above the section into the section, but it includes the unrelated registry additions, so it seemed better to leave it unchanged. * Make table header consistent Co-authored-by: Adriane Boyd Co-authored-by: Sofie Van Landeghem --- website/docs/api/architectures.md | 4 ++-- website/docs/api/dependencyparser.md | 14 ++++++++++++++ website/docs/api/doc.md | 6 +++--- website/docs/api/entitylinker.md | 10 ++++++++++ website/docs/api/entityrecognizer.md | 18 ++++++++++++++++++ website/docs/api/entityruler.md | 21 +++++++++++++++++++++ website/docs/api/legacy.md | 3 ++- website/docs/api/lemmatizer.md | 9 +++++++++ website/docs/api/morphologizer.md | 10 ++++++++++ website/docs/api/morphology.md | 10 +++++----- website/docs/api/phrasematcher.md | 4 ++-- website/docs/api/scorer.md | 2 +- website/docs/api/sentencerecognizer.md | 10 ++++++++++ website/docs/api/sentencizer.md | 12 +++++++++++- website/docs/api/tagger.md | 15 +++++++++++++++ website/docs/api/textcategorizer.md | 16 ++++++++++++++++ website/docs/api/transformer.md | 26 +++++++++++++------------- website/docs/api/vectors.md | 2 +- website/docs/api/vocab.md | 16 ++++++++-------- 19 files changed, 171 insertions(+), 37 deletions(-) diff --git a/website/docs/api/architectures.md b/website/docs/api/architectures.md index f1a11bbc4..ceeb388ab 100644 --- a/website/docs/api/architectures.md +++ b/website/docs/api/architectures.md @@ -555,8 +555,8 @@ consists of either two or three subnetworks: -[TransitionBasedParser.v1](/api/legacy#TransitionBasedParser_v1) had the exact same signature, -but the `use_upper` argument was `True` by default. +[TransitionBasedParser.v1](/api/legacy#TransitionBasedParser_v1) had the exact +same signature, but the `use_upper` argument was `True` by default. diff --git a/website/docs/api/dependencyparser.md b/website/docs/api/dependencyparser.md index fa02a6f99..c48172a22 100644 --- a/website/docs/api/dependencyparser.md +++ b/website/docs/api/dependencyparser.md @@ -25,6 +25,20 @@ current state. The weights are updated such that the scores assigned to the set of optimal actions is increased, while scores assigned to other actions are decreased. Note that more than one action may be optimal for a given state. +## Assigned Attributes {#assigned-attributes} + +Dependency predictions are assigned to the `Token.dep` and `Token.head` fields. +Beside the dependencies themselves, the parser decides sentence boundaries, +which are saved in `Token.is_sent_start` and accessible via `Doc.sents`. + +| Location | Value | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `Token.dep` | The type of dependency relation (hash). ~~int~~ | +| `Token.dep_` | The type of dependency relation. ~~str~~ | +| `Token.head` | The syntactic parent, or "governor", of this token. ~~Token~~ | +| `Token.is_sent_start` | A boolean value indicating whether the token starts a sentence. After the parser runs this will be `True` or `False` for all tokens. ~~bool~~ | +| `Doc.sents` | An iterator over sentences in the `Doc`, determined by `Token.is_sent_start` values. ~~Iterator[Span]~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes diff --git a/website/docs/api/doc.md b/website/docs/api/doc.md index 0b5ef56c0..e1f18963b 100644 --- a/website/docs/api/doc.md +++ b/website/docs/api/doc.md @@ -571,9 +571,9 @@ objects, if the entity recognizer has been applied. > assert ents[0].text == "Mr. Best" > ``` -| Name | Description | -| ----------- | --------------------------------------------------------------------- | -| **RETURNS** | Entities in the document, one `Span` per entity. ~~Tuple[Span, ...]~~ | +| Name | Description | +| ----------- | ---------------------------------------------------------------- | +| **RETURNS** | Entities in the document, one `Span` per entity. ~~Tuple[Span]~~ | ## Doc.spans {#spans tag="property"} diff --git a/website/docs/api/entitylinker.md b/website/docs/api/entitylinker.md index 2994d934b..bbc8f3942 100644 --- a/website/docs/api/entitylinker.md +++ b/website/docs/api/entitylinker.md @@ -16,6 +16,16 @@ plausible candidates from that `KnowledgeBase` given a certain textual mention, and a machine learning model to pick the right candidate, given the local context of the mention. +## Assigned Attributes {#assigned-attributes} + +Predictions, in the form of knowledge base IDs, will be assigned to +`Token.ent_kb_id_`. + +| Location | Value | +| ------------------ | --------------------------------- | +| `Token.ent_kb_id` | Knowledge base ID (hash). ~~int~~ | +| `Token.ent_kb_id_` | Knowledge base ID. ~~str~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes diff --git a/website/docs/api/entityrecognizer.md b/website/docs/api/entityrecognizer.md index 601b644c1..ba7022c14 100644 --- a/website/docs/api/entityrecognizer.md +++ b/website/docs/api/entityrecognizer.md @@ -20,6 +20,24 @@ your entities will be close to their initial tokens. If your entities are long and characterized by tokens in their middle, the component will likely not be a good fit for your task. +## Assigned Attributes {#assigned-attributes} + +Predictions will be saved to `Doc.ents` as a tuple. Each label will also be +reflected to each underlying token, where it is saved in the `Token.ent_type` +and `Token.ent_iob` fields. Note that by definition each token can only have one +label. + +When setting `Doc.ents` to create training data, all the spans must be valid and +non-overlapping, or an error will be thrown. + +| Location | Value | +| ----------------- | ----------------------------------------------------------------- | +| `Doc.ents` | The annotated spans. ~~Tuple[Span]~~ | +| `Token.ent_iob` | An enum encoding of the IOB part of the named entity tag. ~~int~~ | +| `Token.ent_iob_` | The IOB part of the named entity tag. ~~str~~ | +| `Token.ent_type` | The label part of the named entity tag (hash). ~~int~~ | +| `Token.ent_type_` | The label part of the named entity tag. ~~str~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes diff --git a/website/docs/api/entityruler.md b/website/docs/api/entityruler.md index 93b5da45a..48c279914 100644 --- a/website/docs/api/entityruler.md +++ b/website/docs/api/entityruler.md @@ -15,6 +15,27 @@ used on its own to implement a purely rule-based entity recognition system. For usage examples, see the docs on [rule-based entity recognition](/usage/rule-based-matching#entityruler). +## Assigned Attributes {#assigned-attributes} + +This component assigns predictions basically the same way as the +[`EntityRecognizer`](/api/entityrecognizer). + +Predictions can be accessed under `Doc.ents` as a tuple. Each label will also be +reflected in each underlying token, where it is saved in the `Token.ent_type` +and `Token.ent_iob` fields. Note that by definition each token can only have one +label. + +When setting `Doc.ents` to create training data, all the spans must be valid and +non-overlapping, or an error will be thrown. + +| Location | Value | +| ----------------- | ----------------------------------------------------------------- | +| `Doc.ents` | The annotated spans. ~~Tuple[Span]~~ | +| `Token.ent_iob` | An enum encoding of the IOB part of the named entity tag. ~~int~~ | +| `Token.ent_iob_` | The IOB part of the named entity tag. ~~str~~ | +| `Token.ent_type` | The label part of the named entity tag (hash). ~~int~~ | +| `Token.ent_type_` | The label part of the named entity tag. ~~str~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes diff --git a/website/docs/api/legacy.md b/website/docs/api/legacy.md index 02b376780..916a5bf7f 100644 --- a/website/docs/api/legacy.md +++ b/website/docs/api/legacy.md @@ -105,7 +105,8 @@ and residual connections. ### spacy.TransitionBasedParser.v1 {#TransitionBasedParser_v1} -Identical to [`spacy.TransitionBasedParser.v2`](/api/architectures#TransitionBasedParser) +Identical to +[`spacy.TransitionBasedParser.v2`](/api/architectures#TransitionBasedParser) except the `use_upper` was set to `True` by default. ### spacy.TextCatEnsemble.v1 {#TextCatEnsemble_v1} diff --git a/website/docs/api/lemmatizer.md b/website/docs/api/lemmatizer.md index 279821e71..8cb869f64 100644 --- a/website/docs/api/lemmatizer.md +++ b/website/docs/api/lemmatizer.md @@ -31,6 +31,15 @@ available in the pipeline and runs _before_ the lemmatizer. +## Assigned Attributes {#assigned-attributes} + +Lemmas generated by rules or predicted will be saved to `Token.lemma`. + +| Location | Value | +| -------------- | ------------------------- | +| `Token.lemma` | The lemma (hash). ~~int~~ | +| `Token.lemma_` | The lemma. ~~str~~ | + ## Config and implementation The default config is defined by the pipeline component factory and describes diff --git a/website/docs/api/morphologizer.md b/website/docs/api/morphologizer.md index d2dd28ac2..00af83e6f 100644 --- a/website/docs/api/morphologizer.md +++ b/website/docs/api/morphologizer.md @@ -15,6 +15,16 @@ coarse-grained POS tags following the Universal Dependencies [FEATS](https://universaldependencies.org/format.html#morphological-annotation) annotation guidelines. +## Assigned Attributes {#assigned-attributes} + +Predictions are saved to `Token.morph` and `Token.pos`. + +| Location | Value | +| ------------- | ----------------------------------------- | +| `Token.pos` | The UPOS part of speech (hash). ~~int~~ | +| `Token.pos_` | The UPOS part of speech. ~~str~~ | +| `Token.morph` | Morphological features. ~~MorphAnalysis~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes diff --git a/website/docs/api/morphology.md b/website/docs/api/morphology.md index 565e520b5..20fcd1a40 100644 --- a/website/docs/api/morphology.md +++ b/website/docs/api/morphology.md @@ -105,11 +105,11 @@ representation. ## Attributes {#attributes} -| Name | Description | -| ------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- | -| `FEATURE_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) feature separator. Default is ` | `. ~~str~~ | -| `FIELD_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) field separator. Default is `=`. ~~str~~ | -| `VALUE_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) value separator. Default is `,`. ~~str~~ | +| Name | Description | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `FEATURE_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) feature separator. Default is `|`. ~~str~~ | +| `FIELD_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) field separator. Default is `=`. ~~str~~ | +| `VALUE_SEP` | The [FEATS](https://universaldependencies.org/format.html#morphological-annotation) value separator. Default is `,`. ~~str~~ | ## MorphAnalysis {#morphanalysis tag="class" source="spacy/tokens/morphanalysis.pyx"} diff --git a/website/docs/api/phrasematcher.md b/website/docs/api/phrasematcher.md index 4a5fb6042..71ee4b7d1 100644 --- a/website/docs/api/phrasematcher.md +++ b/website/docs/api/phrasematcher.md @@ -149,8 +149,8 @@ patterns = [nlp("health care reform"), nlp("healthcare reform")] | Name | Description | -| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -| `match_id` | An ID for the thing you're matching. ~~str~~ | | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `match_id` | An ID for the thing you're matching. ~~str~~ | | | `docs` | `Doc` objects of the phrases to match. ~~List[Doc]~~ | | _keyword-only_ | | | `on_match` | Callback function to act on matches. Takes the arguments `matcher`, `doc`, `i` and `matches`. ~~Optional[Callable[[Matcher, Doc, int, List[tuple], Any]]~~ | diff --git a/website/docs/api/scorer.md b/website/docs/api/scorer.md index ad908f204..c8163091f 100644 --- a/website/docs/api/scorer.md +++ b/website/docs/api/scorer.md @@ -80,7 +80,7 @@ Docs with `has_unknown_spaces` are skipped during scoring. > ``` | Name | Description | -| ----------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| ----------- | ------------------------------------------------------------------------------------------------------------------- | | `examples` | The `Example` objects holding both the predictions and the correct gold-standard annotations. ~~Iterable[Example]~~ | | **RETURNS** | `Dict` | A dictionary containing the scores `token_acc`, `token_p`, `token_r`, `token_f`. ~~Dict[str, float]]~~ | diff --git a/website/docs/api/sentencerecognizer.md b/website/docs/api/sentencerecognizer.md index e82a4bef6..8d8e57319 100644 --- a/website/docs/api/sentencerecognizer.md +++ b/website/docs/api/sentencerecognizer.md @@ -12,6 +12,16 @@ api_trainable: true A trainable pipeline component for sentence segmentation. For a simpler, rule-based strategy, see the [`Sentencizer`](/api/sentencizer). +## Assigned Attributes {#assigned-attributes} + +Predicted values will be assigned to `Token.is_sent_start`. The resulting +sentences can be accessed using `Doc.sents`. + +| Location | Value | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `Token.is_sent_start` | A boolean value indicating whether the token starts a sentence. This will be either `True` or `False` for all tokens. ~~bool~~ | +| `Doc.sents` | An iterator over sentences in the `Doc`, determined by `Token.is_sent_start` values. ~~Iterator[Span]~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes diff --git a/website/docs/api/sentencizer.md b/website/docs/api/sentencizer.md index 75a253fc0..ef2465c27 100644 --- a/website/docs/api/sentencizer.md +++ b/website/docs/api/sentencizer.md @@ -13,6 +13,16 @@ performed by the [`DependencyParser`](/api/dependencyparser), so the `Sentencizer` lets you implement a simpler, rule-based strategy that doesn't require a statistical model to be loaded. +## Assigned Attributes {#assigned-attributes} + +Calculated values will be assigned to `Token.is_sent_start`. The resulting +sentences can be accessed using `Doc.sents`. + +| Location | Value | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `Token.is_sent_start` | A boolean value indicating whether the token starts a sentence. This will be either `True` or `False` for all tokens. ~~bool~~ | +| `Doc.sents` | An iterator over sentences in the `Doc`, determined by `Token.is_sent_start` values. ~~Iterator[Span]~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes @@ -28,7 +38,7 @@ how the component should be configured. You can override its settings via the > ``` | Setting | Description | -| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `punct_chars` | Optional custom list of punctuation characters that mark sentence ends. See below for defaults if not set. Defaults to `None`. ~~Optional[List[str]]~~ | `None` | ```python diff --git a/website/docs/api/tagger.md b/website/docs/api/tagger.md index 3002aff7b..f34456b0c 100644 --- a/website/docs/api/tagger.md +++ b/website/docs/api/tagger.md @@ -8,6 +8,21 @@ api_string_name: tagger api_trainable: true --- +A trainable pipeline component to predict part-of-speech tags for any +part-of-speech tag set. + +In the pre-trained pipelines, the tag schemas vary by language; see the +[individual model pages](/models) for details. + +## Assigned Attributes {#assigned-attributes} + +Predictions are assigned to `Token.tag`. + +| Location | Value | +| ------------ | ---------------------------------- | +| `Token.tag` | The part of speech (hash). ~~int~~ | +| `Token.tag_` | The part of speech. ~~str~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes diff --git a/website/docs/api/textcategorizer.md b/website/docs/api/textcategorizer.md index 923da0048..62a921d02 100644 --- a/website/docs/api/textcategorizer.md +++ b/website/docs/api/textcategorizer.md @@ -29,6 +29,22 @@ only. +## Assigned Attributes {#assigned-attributes} + +Predictions will be saved to `doc.cats` as a dictionary, where the key is the +name of the category and the value is a score between 0 and 1 (inclusive). For +`textcat` (exclusive categories), the scores will sum to 1, while for +`textcat_multilabel` there is no particular guarantee about their sum. + +Note that when assigning values to create training data, the score of each +category must be 0 or 1. Using other values, for example to create a document +that is a little bit in category A and a little bit in category B, is not +supported. + +| Location | Value | +| ---------- | ------------------------------------- | +| `Doc.cats` | Category scores. ~~Dict[str, float]~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes diff --git a/website/docs/api/transformer.md b/website/docs/api/transformer.md index 569fcfbd4..6e68ac599 100644 --- a/website/docs/api/transformer.md +++ b/website/docs/api/transformer.md @@ -38,12 +38,21 @@ attributes. We also calculate an alignment between the word-piece tokens and the spaCy tokenization, so that we can use the last hidden states to set the `Doc.tensor` attribute. When multiple word-piece tokens align to the same spaCy token, the spaCy token receives the sum of their values. To access the values, -you can use the custom [`Doc._.trf_data`](#custom-attributes) attribute. The +you can use the custom [`Doc._.trf_data`](#assigned-attributes) attribute. The package also adds the function registries [`@span_getters`](#span_getters) and [`@annotation_setters`](#annotation_setters) with several built-in registered functions. For more details, see the [usage documentation](/usage/embeddings-transformers). +## Assigned Attributes {#assigned-attributes} + +The component sets the following +[custom extension attribute](/usage/processing-pipeline#custom-components-attributes): + +| Location | Value | +| ---------------- | ------------------------------------------------------------------------ | +| `Doc._.trf_data` | Transformer tokens and outputs for the `Doc` object. ~~TransformerData~~ | + ## Config and implementation {#config} The default config is defined by the pipeline component factory and describes @@ -98,7 +107,7 @@ https://github.com/explosion/spacy-transformers/blob/master/spacy_transformers/p Construct a `Transformer` component. One or more subsequent spaCy components can use the transformer outputs as features in its model, with gradients backpropagated to the single shared weights. The activations from the -transformer are saved in the [`Doc._.trf_data`](#custom-attributes) extension +transformer are saved in the [`Doc._.trf_data`](#assigned-attributes) extension attribute. You can also provide a callback to set additional annotations. In your application, you would normally use a shortcut for this and instantiate the component using its string name and [`nlp.add_pipe`](/api/language#create_pipe). @@ -205,7 +214,7 @@ modifying them. Assign the extracted features to the `Doc` objects. By default, the [`TransformerData`](/api/transformer#transformerdata) object is written to the -[`Doc._.trf_data`](#custom-attributes) attribute. Your `set_extra_annotations` +[`Doc._.trf_data`](#assigned-attributes) attribute. Your `set_extra_annotations` callback is then called, if provided. > #### Example @@ -383,7 +392,7 @@ are wrapped into the [FullTransformerBatch](/api/transformer#fulltransformerbatch) object. The `FullTransformerBatch` then splits out the per-document data, which is handled by this class. Instances of this class are typically assigned to the -[`Doc._.trf_data`](/api/transformer#custom-attributes) extension attribute. +[`Doc._.trf_data`](/api/transformer#assigned-attributes) extension attribute. | Name | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -549,12 +558,3 @@ The following built-in functions are available: | Name | Description | | ---------------------------------------------- | ------------------------------------- | | `spacy-transformers.null_annotation_setter.v1` | Don't set any additional annotations. | - -## Custom attributes {#custom-attributes} - -The component sets the following -[custom extension attributes](/usage/processing-pipeline#custom-components-attributes): - -| Name | Description | -| ---------------- | ------------------------------------------------------------------------ | -| `Doc._.trf_data` | Transformer tokens and outputs for the `Doc` object. ~~TransformerData~~ | diff --git a/website/docs/api/vectors.md b/website/docs/api/vectors.md index 598abe681..1a7f7a3f5 100644 --- a/website/docs/api/vectors.md +++ b/website/docs/api/vectors.md @@ -321,7 +321,7 @@ performed in chunks to avoid consuming too much memory. You can set the > ``` | Name | Description | -| -------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| -------------- | --------------------------------------------------------------------------- | | `queries` | An array with one or more vectors. ~~numpy.ndarray~~ | | _keyword-only_ | | | `batch_size` | The batch size to use. Default to `1024`. ~~int~~ | diff --git a/website/docs/api/vocab.md b/website/docs/api/vocab.md index 320ad5605..40a3c3b22 100644 --- a/website/docs/api/vocab.md +++ b/website/docs/api/vocab.md @@ -21,14 +21,14 @@ Create the vocabulary. > vocab = Vocab(strings=["hello", "world"]) > ``` -| Name | Description | -| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `lex_attr_getters` | A dictionary mapping attribute IDs to functions to compute them. Defaults to `None`. ~~Optional[Dict[str, Callable[[str], Any]]]~~ | -| `strings` | A [`StringStore`](/api/stringstore) that maps strings to hash values, and vice versa, or a list of strings. ~~Union[List[str], StringStore]~~ | -| `lookups` | A [`Lookups`](/api/lookups) that stores the `lexeme_norm` and other large lookup tables. Defaults to `None`. ~~Optional[Lookups]~~ | -| `oov_prob` | The default OOV probability. Defaults to `-20.0`. ~~float~~ | -| `vectors_name` 2.2 | A name to identify the vectors table. ~~str~~ | -| `writing_system` | A dictionary describing the language's writing system. Typically provided by [`Language.Defaults`](/api/language#defaults). ~~Dict[str, Any]~~ | +| Name | Description | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `lex_attr_getters` | A dictionary mapping attribute IDs to functions to compute them. Defaults to `None`. ~~Optional[Dict[str, Callable[[str], Any]]]~~ | +| `strings` | A [`StringStore`](/api/stringstore) that maps strings to hash values, and vice versa, or a list of strings. ~~Union[List[str], StringStore]~~ | +| `lookups` | A [`Lookups`](/api/lookups) that stores the `lexeme_norm` and other large lookup tables. Defaults to `None`. ~~Optional[Lookups]~~ | +| `oov_prob` | The default OOV probability. Defaults to `-20.0`. ~~float~~ | +| `vectors_name` 2.2 | A name to identify the vectors table. ~~str~~ | +| `writing_system` | A dictionary describing the language's writing system. Typically provided by [`Language.Defaults`](/api/language#defaults). ~~Dict[str, Any]~~ | | `get_noun_chunks` | A function that yields base noun phrases used for [`Doc.noun_chunks`](/api/doc#noun_chunks). ~~Optional[Callable[[Union[Doc, Span], Iterator[Span]]]]~~ | ## Vocab.\_\_len\_\_ {#len tag="method"} From d60b748e3c760c092ed9f8d45ab1a730a5329b73 Mon Sep 17 00:00:00 2001 From: Robyn Speer Date: Wed, 1 Sep 2021 16:52:08 -0400 Subject: [PATCH 37/70] Fix surprises when asking for the root of a git repo (#9074) * Fix surprises when asking for the root of a git repo In the case of the first asset I wanted to get from git, the data I wanted was the entire repository. I tried leaving "path" blank, which gave a less-than-helpful error, and then I tried `path: "/"`, which started copying my entire filesystem into the project. The path I should have used was "". I've made two changes to make this smoother for others: - The 'path' within a git clone defaults to "" - If the path points outside of the tmpdir that the git clone goes into, we fail with an error Signed-off-by: Elia Robyn Speer * use a descriptive error instead of a default plus some minor fixes from PR review Signed-off-by: Elia Robyn Speer * check for None values in assets Signed-off-by: Elia Robyn Speer Co-authored-by: Elia Robyn Speer --- spacy/cli/_util.py | 29 ++++++++++++++++++++++++++--- spacy/cli/project/assets.py | 4 ++++ spacy/tests/test_cli.py | 16 ++++++++++++++++ website/docs/usage/projects.md | 2 +- 4 files changed, 47 insertions(+), 4 deletions(-) diff --git a/spacy/cli/_util.py b/spacy/cli/_util.py index ed1e840a5..127bba55a 100644 --- a/spacy/cli/_util.py +++ b/spacy/cli/_util.py @@ -397,7 +397,11 @@ def git_checkout( run_command(cmd, capture=True) # We need Path(name) to make sure we also support subdirectories try: - shutil.copytree(str(tmp_dir / Path(subpath)), str(dest)) + source_path = tmp_dir / Path(subpath) + if not is_subpath_of(tmp_dir, source_path): + err = f"'{subpath}' is a path outside of the cloned repository." + msg.fail(err, repo, exits=1) + shutil.copytree(str(source_path), str(dest)) except FileNotFoundError: err = f"Can't clone {subpath}. Make sure the directory exists in the repo (branch '{branch}')" msg.fail(err, repo, exits=1) @@ -445,8 +449,14 @@ def git_sparse_checkout(repo, subpath, dest, branch): # And finally, we can checkout our subpath cmd = f"git -C {tmp_dir} checkout {branch} {subpath}" run_command(cmd, capture=True) - # We need Path(name) to make sure we also support subdirectories - shutil.move(str(tmp_dir / Path(subpath)), str(dest)) + + # Get a subdirectory of the cloned path, if appropriate + source_path = tmp_dir / Path(subpath) + if not is_subpath_of(tmp_dir, source_path): + err = f"'{subpath}' is a path outside of the cloned repository." + msg.fail(err, repo, exits=1) + + shutil.move(str(source_path), str(dest)) def get_git_version( @@ -477,6 +487,19 @@ def _http_to_git(repo: str) -> str: return repo +def is_subpath_of(parent, child): + """ + Check whether `child` is a path contained within `parent`. + """ + # Based on https://stackoverflow.com/a/37095733 . + + # In Python 3.9, the `Path.is_relative_to()` method will supplant this, so + # we can stop using crusty old os.path functions. + parent_realpath = os.path.realpath(parent) + child_realpath = os.path.realpath(child) + return os.path.commonpath([parent_realpath, child_realpath]) == parent_realpath + + def string_to_list(value: str, intify: bool = False) -> Union[List[str], List[int]]: """Parse a comma-separated string to a list and account for various formatting options. Mostly used to handle CLI arguments that take a list of diff --git a/spacy/cli/project/assets.py b/spacy/cli/project/assets.py index b49e18608..efa4d637a 100644 --- a/spacy/cli/project/assets.py +++ b/spacy/cli/project/assets.py @@ -59,6 +59,10 @@ def project_assets(project_dir: Path, *, sparse_checkout: bool = False) -> None: shutil.rmtree(dest) else: dest.unlink() + if "repo" not in asset["git"] or asset["git"]["repo"] is None: + msg.fail("A git asset must include 'repo', the repository address.", exits=1) + if "path" not in asset["git"] or asset["git"]["path"] is None: + msg.fail("A git asset must include 'path' - use \"\" to get the entire repository.", exits=1) git_checkout( asset["git"]["repo"], asset["git"]["path"], diff --git a/spacy/tests/test_cli.py b/spacy/tests/test_cli.py index e84159b64..ae4cec17d 100644 --- a/spacy/tests/test_cli.py +++ b/spacy/tests/test_cli.py @@ -9,6 +9,7 @@ from spacy.cli import info from spacy.cli.init_config import init_config, RECOMMENDATIONS from spacy.cli._util import validate_project_commands, parse_config_overrides from spacy.cli._util import load_project_config, substitute_project_variables +from spacy.cli._util import is_subpath_of from spacy.cli._util import string_to_list from spacy import about from spacy.util import get_minor_version @@ -542,3 +543,18 @@ def test_get_third_party_dependencies_runs(): # Test with component factory based on Cython module nlp.add_pipe("tagger") assert get_third_party_dependencies(nlp.config) == [] + + +@pytest.mark.parametrize( + "parent,child,expected", + [ + ("/tmp", "/tmp", True), + ("/tmp", "/", False), + ("/tmp", "/tmp/subdir", True), + ("/tmp", "/tmpdir", False), + ("/tmp", "/tmp/subdir/..", True), + ("/tmp", "/tmp/..", False) + ], +) +def test_is_subpath_of(parent, child, expected): + assert is_subpath_of(parent, child) == expected diff --git a/website/docs/usage/projects.md b/website/docs/usage/projects.md index a646989a5..6f6cef7c8 100644 --- a/website/docs/usage/projects.md +++ b/website/docs/usage/projects.md @@ -291,7 +291,7 @@ files you need and not the whole repo. | Name | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dest` | The destination path to save the downloaded asset to (relative to the project directory), including the file name. | -| `git` | `repo`: The URL of the repo to download from.
`path`: Path of the file or directory to download, relative to the repo root.
`branch`: The branch to download from. Defaults to `"master"`. | +| `git` | `repo`: The URL of the repo to download from.
`path`: Path of the file or directory to download, relative to the repo root. "" specifies the root directory.
`branch`: The branch to download from. Defaults to `"master"`. | | `checksum` | Optional checksum of the file. If provided, it will be used to verify that the file matches and downloads will be skipped if a local file with the same checksum already exists. | | `description` | Optional asset description, used in [auto-generated docs](#custom-docs). | From 8895e3c9ad57628743d87ace769f911c2e873d45 Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Thu, 2 Sep 2021 09:26:33 +0200 Subject: [PATCH 38/70] matcher doc corrections (#9115) * update error message to current UX * clarify uppercase effect * fix docstring --- spacy/matcher/matcher.pyx | 2 +- website/docs/usage/rule-based-matching.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/spacy/matcher/matcher.pyx b/spacy/matcher/matcher.pyx index 555766f62..be45dcaad 100644 --- a/spacy/matcher/matcher.pyx +++ b/spacy/matcher/matcher.pyx @@ -340,7 +340,7 @@ cdef find_matches(TokenPatternC** patterns, int n, object doclike, int length, e The "predicates" list contains functions that take a Python list and return a boolean value. It's mostly used for regular expressions. - The "extra_getters" list contains functions that take a Python list and return + The "extensions" list contains functions that take a Python list and return an attr ID. It's mostly used for extension attributes. """ cdef vector[PatternStateC] states diff --git a/website/docs/usage/rule-based-matching.md b/website/docs/usage/rule-based-matching.md index 81c838584..74bb10304 100644 --- a/website/docs/usage/rule-based-matching.md +++ b/website/docs/usage/rule-based-matching.md @@ -429,7 +429,7 @@ matcher.add("HelloWorld", [pattern]) # 🚨 Raises an error: # MatchPatternError: Invalid token patterns for matcher rule 'HelloWorld' # Pattern 0: -# - Additional properties are not allowed ('CASEINSENSITIVE' was unexpected) [2] +# - [pattern -> 2 -> CASEINSENSITIVE] extra fields not permitted ``` @@ -438,7 +438,8 @@ matcher.add("HelloWorld", [pattern]) To move on to a more realistic example, let's say you're working with a large corpus of blog articles, and you want to match all mentions of "Google I/O" (which spaCy tokenizes as `['Google', 'I', '/', 'O'`]). To be safe, you only -match on the uppercase versions, in case someone has written it as "Google i/o". +match on the uppercase versions, avoiding matches with phrases such as "Google +i/o". ```python ### {executable="true"} From ca93504660156ce21b6f795831fd200a530ea832 Mon Sep 17 00:00:00 2001 From: Kevin Humphreys Date: Thu, 2 Sep 2021 06:58:05 -0400 Subject: [PATCH 39/70] Pass alignments to Matcher callbacks (#9001) * pass alignments to callbacks * refactor for single callback loop * Update spacy/matcher/matcher.pyx Co-authored-by: Sofie Van Landeghem --- spacy/matcher/matcher.pyx | 31 +++++++++++-------------- spacy/tests/matcher/test_matcher_api.py | 10 ++++++++ 2 files changed, 24 insertions(+), 17 deletions(-) diff --git a/spacy/matcher/matcher.pyx b/spacy/matcher/matcher.pyx index be45dcaad..05c55c9a7 100644 --- a/spacy/matcher/matcher.pyx +++ b/spacy/matcher/matcher.pyx @@ -281,28 +281,19 @@ cdef class Matcher: final_matches.append((key, *match)) # Mark tokens that have matched memset(&matched[start], 1, span_len * sizeof(matched[0])) - if with_alignments: - final_matches_with_alignments = final_matches - final_matches = [(key, start, end) for key, start, end, alignments in final_matches] - # perform the callbacks on the filtered set of results - for i, (key, start, end) in enumerate(final_matches): - on_match = self._callbacks.get(key, None) - if on_match is not None: - on_match(self, doc, i, final_matches) if as_spans: - spans = [] - for key, start, end in final_matches: + final_results = [] + for key, start, end, *_ in final_matches: if isinstance(doclike, Span): start += doclike.start end += doclike.start - spans.append(Span(doc, start, end, label=key)) - return spans + final_results.append(Span(doc, start, end, label=key)) elif with_alignments: # convert alignments List[Dict[str, int]] --> List[int] - final_matches = [] # when multiple alignment (belongs to the same length) is found, # keeps the alignment that has largest token_idx - for key, start, end, alignments in final_matches_with_alignments: + final_results = [] + for key, start, end, alignments in final_matches: sorted_alignments = sorted(alignments, key=lambda x: (x['length'], x['token_idx']), reverse=False) alignments = [0] * (end-start) for align in sorted_alignments: @@ -311,10 +302,16 @@ cdef class Matcher: # Since alignments are sorted in order of (length, token_idx) # this overwrites smaller token_idx when they have same length. alignments[align['length']] = align['token_idx'] - final_matches.append((key, start, end, alignments)) - return final_matches + final_results.append((key, start, end, alignments)) + final_matches = final_results # for callbacks else: - return final_matches + final_results = final_matches + # perform the callbacks on the filtered set of results + for i, (key, *_) in enumerate(final_matches): + on_match = self._callbacks.get(key, None) + if on_match is not None: + on_match(self, doc, i, final_matches) + return final_results def _normalize_key(self, key): if isinstance(key, basestring): diff --git a/spacy/tests/matcher/test_matcher_api.py b/spacy/tests/matcher/test_matcher_api.py index a42735eae..c02d65cdf 100644 --- a/spacy/tests/matcher/test_matcher_api.py +++ b/spacy/tests/matcher/test_matcher_api.py @@ -576,6 +576,16 @@ def test_matcher_callback(en_vocab): mock.assert_called_once_with(matcher, doc, 0, matches) +def test_matcher_callback_with_alignments(en_vocab): + mock = Mock() + matcher = Matcher(en_vocab) + pattern = [{"ORTH": "test"}] + matcher.add("Rule", [pattern], on_match=mock) + doc = Doc(en_vocab, words=["This", "is", "a", "test", "."]) + matches = matcher(doc, with_alignments=True) + mock.assert_called_once_with(matcher, doc, 0, matches) + + def test_matcher_span(matcher): text = "JavaScript is good but Java is better" doc = Doc(matcher.vocab, words=text.split()) From 584fae58071a77fa5a329c01ca4ff24258049d06 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 3 Sep 2021 10:47:03 +0200 Subject: [PATCH 40/70] Auto-format code with black (#9130) Co-authored-by: explosion-bot --- spacy/cli/project/assets.py | 9 +++++++-- spacy/cli/project/run.py | 9 ++++++++- spacy/tests/test_cli.py | 2 +- 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/spacy/cli/project/assets.py b/spacy/cli/project/assets.py index efa4d637a..70fcd0ecf 100644 --- a/spacy/cli/project/assets.py +++ b/spacy/cli/project/assets.py @@ -60,9 +60,14 @@ def project_assets(project_dir: Path, *, sparse_checkout: bool = False) -> None: else: dest.unlink() if "repo" not in asset["git"] or asset["git"]["repo"] is None: - msg.fail("A git asset must include 'repo', the repository address.", exits=1) + msg.fail( + "A git asset must include 'repo', the repository address.", exits=1 + ) if "path" not in asset["git"] or asset["git"]["path"] is None: - msg.fail("A git asset must include 'path' - use \"\" to get the entire repository.", exits=1) + msg.fail( + "A git asset must include 'path' - use \"\" to get the entire repository.", + exits=1, + ) git_checkout( asset["git"]["repo"], asset["git"]["path"], diff --git a/spacy/cli/project/run.py b/spacy/cli/project/run.py index ef753d256..3736a6e1c 100644 --- a/spacy/cli/project/run.py +++ b/spacy/cli/project/run.py @@ -73,7 +73,14 @@ def project_run( if subcommand in workflows: msg.info(f"Running workflow '{subcommand}'") for cmd in workflows[subcommand]: - project_run(project_dir, cmd, overrides=overrides, force=force, dry=dry, capture=capture) + project_run( + project_dir, + cmd, + overrides=overrides, + force=force, + dry=dry, + capture=capture, + ) else: cmd = commands[subcommand] for dep in cmd.get("deps", []): diff --git a/spacy/tests/test_cli.py b/spacy/tests/test_cli.py index ae4cec17d..a9525caae 100644 --- a/spacy/tests/test_cli.py +++ b/spacy/tests/test_cli.py @@ -553,7 +553,7 @@ def test_get_third_party_dependencies_runs(): ("/tmp", "/tmp/subdir", True), ("/tmp", "/tmpdir", False), ("/tmp", "/tmp/subdir/..", True), - ("/tmp", "/tmp/..", False) + ("/tmp", "/tmp/..", False), ], ) def test_is_subpath_of(parent, child, expected): From 632d8d4c356f424e0c9c18fc2edc1e75955586ad Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Fri, 3 Sep 2021 13:34:42 +0200 Subject: [PATCH 41/70] bump thinc to 8.0.9 (#9133) --- pyproject.toml | 2 +- requirements.txt | 2 +- setup.cfg | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 07091123a..9dd640185 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ requires = [ "cymem>=2.0.2,<2.1.0", "preshed>=3.0.2,<3.1.0", "murmurhash>=0.28.0,<1.1.0", - "thinc>=8.0.8,<8.1.0", + "thinc>=8.0.9,<8.1.0", "blis>=0.4.0,<0.8.0", "pathy", "numpy>=1.15.0", diff --git a/requirements.txt b/requirements.txt index 49f49ad63..eea9dc21d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,7 +2,7 @@ spacy-legacy>=3.0.7,<3.1.0 cymem>=2.0.2,<2.1.0 preshed>=3.0.2,<3.1.0 -thinc>=8.0.8,<8.1.0 +thinc>=8.0.9,<8.1.0 blis>=0.4.0,<0.8.0 ml_datasets>=0.2.0,<0.3.0 murmurhash>=0.28.0,<1.1.0 diff --git a/setup.cfg b/setup.cfg index 9517acfc2..2708bac75 100644 --- a/setup.cfg +++ b/setup.cfg @@ -37,14 +37,14 @@ setup_requires = cymem>=2.0.2,<2.1.0 preshed>=3.0.2,<3.1.0 murmurhash>=0.28.0,<1.1.0 - thinc>=8.0.8,<8.1.0 + thinc>=8.0.9,<8.1.0 install_requires = # Our libraries spacy-legacy>=3.0.7,<3.1.0 murmurhash>=0.28.0,<1.1.0 cymem>=2.0.2,<2.1.0 preshed>=3.0.2,<3.1.0 - thinc>=8.0.8,<8.1.0 + thinc>=8.0.9,<8.1.0 blis>=0.4.0,<0.8.0 wasabi>=0.8.1,<1.1.0 srsly>=2.4.1,<3.0.0 From aba6ce3a43f3996388231ed423cba45967c42f14 Mon Sep 17 00:00:00 2001 From: Adriane Boyd Date: Wed, 8 Sep 2021 11:46:40 +0200 Subject: [PATCH 42/70] Handle spacy-legacy in package CLI for dependencies (#9163) * Handle spacy-legacy in package CLI for dependencies * Implement legacy backoff in spacy registry.find * Remove unused import * Update and format test --- spacy/cli/package.py | 5 ++--- spacy/tests/test_cli.py | 18 +++++++++++++++++- spacy/util.py | 26 ++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 4 deletions(-) diff --git a/spacy/cli/package.py b/spacy/cli/package.py index 9350b58e4..1a873d104 100644 --- a/spacy/cli/package.py +++ b/spacy/cli/package.py @@ -200,7 +200,7 @@ def get_third_party_dependencies( exclude (list): List of packages to exclude (e.g. that already exist in meta). RETURNS (list): The versioned requirements. """ - own_packages = ("spacy", "spacy-nightly", "thinc", "srsly") + own_packages = ("spacy", "spacy-legacy", "spacy-nightly", "thinc", "srsly") distributions = util.packages_distributions() funcs = defaultdict(set) for path, value in util.walk_dict(config): @@ -211,9 +211,8 @@ def get_third_party_dependencies( funcs["factories"].add(component["factory"]) modules = set() for reg_name, func_names in funcs.items(): - sub_registry = getattr(util.registry, reg_name) for func_name in func_names: - func_info = sub_registry.find(func_name) + func_info = util.registry.find(reg_name, func_name) module_name = func_info.get("module") if module_name: # the code is part of a module, not a --code file modules.add(func_info["module"].split(".")[0]) diff --git a/spacy/tests/test_cli.py b/spacy/tests/test_cli.py index a9525caae..72bbe04e5 100644 --- a/spacy/tests/test_cli.py +++ b/spacy/tests/test_cli.py @@ -536,7 +536,7 @@ def test_init_labels(component_name): assert len(nlp2.get_pipe(component_name).labels) == 4 -def test_get_third_party_dependencies_runs(): +def test_get_third_party_dependencies(): # We can't easily test the detection of third-party packages here, but we # can at least make sure that the function and its importlib magic runs. nlp = Dutch() @@ -544,6 +544,22 @@ def test_get_third_party_dependencies_runs(): nlp.add_pipe("tagger") assert get_third_party_dependencies(nlp.config) == [] + # Test with legacy function + nlp = Dutch() + nlp.add_pipe( + "textcat", + config={ + "model": { + # Do not update from legacy architecture spacy.TextCatBOW.v1 + "@architectures": "spacy.TextCatBOW.v1", + "exclusive_classes": True, + "ngram_size": 1, + "no_output_layer": False, + } + }, + ) + get_third_party_dependencies(nlp.config) == [] + @pytest.mark.parametrize( "parent,child,expected", diff --git a/spacy/util.py b/spacy/util.py index 6638e94ce..b49bd096f 100644 --- a/spacy/util.py +++ b/spacy/util.py @@ -140,6 +140,32 @@ class registry(thinc.registry): ) from None return func + @classmethod + def find(cls, registry_name: str, func_name: str) -> Callable: + """Get info about a registered function from the registry.""" + # We're overwriting this classmethod so we're able to provide more + # specific error messages and implement a fallback to spacy-legacy. + if not hasattr(cls, registry_name): + names = ", ".join(cls.get_registry_names()) or "none" + raise RegistryError(Errors.E892.format(name=registry_name, available=names)) + reg = getattr(cls, registry_name) + try: + func_info = reg.find(func_name) + except RegistryError: + if func_name.startswith("spacy."): + legacy_name = func_name.replace("spacy.", "spacy-legacy.") + try: + return reg.find(legacy_name) + except catalogue.RegistryError: + pass + available = ", ".join(sorted(reg.get_all().keys())) or "none" + raise RegistryError( + Errors.E893.format( + name=func_name, reg_name=registry_name, available=available + ) + ) from None + return func_info + @classmethod def has(cls, registry_name: str, func_name: str) -> bool: """Check whether a function is available in a registry.""" From ea5829407660ef34838e7a2296ae47c321fd5e0d Mon Sep 17 00:00:00 2001 From: Renat Shigapov <57352291+shigapov@users.noreply.github.com> Date: Thu, 9 Sep 2021 15:13:18 +0200 Subject: [PATCH 43/70] add spaCyOpenTapioca to universe --- website/meta/universe.json | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/website/meta/universe.json b/website/meta/universe.json index 993e900ff..c5e8017ab 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -642,6 +642,32 @@ "website": "https://ines.io" } }, + { + "id": "spacyopentapioca", + "title": "spaCyOpenTapioca", + "slogan": "Named entity linking on Wikidata in spaCy via OpenTapioca", + "description": "A spaCy wrapper of OpenTapioca for named entity linking on Wikidata", + "github": "UB-Mannheim/spacyopentapioca", + "pip": "spacyopentapioca", + "code_example": [ + "import spacy", + "nlp = spacy.blank('en')", + "nlp.add_pipe('opentapioca')", + "doc = nlp('Christian Drosten works in Germany.')", + "for span in doc.ents:", + " print((span.text, span.kb_id_, span.label_, span._.description, span._.score))", + "# ('Christian Drosten', 'Q1079331', 'PERSON', 'German virologist and university teacher', 3.6533377082098895)", + "# ('Germany', 'Q183', 'LOC', 'sovereign state in Central Europe', 2.1099332471902863)", + "## Check also span._.types, span._.aliases, span._.rank" + ], + "category": ["models", "pipeline"], + "tags": ["NER", "NEL"] + "author": "Renat Shigapov", + "author_links": { + "twitter": "_shigapov", + "github": "shigapov" + } + }, { "id": "spacy_hunspell", "slogan": "Add spellchecking and spelling suggestions to your spaCy pipeline using Hunspell", From 8940e0baca769be457df976bfab9531eb5d86e40 Mon Sep 17 00:00:00 2001 From: Renat Shigapov <57352291+shigapov@users.noreply.github.com> Date: Thu, 9 Sep 2021 15:33:29 +0200 Subject: [PATCH 44/70] add agreement --- .github/contributors/shigapov.md | 106 +++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 .github/contributors/shigapov.md diff --git a/.github/contributors/shigapov.md b/.github/contributors/shigapov.md new file mode 100644 index 000000000..3c24c7982 --- /dev/null +++ b/.github/contributors/shigapov.md @@ -0,0 +1,106 @@ +# spaCy contributor agreement + +This spaCy Contributor Agreement (**"SCA"**) is based on the +[Oracle Contributor Agreement](http://www.oracle.com/technetwork/oca-405177.pdf). +The SCA applies to any contribution that you make to any product or project +managed by us (the **"project"**), and sets out the intellectual property rights +you grant to us in the contributed materials. The term **"us"** shall mean +[ExplosionAI GmbH](https://explosion.ai/legal). The term +**"you"** shall mean the person or entity identified below. + +If you agree to be bound by these terms, fill in the information requested +below and include the filled-in version with your first pull request, under the +folder [`.github/contributors/`](/.github/contributors/). The name of the file +should be your GitHub username, with the extension `.md`. For example, the user +example_user would create the file `.github/contributors/example_user.md`. + +Read this agreement carefully before signing. These terms and conditions +constitute a binding legal agreement. + +## Contributor Agreement + +1. The term "contribution" or "contributed materials" means any source code, +object code, patch, tool, sample, graphic, specification, manual, +documentation, or any other material posted or submitted by you to the project. + +2. With respect to any worldwide copyrights, or copyright applications and +registrations, in your contribution: + + * you hereby assign to us joint ownership, and to the extent that such + assignment is or becomes invalid, ineffective or unenforceable, you hereby + grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge, + royalty-free, unrestricted license to exercise all rights under those + copyrights. This includes, at our option, the right to sublicense these same + rights to third parties through multiple levels of sublicensees or other + licensing arrangements; + + * you agree that each of us can do all things in relation to your + contribution as if each of us were the sole owners, and if one of us makes + a derivative work of your contribution, the one who makes the derivative + work (or has it made will be the sole owner of that derivative work; + + * you agree that you will not assert any moral rights in your contribution + against us, our licensees or transferees; + + * you agree that we may register a copyright in your contribution and + exercise all ownership rights associated with it; and + + * you agree that neither of us has any duty to consult with, obtain the + consent of, pay or render an accounting to the other for any use or + distribution of your contribution. + +3. With respect to any patents you own, or that you can license without payment +to any third party, you hereby grant to us a perpetual, irrevocable, +non-exclusive, worldwide, no-charge, royalty-free license to: + + * make, have made, use, sell, offer to sell, import, and otherwise transfer + your contribution in whole or in part, alone or in combination with or + included in any product, work or materials arising out of the project to + which your contribution was submitted, and + + * at our option, to sublicense these same rights to third parties through + multiple levels of sublicensees or other licensing arrangements. + +4. Except as set out above, you keep all right, title, and interest in your +contribution. The rights that you grant to us under these terms are effective +on the date you first submitted a contribution to us, even if your submission +took place before the date you sign these terms. + +5. You covenant, represent, warrant and agree that: + + * Each contribution that you submit is and shall be an original work of + authorship and you can legally grant the rights set out in this SCA; + + * to the best of your knowledge, each contribution will not violate any + third party's copyrights, trademarks, patents, or other intellectual + property rights; and + + * each contribution shall be in compliance with U.S. export control laws and + other applicable export and import laws. You agree to notify us if you + become aware of any circumstance which would make any of the foregoing + representations inaccurate in any respect. We may publicly disclose your + participation in the project, including the fact that you have signed the SCA. + +6. This SCA is governed by the laws of the State of California and applicable +U.S. Federal law. Any choice of law rules will not apply. + +7. Please place an “x” on one of the applicable statement below. Please do NOT +mark both statements: + + * [x] I am signing on behalf of myself as an individual and no other person + or entity, including my employer, has or will have rights with respect to my + contributions. + + * [ ] I am signing on behalf of my employer or a legal entity and I have the + actual authority to contractually bind that entity. + +## Contributor Details + +| Field | Entry | +|------------------------------- | ------------------------ | +| Name | Renat Shigapov | +| Company name (if applicable) | | +| Title or role (if applicable) | | +| Date | 2021-09-09 | +| GitHub username | shigapov | +| Website (optional) | | From c1927fe9943d236f6a839cd356afcae3a9e0adf7 Mon Sep 17 00:00:00 2001 From: Renat Shigapov <57352291+shigapov@users.noreply.github.com> Date: Thu, 9 Sep 2021 15:37:34 +0200 Subject: [PATCH 45/70] fix misprint in tags --- website/meta/universe.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/meta/universe.json b/website/meta/universe.json index c5e8017ab..04163c61e 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -661,7 +661,7 @@ "## Check also span._.types, span._.aliases, span._.rank" ], "category": ["models", "pipeline"], - "tags": ["NER", "NEL"] + "tags": ["NER", "NEL"], "author": "Renat Shigapov", "author_links": { "twitter": "_shigapov", From 462b009648d9dfaadb5ac0fe77f59c69e56f2c2f Mon Sep 17 00:00:00 2001 From: j-frei <27365662+j-frei@users.noreply.github.com> Date: Fri, 10 Sep 2021 16:19:58 +0200 Subject: [PATCH 46/70] Correct parser.py use_upper param info (#9180) --- spacy/ml/models/parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spacy/ml/models/parser.py b/spacy/ml/models/parser.py index 80751a695..97137313d 100644 --- a/spacy/ml/models/parser.py +++ b/spacy/ml/models/parser.py @@ -56,7 +56,7 @@ def build_tb_parser_model( non-linearity if use_upper=False. use_upper (bool): Whether to use an additional hidden layer after the state vector in order to predict the action scores. It is recommended to set - this to False for large pretrained models such as transformers, and False + this to False for large pretrained models such as transformers, and True for smaller networks. The upper layer is computed on CPU, which becomes a bottleneck on larger GPU-based models, where it's also less necessary. nO (int or None): The number of actions the model will predict between. From ee28aac68efea916571aab7dcc421d4f394223a2 Mon Sep 17 00:00:00 2001 From: mylibrar <54747962+mylibrar@users.noreply.github.com> Date: Sat, 11 Sep 2021 00:13:13 -0400 Subject: [PATCH 47/70] Update example code of forte (#9175) Co-authored-by: Suqi Sun --- website/meta/universe.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/website/meta/universe.json b/website/meta/universe.json index 993e900ff..2ff0cec9f 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -3259,15 +3259,17 @@ "slogan": "Forte is a toolkit for building Natural Language Processing pipelines, featuring cross-task interaction, adaptable data-model interfaces and composable pipelines.", "description": "Forte provides a platform to assemble state-of-the-art NLP and ML technologies in a highly-composable fashion, including a wide spectrum of tasks ranging from Information Retrieval, Natural Language Understanding to Natural Language Generation.", "github": "asyml/forte", - "pip": "forte.spacy torch", + "pip": "forte.spacy stave torch", "code_example": [ - "from forte.spacy import SpacyProcessor", + "from fortex.spacy import SpacyProcessor", + "from forte.processors.stave import StaveProcessor", "from forte import Pipeline", "from forte.data.readers import StringReader", "", "pipeline = Pipeline()", "pipeline.set_reader(StringReader())", "pipeline.add(SpacyProcessor())", + "pipeline.add(StaveProcessor())", "pipeline.run('Running SpaCy with Forte!')" ], "code_language": "python", From 646f3a54db330c6f947d7b722158f1a7c512247f Mon Sep 17 00:00:00 2001 From: Renat Shigapov <57352291+shigapov@users.noreply.github.com> Date: Sat, 11 Sep 2021 06:16:51 +0200 Subject: [PATCH 48/70] added spaCyOpenTapioca (#9181) * add spaCyOpenTapioca to universe * add agreement * fix misprint in tags --- .github/contributors/shigapov.md | 106 +++++++++++++++++++++++++++++++ website/meta/universe.json | 26 ++++++++ 2 files changed, 132 insertions(+) create mode 100644 .github/contributors/shigapov.md diff --git a/.github/contributors/shigapov.md b/.github/contributors/shigapov.md new file mode 100644 index 000000000..3c24c7982 --- /dev/null +++ b/.github/contributors/shigapov.md @@ -0,0 +1,106 @@ +# spaCy contributor agreement + +This spaCy Contributor Agreement (**"SCA"**) is based on the +[Oracle Contributor Agreement](http://www.oracle.com/technetwork/oca-405177.pdf). +The SCA applies to any contribution that you make to any product or project +managed by us (the **"project"**), and sets out the intellectual property rights +you grant to us in the contributed materials. The term **"us"** shall mean +[ExplosionAI GmbH](https://explosion.ai/legal). The term +**"you"** shall mean the person or entity identified below. + +If you agree to be bound by these terms, fill in the information requested +below and include the filled-in version with your first pull request, under the +folder [`.github/contributors/`](/.github/contributors/). The name of the file +should be your GitHub username, with the extension `.md`. For example, the user +example_user would create the file `.github/contributors/example_user.md`. + +Read this agreement carefully before signing. These terms and conditions +constitute a binding legal agreement. + +## Contributor Agreement + +1. The term "contribution" or "contributed materials" means any source code, +object code, patch, tool, sample, graphic, specification, manual, +documentation, or any other material posted or submitted by you to the project. + +2. With respect to any worldwide copyrights, or copyright applications and +registrations, in your contribution: + + * you hereby assign to us joint ownership, and to the extent that such + assignment is or becomes invalid, ineffective or unenforceable, you hereby + grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge, + royalty-free, unrestricted license to exercise all rights under those + copyrights. This includes, at our option, the right to sublicense these same + rights to third parties through multiple levels of sublicensees or other + licensing arrangements; + + * you agree that each of us can do all things in relation to your + contribution as if each of us were the sole owners, and if one of us makes + a derivative work of your contribution, the one who makes the derivative + work (or has it made will be the sole owner of that derivative work; + + * you agree that you will not assert any moral rights in your contribution + against us, our licensees or transferees; + + * you agree that we may register a copyright in your contribution and + exercise all ownership rights associated with it; and + + * you agree that neither of us has any duty to consult with, obtain the + consent of, pay or render an accounting to the other for any use or + distribution of your contribution. + +3. With respect to any patents you own, or that you can license without payment +to any third party, you hereby grant to us a perpetual, irrevocable, +non-exclusive, worldwide, no-charge, royalty-free license to: + + * make, have made, use, sell, offer to sell, import, and otherwise transfer + your contribution in whole or in part, alone or in combination with or + included in any product, work or materials arising out of the project to + which your contribution was submitted, and + + * at our option, to sublicense these same rights to third parties through + multiple levels of sublicensees or other licensing arrangements. + +4. Except as set out above, you keep all right, title, and interest in your +contribution. The rights that you grant to us under these terms are effective +on the date you first submitted a contribution to us, even if your submission +took place before the date you sign these terms. + +5. You covenant, represent, warrant and agree that: + + * Each contribution that you submit is and shall be an original work of + authorship and you can legally grant the rights set out in this SCA; + + * to the best of your knowledge, each contribution will not violate any + third party's copyrights, trademarks, patents, or other intellectual + property rights; and + + * each contribution shall be in compliance with U.S. export control laws and + other applicable export and import laws. You agree to notify us if you + become aware of any circumstance which would make any of the foregoing + representations inaccurate in any respect. We may publicly disclose your + participation in the project, including the fact that you have signed the SCA. + +6. This SCA is governed by the laws of the State of California and applicable +U.S. Federal law. Any choice of law rules will not apply. + +7. Please place an “x” on one of the applicable statement below. Please do NOT +mark both statements: + + * [x] I am signing on behalf of myself as an individual and no other person + or entity, including my employer, has or will have rights with respect to my + contributions. + + * [ ] I am signing on behalf of my employer or a legal entity and I have the + actual authority to contractually bind that entity. + +## Contributor Details + +| Field | Entry | +|------------------------------- | ------------------------ | +| Name | Renat Shigapov | +| Company name (if applicable) | | +| Title or role (if applicable) | | +| Date | 2021-09-09 | +| GitHub username | shigapov | +| Website (optional) | | diff --git a/website/meta/universe.json b/website/meta/universe.json index 2ff0cec9f..6e5696be1 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -642,6 +642,32 @@ "website": "https://ines.io" } }, + { + "id": "spacyopentapioca", + "title": "spaCyOpenTapioca", + "slogan": "Named entity linking on Wikidata in spaCy via OpenTapioca", + "description": "A spaCy wrapper of OpenTapioca for named entity linking on Wikidata", + "github": "UB-Mannheim/spacyopentapioca", + "pip": "spacyopentapioca", + "code_example": [ + "import spacy", + "nlp = spacy.blank('en')", + "nlp.add_pipe('opentapioca')", + "doc = nlp('Christian Drosten works in Germany.')", + "for span in doc.ents:", + " print((span.text, span.kb_id_, span.label_, span._.description, span._.score))", + "# ('Christian Drosten', 'Q1079331', 'PERSON', 'German virologist and university teacher', 3.6533377082098895)", + "# ('Germany', 'Q183', 'LOC', 'sovereign state in Central Europe', 2.1099332471902863)", + "## Check also span._.types, span._.aliases, span._.rank" + ], + "category": ["models", "pipeline"], + "tags": ["NER", "NEL"], + "author": "Renat Shigapov", + "author_links": { + "twitter": "_shigapov", + "github": "shigapov" + } + }, { "id": "spacy_hunspell", "slogan": "Add spellchecking and spelling suggestions to your spaCy pipeline using Hunspell", From f89e1c34c9097bb5081c87ba3179d9e8f60929f7 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Sat, 11 Sep 2021 14:22:05 +0900 Subject: [PATCH 49/70] Minor typo fix in docs --- website/docs/usage/processing-pipelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/usage/processing-pipelines.md b/website/docs/usage/processing-pipelines.md index 0109f24c9..0264a2825 100644 --- a/website/docs/usage/processing-pipelines.md +++ b/website/docs/usage/processing-pipelines.md @@ -795,7 +795,7 @@ if there's no state to be passed through – spaCy can just take care of this fo you. The following two code examples are equivalent: ```python -# Statless component with @Language.factory +# Stateless component with @Language.factory @Language.factory("my_component") def create_my_component(): def my_component(doc): From 7562fb53545f396848bd55e774adf1a6b1686af8 Mon Sep 17 00:00:00 2001 From: Renat Shigapov <57352291+shigapov@users.noreply.github.com> Date: Mon, 13 Sep 2021 08:06:54 +0200 Subject: [PATCH 50/70] add links to entities into the TPL_ENT-template --- spacy/displacy/templates.py | 1 + 1 file changed, 1 insertion(+) diff --git a/spacy/displacy/templates.py b/spacy/displacy/templates.py index b9cbf717b..c44c1e2a6 100644 --- a/spacy/displacy/templates.py +++ b/spacy/displacy/templates.py @@ -52,6 +52,7 @@ TPL_ENT = """ {text} {label} + {kb_id} """ From f4b5c4209d6cb3748534ad072784a3f9c4fa194c Mon Sep 17 00:00:00 2001 From: Renat Shigapov <57352291+shigapov@users.noreply.github.com> Date: Mon, 13 Sep 2021 08:15:07 +0200 Subject: [PATCH 51/70] specify kb_id and kb_url for URL visualisation --- spacy/displacy/render.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/spacy/displacy/render.py b/spacy/displacy/render.py index ba56beca3..40269e74f 100644 --- a/spacy/displacy/render.py +++ b/spacy/displacy/render.py @@ -305,7 +305,7 @@ class EntityRenderer: """Render entities in text. text (str): Original text. - spans (list): Individual entity spans and their start, end and label. + spans (list): Individual entity spans and their start, end, label, kb_id and kb_url. title (str / None): Document title set in Doc.user_data['title']. """ markup = "" @@ -314,6 +314,8 @@ class EntityRenderer: label = span["label"] start = span["start"] end = span["end"] + kb_id = str(span.get("kb_id") or "") + kb_url = str(span.get("kb_url") or "") additional_params = span.get("params", {}) entity = escape_html(text[start:end]) fragments = text[offset:start].split("\n") @@ -323,7 +325,7 @@ class EntityRenderer: markup += "
" if self.ents is None or label.upper() in self.ents: color = self.colors.get(label.upper(), self.default_color) - ent_settings = {"label": label, "text": entity, "bg": color} + ent_settings = {"label": label, "text": entity, "bg": color, "kb_id": kb_id, "kb_url": kb_url} ent_settings.update(additional_params) markup += self.ent_template.format(**ent_settings) else: From e61d93f8c3715d74038c9bd952fe60418fc6f144 Mon Sep 17 00:00:00 2001 From: Renat Shigapov <57352291+shigapov@users.noreply.github.com> Date: Mon, 13 Sep 2021 08:38:58 +0200 Subject: [PATCH 52/70] add NEL-visualisation to manual-usage --- website/docs/usage/visualizers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/usage/visualizers.md b/website/docs/usage/visualizers.md index cc73e7e67..cb643aed1 100644 --- a/website/docs/usage/visualizers.md +++ b/website/docs/usage/visualizers.md @@ -297,7 +297,7 @@ position. > > ```python > ex = [{"text": "But Google is starting from behind.", -> "ents": [{"start": 4, "end": 10, "label": "ORG"}], +> "ents": [{"start": 4, "end": 10, "label": "ORG", "kb_id": "Q95", "kb_url": "https://www.wikidata.org/entity/Q95"}], > "title": None}] > html = displacy.render(ex, style="ent", manual=True) > ``` @@ -323,7 +323,7 @@ position. ### ENT input { "text": "But Google is starting from behind.", - "ents": [{"start": 4, "end": 10, "label": "ORG"}], + "ents": [{"start": 4, "end": 10, "label": "ORG", "kb_id": "Q95", "kb_url": "https://www.wikidata.org/entity/Q95"}], "title": None } ``` From d74870d38cec6c2bf0562f38a32b3ed4716ef4a9 Mon Sep 17 00:00:00 2001 From: Adriane Boyd Date: Tue, 14 Sep 2021 11:03:51 +0200 Subject: [PATCH 53/70] Prepare for v3.1.3 (#9200) * Update thinc and spacy-legacy requirements * Set version to v3.1.3 --- pyproject.toml | 2 +- requirements.txt | 4 ++-- setup.cfg | 4 ++-- spacy/about.py | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 9dd640185..7328cd6c2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,7 +5,7 @@ requires = [ "cymem>=2.0.2,<2.1.0", "preshed>=3.0.2,<3.1.0", "murmurhash>=0.28.0,<1.1.0", - "thinc>=8.0.9,<8.1.0", + "thinc>=8.0.10,<8.1.0", "blis>=0.4.0,<0.8.0", "pathy", "numpy>=1.15.0", diff --git a/requirements.txt b/requirements.txt index eea9dc21d..12fdf650f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,8 +1,8 @@ # Our libraries -spacy-legacy>=3.0.7,<3.1.0 +spacy-legacy>=3.0.8,<3.1.0 cymem>=2.0.2,<2.1.0 preshed>=3.0.2,<3.1.0 -thinc>=8.0.9,<8.1.0 +thinc>=8.0.10,<8.1.0 blis>=0.4.0,<0.8.0 ml_datasets>=0.2.0,<0.3.0 murmurhash>=0.28.0,<1.1.0 diff --git a/setup.cfg b/setup.cfg index 2708bac75..ff12d511a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -37,10 +37,10 @@ setup_requires = cymem>=2.0.2,<2.1.0 preshed>=3.0.2,<3.1.0 murmurhash>=0.28.0,<1.1.0 - thinc>=8.0.9,<8.1.0 + thinc>=8.0.10,<8.1.0 install_requires = # Our libraries - spacy-legacy>=3.0.7,<3.1.0 + spacy-legacy>=3.0.8,<3.1.0 murmurhash>=0.28.0,<1.1.0 cymem>=2.0.2,<2.1.0 preshed>=3.0.2,<3.1.0 diff --git a/spacy/about.py b/spacy/about.py index 85b579f95..3137be806 100644 --- a/spacy/about.py +++ b/spacy/about.py @@ -1,6 +1,6 @@ # fmt: off __title__ = "spacy" -__version__ = "3.1.2" +__version__ = "3.1.3" __download_url__ = "https://github.com/explosion/spacy-models/releases/download" __compatibility__ = "https://raw.githubusercontent.com/explosion/spacy-models/master/compatibility.json" __projects__ = "https://github.com/explosion/projects" From 20f63e7154fe51955ab88e56e07487e7ab3c3862 Mon Sep 17 00:00:00 2001 From: Ines Montani Date: Thu, 16 Sep 2021 07:16:01 +1000 Subject: [PATCH 54/70] Only include runtime-relevant config in package CLI dependency detection (#9211) --- spacy/cli/package.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/spacy/cli/package.py b/spacy/cli/package.py index 1a873d104..332a51bc7 100644 --- a/spacy/cli/package.py +++ b/spacy/cli/package.py @@ -203,9 +203,11 @@ def get_third_party_dependencies( own_packages = ("spacy", "spacy-legacy", "spacy-nightly", "thinc", "srsly") distributions = util.packages_distributions() funcs = defaultdict(set) - for path, value in util.walk_dict(config): - if path[-1].startswith("@"): # collect all function references by registry - funcs[path[-1][1:]].add(value) + # We only want to look at runtime-relevant sections, not [training] or [initialize] + for section in ("nlp", "components"): + for path, value in util.walk_dict(config[section]): + if path[-1].startswith("@"): # collect all function references by registry + funcs[path[-1][1:]].add(value) for component in config.get("components", {}).values(): if "factory" in component: funcs["factories"].add(component["factory"]) From 9ceb8f413c42f7a130a27f4fb8b277e917e63bc4 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Thu, 16 Sep 2021 12:50:22 +0900 Subject: [PATCH 55/70] StringStore/Vocab dev docs (#9142) * First take at StringStore/Vocab docs Things to check: 1. The mysterious vocab members 2. How to make table of contents? Is it autogenerated? 3. Anything I missed / needs more detail? * Update docs * Apply suggestions from code review Co-authored-by: Sofie Van Landeghem * Updates based on review feedback * Minor fix * Move example code down Co-authored-by: Sofie Van Landeghem --- extra/DEVELOPER_DOCS/StringStore-Vocab.md | 216 ++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 extra/DEVELOPER_DOCS/StringStore-Vocab.md diff --git a/extra/DEVELOPER_DOCS/StringStore-Vocab.md b/extra/DEVELOPER_DOCS/StringStore-Vocab.md new file mode 100644 index 000000000..866ba2aae --- /dev/null +++ b/extra/DEVELOPER_DOCS/StringStore-Vocab.md @@ -0,0 +1,216 @@ +# StringStore & Vocab + +> Reference: `spacy/strings.pyx` +> Reference: `spacy/vocab.pyx` + +## Overview + +spaCy represents mosts strings internally using a `uint64` in Cython which +corresponds to a hash. The magic required to make this largely transparent is +handled by the `StringStore`, and is integrated into the pipelines using the +`Vocab`, which also connects it to some other information. + +These are mostly internal details that average library users should never have +to think about. On the other hand, when developing a component it's normal to +interact with the Vocab for lexeme data or word vectors, and it's not unusual +to add labels to the `StringStore`. + +## StringStore + +### Overview + +The `StringStore` is a `cdef class` that looks a bit like a two-way dictionary, +though it is not a subclass of anything in particular. + +The main functionality of the `StringStore` is that `__getitem__` converts +hashes into strings or strings into hashes. + +The full details of the conversion are complicated. Normally you shouldn't have +to worry about them, but the first applicable case here is used to get the +return value: + +1. 0 and the empty string are special cased to each other +2. internal symbols use a lookup table (`SYMBOLS_BY_STR`) +3. normal strings or bytes are hashed +4. internal symbol IDs in `SYMBOLS_BY_INT` are handled +5. anything not yet handled is used as a hash to lookup a string + +For the symbol enums, see [`symbols.pxd`](https://github.com/explosion/spaCy/blob/master/spacy/symbols.pxd). + +Almost all strings in spaCy are stored in the `StringStore`. This naturally +includes tokens, but also includes things like labels (not just NER/POS/dep, +but also categories etc.), lemmas, lowercase forms, word shapes, and so on. One +of the main results of this is that tokens can be represented by a compact C +struct ([`LexemeC`](https://spacy.io/api/cython-structs#lexemec)/[`TokenC`](https://github.com/explosion/spaCy/issues/4854)) that mostly consists of string hashes. This also means that converting +input for the models is straightforward, and there's not a token mapping step +like in many machine learning frameworks. Additionally, because the token IDs +in spaCy are based on hashes, they are consistent across environments or +models. + +One pattern you'll see a lot in spaCy APIs is that `something.value` returns an +`int` and `something.value_` returns a string. That's implemented using the +`StringStore`. Typically the `int` is stored in a C struct and the string is +generated via a property that calls into the `StringStore` with the `int`. + +Besides `__getitem__`, the `StringStore` has functions to return specifically a +string or specifically a hash, regardless of whether the input was a string or +hash to begin with, though these are only used occasionally. + +### Implementation Details: Hashes and Allocations + +Hashes are 64-bit and are computed using [murmurhash][] on UTF-8 bytes. There is no +mechanism for detecting and avoiding collisions. To date there has never been a +reproducible collision or user report about any related issues. + +[murmurhash]: https://github.com/explosion/murmurhash + +The empty string is not hashed, it's just converted to/from 0. + +A small number of strings use indices into a lookup table (so low integers) +rather than hashes. This is mostly Universal Dependencies labels or other +strings considered "core" in spaCy. This was critical in v1, which hadn't +introduced hashing yet. Since v2 it's important for items in `spacy.attrs`, +especially lexeme flags, but is otherwise only maintained for backwards +compatibility. + +You can call `strings["mystring"]` with a string the `StringStore` has never seen +before and it will return a hash. But in order to do the reverse operation, you +need to call `strings.add("mystring")` first. Without a call to `add` the +string will not be interned. + +Example: + +``` +from spacy.strings import StringStore + +ss = StringStore() +hashval = ss["spacy"] # 10639093010105930009 +try: + # this won't work + ss[hashval] +except KeyError: + print(f"key {hashval} unknown in the StringStore.") + +ss.add("spacy") +assert ss[hashval] == "spacy" # it works now + +# There is no `.keys` property, but you can iterate over keys +# The empty string will never be in the list of keys +for key in ss: + print(key) +``` + +In normal use nothing is ever removed from the `StringStore`. In theory this +means that if you do something like iterate through all hex values of a certain +length you can have explosive memory usage. In practice this has never been an +issue. (Note that this is also different from using `sys.intern` to intern +Python strings, which does not guarantee they won't be garbage collected later.) + +Strings are stored in the `StringStore` in a peculiar way: each string uses a +union that is either an eight-byte `char[]` or a `char*`. Short strings are +stored directly in the `char[]`, while longer strings are stored in allocated +memory and prefixed with their length. This is a strategy to reduce indirection +and memory fragmentation. See `decode_Utf8Str` and `_allocate` in +`strings.pyx` for the implementation. + +### When to Use the StringStore? + +While you can ignore the `StringStore` in many cases, there are situations where +you should make use of it to avoid errors. + +Any time you introduce a string that may be set on a `Doc` field that has a hash, +you should add the string to the `StringStore`. This mainly happens when adding +labels in components, but there are some other cases: + +- syntax iterators, mainly `get_noun_chunks` +- external data used in components, like the `KnowledgeBase` in the `entity_linker` +- labels used in tests + +## Vocab + +The `Vocab` is a core component of a `Language` pipeline. Its main function is +to manage `Lexeme`s, which are structs that contain information about a token +that depends only on its surface form, without context. `Lexeme`s store much of +the data associated with `Token`s. As a side effect of this the `Vocab` also +manages the `StringStore` for a pipeline and a grab-bag of other data. + +These are things stored in the vocab: + +- `Lexeme`s +- `StringStore` +- `Morphology`: manages info used in `MorphAnalysis` objects +- `vectors`: basically a dict for word vectors +- `lookups`: language specific data like lemmas +- `writing_system`: language specific metadata +- `get_noun_chunks`: a syntax iterator +- lex attribute getters: functions like `is_punct`, set in language defaults +- `cfg`: **not** the pipeline config, this is mostly unused +- `_unused_object`: Formerly an unused object, kept around until v4 for compatability + +Some of these, like the Morphology and Vectors, are complex enough that they +need their own explanations. Here we'll just look at Vocab-specific items. + +### Lexemes + +A `Lexeme` is a type that mainly wraps a `LexemeC`, a struct consisting of ints +that identify various context-free token attributes. Lexemes are the core data +of the `Vocab`, and can be accessed using `__getitem__` on the `Vocab`. The memory +for storing `LexemeC` objects is managed by a pool that belongs to the `Vocab`. + +Note that `__getitem__` on the `Vocab` works much like the `StringStore`, in +that it accepts a hash or id, with one important difference: if you do a lookup +using a string, that value is added to the `StringStore` automatically. + +The attributes stored in a `LexemeC` are: + +- orth (the raw text) +- lower +- norm +- shape +- prefix +- suffix + +Most of these are straightforward. All of them can be customized, and (except +`orth`) probably should be since the defaults are based on English, but in +practice this is rarely done at present. + +### Lookups + +This is basically a dict of dicts, implemented using a `Table` for each +sub-dict, that stores lemmas and other language-specific lookup data. + +A `Table` is a subclass of `OrderedDict` used for string-to-string data. It uses +Bloom filters to speed up misses and has some extra serialization features. +Tables are not used outside of the lookups. + +### Lex Attribute Getters + +Lexical Attribute Getters like `is_punct` are defined on a per-language basis, +much like lookups, but take the form of functions rather than string-to-string +dicts, so they're stored separately. + +### Writing System + +This is a dict with three attributes: + +- `direction`: ltr or rtl (default ltr) +- `has_case`: bool (default `True`) +- `has_letters`: bool (default `True`, `False` only for CJK for now) + +Currently these are not used much - the main use is that `direction` is used in +visualizers, though `rtl` doesn't quite work (see +[#4854](https://github.com/explosion/spaCy/issues/4854)). In the future they +could be used when choosing hyperparameters for subwords, controlling word +shape generation, and similar tasks. + +### Other Vocab Members + +The Vocab is kind of the default place to store things from `Language.defaults` +that don't belong to the Tokenizer. The following properties are in the Vocab +just because they don't have anywhere else to go. + +- `get_noun_chunks` +- `cfg`: This is a dict that just stores `oov_prob` (hardcoded to `-20`) +- `_unused_object`: Leftover C member, should be removed in next major version + + From 1d57d78758a6dece13bf0574b69c0ef57e19b932 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Thu, 16 Sep 2021 15:54:12 +0900 Subject: [PATCH 56/70] Make docs consistent (fix #9126) --- website/docs/usage/embeddings-transformers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/usage/embeddings-transformers.md b/website/docs/usage/embeddings-transformers.md index 9e3f140e4..88fb39f61 100644 --- a/website/docs/usage/embeddings-transformers.md +++ b/website/docs/usage/embeddings-transformers.md @@ -671,7 +671,7 @@ You can then run [`spacy pretrain`](/api/cli#pretrain) with the updated config and pass in optional config overrides, like the path to the raw text file: ```cli -$ python -m spacy pretrain config_pretrain.cfg ./output --paths.raw text.jsonl +$ python -m spacy pretrain config_pretrain.cfg ./output --paths.raw_text text.jsonl ``` The following defaults are used for the `[pretraining]` block and merged into From 4bf2606adf4cdd2045a6aeec3a8258c5cb3915ed Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Thu, 16 Sep 2021 09:22:38 +0200 Subject: [PATCH 57/70] Update spacy/displacy/render.py Co-authored-by: Renat Shigapov <57352291+shigapov@users.noreply.github.com> --- spacy/displacy/render.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spacy/displacy/render.py b/spacy/displacy/render.py index 40269e74f..bd7178724 100644 --- a/spacy/displacy/render.py +++ b/spacy/displacy/render.py @@ -314,8 +314,8 @@ class EntityRenderer: label = span["label"] start = span["start"] end = span["end"] - kb_id = str(span.get("kb_id") or "") - kb_url = str(span.get("kb_url") or "") + kb_id = span.get("kb_id", "") + kb_url = span.get("kb_url", "") additional_params = span.get("params", {}) entity = escape_html(text[start:end]) fragments = text[offset:start].split("\n") From 00836c2d7d46b0aa405eb1569856f7923da6d1f0 Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Thu, 16 Sep 2021 09:23:21 +0200 Subject: [PATCH 58/70] Update spacy/displacy/templates.py --- spacy/displacy/templates.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spacy/displacy/templates.py b/spacy/displacy/templates.py index c44c1e2a6..051f72cb2 100644 --- a/spacy/displacy/templates.py +++ b/spacy/displacy/templates.py @@ -51,8 +51,9 @@ TPL_ENTS = """ TPL_ENT = """ {text} - {label} + {label} {kb_id} + """ From 865cfbc903a53df15f74c767c14bcf29847d0848 Mon Sep 17 00:00:00 2001 From: Jozef Harag <32jojo32@gmail.com> Date: Thu, 16 Sep 2021 12:26:41 +0200 Subject: [PATCH 59/70] feat: add `spacy.WandbLogger.v3` with optional `run_name` and `entity` parameters (#9202) * feat: add `spacy.WandbLogger.v3` with optional `run_name` and `entity` parameters * update versioning in docs Co-authored-by: svlandeg --- spacy/training/loggers.py | 84 +++++++++++++++++++++++++++++++++++ website/docs/api/top-level.md | 18 ++++---- 2 files changed, 94 insertions(+), 8 deletions(-) diff --git a/spacy/training/loggers.py b/spacy/training/loggers.py index 5cf2db6b3..524b422a5 100644 --- a/spacy/training/loggers.py +++ b/spacy/training/loggers.py @@ -177,3 +177,87 @@ def wandb_logger( return log_step, finalize return setup_logger + + +@registry.loggers("spacy.WandbLogger.v3") +def wandb_logger( + project_name: str, + remove_config_values: List[str] = [], + model_log_interval: Optional[int] = None, + log_dataset_dir: Optional[str] = None, + entity: Optional[str] = None, + run_name: Optional[str] = None, +): + try: + import wandb + + # test that these are available + from wandb import init, log, join # noqa: F401 + except ImportError: + raise ImportError(Errors.E880) + + console = console_logger(progress_bar=False) + + def setup_logger( + nlp: "Language", stdout: IO = sys.stdout, stderr: IO = sys.stderr + ) -> Tuple[Callable[[Dict[str, Any]], None], Callable[[], None]]: + config = nlp.config.interpolate() + config_dot = util.dict_to_dot(config) + for field in remove_config_values: + del config_dot[field] + config = util.dot_to_dict(config_dot) + run = wandb.init(project=project_name, config=config, entity=entity, reinit=True) + + if run_name: + wandb.run.name = run_name + + console_log_step, console_finalize = console(nlp, stdout, stderr) + + def log_dir_artifact( + path: str, + name: str, + type: str, + metadata: Optional[Dict[str, Any]] = {}, + aliases: Optional[List[str]] = [], + ): + dataset_artifact = wandb.Artifact(name, type=type, metadata=metadata) + dataset_artifact.add_dir(path, name=name) + wandb.log_artifact(dataset_artifact, aliases=aliases) + + if log_dataset_dir: + log_dir_artifact(path=log_dataset_dir, name="dataset", type="dataset") + + def log_step(info: Optional[Dict[str, Any]]): + console_log_step(info) + if info is not None: + score = info["score"] + other_scores = info["other_scores"] + losses = info["losses"] + wandb.log({"score": score}) + if losses: + wandb.log({f"loss_{k}": v for k, v in losses.items()}) + if isinstance(other_scores, dict): + wandb.log(other_scores) + if model_log_interval and info.get("output_path"): + if info["step"] % model_log_interval == 0 and info["step"] != 0: + log_dir_artifact( + path=info["output_path"], + name="pipeline_" + run.id, + type="checkpoint", + metadata=info, + aliases=[ + f"epoch {info['epoch']} step {info['step']}", + "latest", + "best" + if info["score"] == max(info["checkpoints"])[0] + else "", + ], + ) + + def finalize() -> None: + console_finalize() + wandb.join() + + return log_step, finalize + + return setup_logger diff --git a/website/docs/api/top-level.md b/website/docs/api/top-level.md index 8190d9f78..3cf81ae93 100644 --- a/website/docs/api/top-level.md +++ b/website/docs/api/top-level.md @@ -462,7 +462,7 @@ start decreasing across epochs. -#### spacy.WandbLogger.v2 {#WandbLogger tag="registered function"} +#### spacy.WandbLogger.v3 {#WandbLogger tag="registered function"} > #### Installation > @@ -494,19 +494,21 @@ remain in the config file stored on your local system. > > ```ini > [training.logger] -> @loggers = "spacy.WandbLogger.v2" +> @loggers = "spacy.WandbLogger.v3" > project_name = "monitor_spacy_training" > remove_config_values = ["paths.train", "paths.dev", "corpora.train.path", "corpora.dev.path"] > log_dataset_dir = "corpus" > model_log_interval = 1000 > ``` -| Name | Description | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `project_name` | The name of the project in the Weights & Biases interface. The project will be created automatically if it doesn't exist yet. ~~str~~ | -| `remove_config_values` | A list of values to include from the config before it is uploaded to W&B (default: empty). ~~List[str]~~ | -| `model_log_interval` | Steps to wait between logging model checkpoints to W&B dasboard (default: None). ~~Optional[int]~~ | -| `log_dataset_dir` | Directory containing dataset to be logged and versioned as W&B artifact (default: None). ~~Optional[str]~~ | +| Name | Description | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `project_name` | The name of the project in the Weights & Biases interface. The project will be created automatically if it doesn't exist yet. ~~str~~ | +| `remove_config_values` | A list of values to include from the config before it is uploaded to W&B (default: empty). ~~List[str]~~ | +| `model_log_interval` | Steps to wait between logging model checkpoints to W&B dasboard (default: None). ~~Optional[int]~~ | +| `log_dataset_dir` | Directory containing dataset to be logged and versioned as W&B artifact (default: None). ~~Optional[str]~~ | +| `run_name` | The name of the run. If you don't specify a run_name, the name will be created by wandb library. (default: None ). ~~Optional[str]~~ | +| `entity` | An entity is a username or team name where you're sending runs. If you don't specify an entity, the run will be sent to your default entity, which is usually your username. (default: None). ~~Optional[str]~~ | From c4f0800fb8fbd67ad1c55e8d2cee7f95414803e3 Mon Sep 17 00:00:00 2001 From: Paul O'Leary McCann Date: Thu, 16 Sep 2021 20:28:05 +0900 Subject: [PATCH 60/70] Validate pos values when creating Doc (#9148) * Validate pos values when creating Doc * Add clear error when setting invalid pos This also changes the error language slightly. * Fix variable name * Update spacy/tokens/doc.pyx * Test that setting invalid pos raises an error Co-authored-by: Sofie Van Landeghem --- spacy/errors.py | 2 ++ spacy/tests/doc/test_creation.py | 7 +++++++ spacy/tests/doc/test_token_api.py | 4 ++++ spacy/tokens/doc.pyx | 5 +++++ spacy/tokens/token.pyx | 2 ++ 5 files changed, 20 insertions(+) diff --git a/spacy/errors.py b/spacy/errors.py index 0e1a294c3..135aacf92 100644 --- a/spacy/errors.py +++ b/spacy/errors.py @@ -871,6 +871,8 @@ class Errors: "the documentation:\nhttps://spacy.io/usage/models") E1020 = ("No `epoch_resume` value specified and could not infer one from " "filename. Specify an epoch to resume from.") + E1021 = ("`pos` value \"{pp}\" is not a valid Universal Dependencies tag. " + "Non-UD tags should use the `tag` property.") # Deprecated model shortcuts, only used in errors and warnings diff --git a/spacy/tests/doc/test_creation.py b/spacy/tests/doc/test_creation.py index 6989b965f..302a9b6ea 100644 --- a/spacy/tests/doc/test_creation.py +++ b/spacy/tests/doc/test_creation.py @@ -70,3 +70,10 @@ def test_create_with_heads_and_no_deps(vocab): heads = list(range(len(words))) with pytest.raises(ValueError): Doc(vocab, words=words, heads=heads) + + +def test_create_invalid_pos(vocab): + words = "I like ginger".split() + pos = "QQ ZZ XX".split() + with pytest.raises(ValueError): + Doc(vocab, words=words, pos=pos) diff --git a/spacy/tests/doc/test_token_api.py b/spacy/tests/doc/test_token_api.py index 5ea0bcff0..38178cd00 100644 --- a/spacy/tests/doc/test_token_api.py +++ b/spacy/tests/doc/test_token_api.py @@ -202,6 +202,10 @@ def test_set_pos(): doc[1].pos = VERB assert doc[1].pos_ == "VERB" +def test_set_invalid_pos(): + doc = Doc(Vocab(), words=["hello", "world"]) + with pytest.raises(ValueError): + doc[0].pos_ = "blah" def test_tokens_sent(doc): """Test token.sent property""" diff --git a/spacy/tokens/doc.pyx b/spacy/tokens/doc.pyx index cd2bd6f6c..b3eda26e1 100644 --- a/spacy/tokens/doc.pyx +++ b/spacy/tokens/doc.pyx @@ -30,6 +30,7 @@ from ..compat import copy_reg, pickle from ..errors import Errors, Warnings from ..morphology import Morphology from .. import util +from .. import parts_of_speech from .underscore import Underscore, get_ext_args from ._retokenize import Retokenizer from ._serialize import ALL_ATTRS as DOCBIN_ALL_ATTRS @@ -285,6 +286,10 @@ cdef class Doc: sent_starts[i] = -1 elif sent_starts[i] is None or sent_starts[i] not in [-1, 0, 1]: sent_starts[i] = 0 + if pos is not None: + for pp in set(pos): + if pp not in parts_of_speech.IDS: + raise ValueError(Errors.E1021.format(pp=pp)) ent_iobs = None ent_types = None if ents is not None: diff --git a/spacy/tokens/token.pyx b/spacy/tokens/token.pyx index 3fcfda691..9277eb6fa 100644 --- a/spacy/tokens/token.pyx +++ b/spacy/tokens/token.pyx @@ -867,6 +867,8 @@ cdef class Token: return parts_of_speech.NAMES[self.c.pos] def __set__(self, pos_name): + if pos_name not in parts_of_speech.IDS: + raise ValueError(Errors.E1021.format(pp=pos_name)) self.c.pos = parts_of_speech.IDS[pos_name] property tag_: From 8bda39f088b1f0943ebd12f5ac425dcc74c4e5f0 Mon Sep 17 00:00:00 2001 From: Edward <43848523+thomashacker@users.noreply.github.com> Date: Thu, 16 Sep 2021 13:32:44 +0200 Subject: [PATCH 61/70] Update Hammurabi example code to v3 (#9218) * Update Hammurabi example code * Fix typo --- website/meta/universe.json | 64 +++++++++++++++++++++++++++----------- 1 file changed, 46 insertions(+), 18 deletions(-) diff --git a/website/meta/universe.json b/website/meta/universe.json index 6e5696be1..396f56bf4 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -3238,33 +3238,61 @@ "github": "babylonhealth/hmrb", "pip": "hmrb", "code_example": [ - "import spacy # __version__ 3.0+", + "import spacy", "from hmrb.core import SpacyCore", "", + "nlp = spacy.load(\"en_core_web_sm\")", + "sentences = \"I love gorillas. Peter loves gorillas. Jane loves Tarzan.\"", + "", + "def conj_be(subj: str) -> str:", + " if subj == \"I\":", + " return \"am\"", + " elif subj == \"you\":", + " return \"are\"", + " else:", + " return \"is\"", + "", + "@spacy.registry.callbacks(\"gorilla_callback\")", + "def gorilla_clb(seq: list, span: slice, data: dict) -> None:", + " subj = seq[span.start].text", + " be = conj_be(subj)", + " print(f\"{subj} {be} a gorilla person.\")", + "@spacy.registry.callbacks(\"lover_callback\")", + "def lover_clb(seq: list, span: slice, data: dict) -> None:", + " print(f\"{seq[span][-1].text} is a love interest of {seq[span.start].text}.\")", + "", "grammar = \"\"\"", - "Var is_hurting:", - "(", - " optional (lemma: \"be\")", - " (lemma: \"hurt\")", - ")", - "Law:", - " - package: \"headache\"", - " - callback: \"mark_headache\"", - "(", - " (lemma: \"head\", pos: \"NOUN\")", - " $is_hurting", - ")\"\"\"", + " Law:", + " - callback: \"loves_gorilla\"", + " (", + " ((pos: \"PROPN\") or (pos: \"PRON\"))", + " (lemma: \"love\")", + " (lemma: \"gorilla\")", + " )", + " Law:", + " - callback: \"loves_someone\"", + " (", + " (pos: \"PROPN\")", + " (lower: \"loves\")", + " (pos: \"PROPN\")", + " )", + "\"\"\"", + "", + "@spacy.registry.augmenters(\"jsonify_span\")", + "def jsonify_span(span):", + " return [{\"lemma\": token.lemma_, \"pos\": token.pos_, \"lower\": token.lower_} for token in span]", "", "conf = {", - " \"rules\": grammar", + " \"rules\": grammar,", " \"callbacks\": {", - " \"mark_headache\": \"callbacks.headache_handler\",", - " },", + " \"loves_gorilla\": \"callbacks.gorilla_callback\",", + " \"loves_someone\": \"callbacks.lover_callback\",", + " },", " \"map_doc\": \"augmenters.jsonify_span\",", " \"sort_length\": True,", "}", - "nlp = spacy.load(\"en_core_web_sm\")", - "nlp.add_pipe(\"hammurabi\", config=conf)", + "", + "nlp.add_pipe(\"hmrb\", config=conf)", "nlp(sentences)" ], "code_language": "python", From 015d439eb6d79d8d9c3dca9f07901714e9d47958 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 20 Sep 2021 08:49:19 +0200 Subject: [PATCH 62/70] Auto-format code with black (#9234) Co-authored-by: explosion-bot --- spacy/tests/doc/test_token_api.py | 2 ++ spacy/training/loggers.py | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/spacy/tests/doc/test_token_api.py b/spacy/tests/doc/test_token_api.py index 38178cd00..e715c5e85 100644 --- a/spacy/tests/doc/test_token_api.py +++ b/spacy/tests/doc/test_token_api.py @@ -202,11 +202,13 @@ def test_set_pos(): doc[1].pos = VERB assert doc[1].pos_ == "VERB" + def test_set_invalid_pos(): doc = Doc(Vocab(), words=["hello", "world"]) with pytest.raises(ValueError): doc[0].pos_ = "blah" + def test_tokens_sent(doc): """Test token.sent property""" assert len(list(doc.sents)) == 3 diff --git a/spacy/training/loggers.py b/spacy/training/loggers.py index 524b422a5..137e89e56 100644 --- a/spacy/training/loggers.py +++ b/spacy/training/loggers.py @@ -206,7 +206,9 @@ def wandb_logger( for field in remove_config_values: del config_dot[field] config = util.dot_to_dict(config_dot) - run = wandb.init(project=project_name, config=config, entity=entity, reinit=True) + run = wandb.init( + project=project_name, config=config, entity=entity, reinit=True + ) if run_name: wandb.run.name = run_name From 00bdb311506c1ca4236296267c3e98e9f65f424c Mon Sep 17 00:00:00 2001 From: Adriane Boyd Date: Mon, 20 Sep 2021 20:22:49 +0200 Subject: [PATCH 63/70] Fix vector for 0-length span (#9244) --- spacy/tests/doc/test_span.py | 22 ++++++++++++++++++++++ spacy/tokens/span.pyx | 6 +++++- 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/spacy/tests/doc/test_span.py b/spacy/tests/doc/test_span.py index 01b022b9d..5644e5a8b 100644 --- a/spacy/tests/doc/test_span.py +++ b/spacy/tests/doc/test_span.py @@ -5,7 +5,9 @@ from spacy.attrs import ORTH, LENGTH from spacy.tokens import Doc, Span, Token from spacy.vocab import Vocab from spacy.util import filter_spans +from thinc.api import get_current_ops +from ..util import add_vecs_to_vocab from .test_underscore import clean_underscore # noqa: F401 @@ -412,3 +414,23 @@ def test_sent(en_tokenizer): assert not span.doc.has_annotation("SENT_START") with pytest.raises(ValueError): span.sent + + +def test_span_with_vectors(doc): + ops = get_current_ops() + prev_vectors = doc.vocab.vectors + vectors = [ + ("apple", ops.asarray([1, 2, 3])), + ("orange", ops.asarray([-1, -2, -3])), + ("And", ops.asarray([-1, -1, -1])), + ("juice", ops.asarray([5, 5, 10])), + ("pie", ops.asarray([7, 6.3, 8.9])), + ] + add_vecs_to_vocab(doc.vocab, vectors) + # 0-length span + assert_array_equal(ops.to_numpy(doc[0:0].vector), numpy.zeros((3, ))) + # longer span with no vector + assert_array_equal(ops.to_numpy(doc[0:4].vector), numpy.zeros((3, ))) + # single-token span with vector + assert_array_equal(ops.to_numpy(doc[10:11].vector), [-1, -1, -1]) + doc.vocab.vectors = prev_vectors diff --git a/spacy/tokens/span.pyx b/spacy/tokens/span.pyx index 093e8c826..050a70d02 100644 --- a/spacy/tokens/span.pyx +++ b/spacy/tokens/span.pyx @@ -474,7 +474,11 @@ cdef class Span: if "vector" in self.doc.user_span_hooks: return self.doc.user_span_hooks["vector"](self) if self._vector is None: - self._vector = sum(t.vector for t in self) / len(self) + if not len(self): + xp = get_array_module(self.vocab.vectors.data) + self._vector = xp.zeros((self.vocab.vectors_length,), dtype="f") + else: + self._vector = sum(t.vector for t in self) / len(self) return self._vector @property From 17802836be8b761fc7c37e2006ac43841ac1565f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20de=20Kok?= Date: Tue, 21 Sep 2021 10:49:45 +0200 Subject: [PATCH 64/70] Allow overriding vars in the project assets subcommand (#9248) This change makes the `project assets` subcommand accept variables to override as well, making the interface more similar to `project run`. --- spacy/cli/project/assets.py | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/spacy/cli/project/assets.py b/spacy/cli/project/assets.py index 70fcd0ecf..efc93efab 100644 --- a/spacy/cli/project/assets.py +++ b/spacy/cli/project/assets.py @@ -1,18 +1,24 @@ -from typing import Optional +from typing import Any, Dict, Optional from pathlib import Path from wasabi import msg import re import shutil import requests +import typer from ...util import ensure_path, working_dir from .._util import project_cli, Arg, Opt, PROJECT_FILE, load_project_config from .._util import get_checksum, download_file, git_checkout, get_git_version +from .._util import SimpleFrozenDict, parse_config_overrides -@project_cli.command("assets") +@project_cli.command( + "assets", + context_settings={"allow_extra_args": True, "ignore_unknown_options": True}, +) def project_assets_cli( # fmt: off + ctx: typer.Context, # This is only used to read additional arguments project_dir: Path = Arg(Path.cwd(), help="Path to cloned project. Defaults to current working directory.", exists=True, file_okay=False), sparse_checkout: bool = Opt(False, "--sparse", "-S", help="Use sparse checkout for assets provided via Git, to only check out and clone the files needed. Requires Git v22.2+.") # fmt: on @@ -24,16 +30,22 @@ def project_assets_cli( DOCS: https://spacy.io/api/cli#project-assets """ - project_assets(project_dir, sparse_checkout=sparse_checkout) + overrides = parse_config_overrides(ctx.args) + project_assets(project_dir, overrides=overrides, sparse_checkout=sparse_checkout) -def project_assets(project_dir: Path, *, sparse_checkout: bool = False) -> None: +def project_assets( + project_dir: Path, + *, + overrides: Dict[str, Any] = SimpleFrozenDict(), + sparse_checkout: bool = False, +) -> None: """Fetch assets for a project using DVC if possible. project_dir (Path): Path to project directory. """ project_path = ensure_path(project_dir) - config = load_project_config(project_path) + config = load_project_config(project_path, overrides=overrides) assets = config.get("assets", {}) if not assets: msg.warn(f"No assets specified in {PROJECT_FILE}", exits=0) From 3fc3b7a13af2e15d8cb0cc90860d7861d3ad7ddf Mon Sep 17 00:00:00 2001 From: Sofie Van Landeghem Date: Wed, 22 Sep 2021 21:01:34 +0200 Subject: [PATCH 65/70] avoid crash when unicode in title (#9254) --- spacy/cli/project/run.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spacy/cli/project/run.py b/spacy/cli/project/run.py index 3736a6e1c..74c8b24b6 100644 --- a/spacy/cli/project/run.py +++ b/spacy/cli/project/run.py @@ -1,6 +1,7 @@ from typing import Optional, List, Dict, Sequence, Any, Iterable from pathlib import Path from wasabi import msg +from wasabi.util import locale_escape import sys import srsly import typer @@ -135,7 +136,7 @@ def print_run_help(project_dir: Path, subcommand: Optional[str] = None) -> None: print("") title = config.get("title") if title: - print(f"{title}\n") + print(f"{locale_escape(title)}\n") if config_commands: print(f"Available commands in {PROJECT_FILE}") print(f"Usage: {COMMAND} project run [COMMAND] {project_loc}") From 57b5fc1995ded2f4bb9dd6305c567cdd4c1151ee Mon Sep 17 00:00:00 2001 From: Ines Montani Date: Thu, 23 Sep 2021 17:58:32 +1000 Subject: [PATCH 66/70] Apply suggestions from code review Co-authored-by: Renat Shigapov <57352291+shigapov@users.noreply.github.com> --- spacy/displacy/render.py | 6 +++++- spacy/displacy/templates.py | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/spacy/displacy/render.py b/spacy/displacy/render.py index bd7178724..406824eb4 100644 --- a/spacy/displacy/render.py +++ b/spacy/displacy/render.py @@ -316,6 +316,10 @@ class EntityRenderer: end = span["end"] kb_id = span.get("kb_id", "") kb_url = span.get("kb_url", "") + if kb_id: + kb_link = """{}""".format(kb_url, kb_id) + else: + kb_link = "" additional_params = span.get("params", {}) entity = escape_html(text[start:end]) fragments = text[offset:start].split("\n") @@ -325,7 +329,7 @@ class EntityRenderer: markup += "
" if self.ents is None or label.upper() in self.ents: color = self.colors.get(label.upper(), self.default_color) - ent_settings = {"label": label, "text": entity, "bg": color, "kb_id": kb_id, "kb_url": kb_url} + ent_settings = {"label": label, "text": entity, "bg": color, "kb_link": kb_link} ent_settings.update(additional_params) markup += self.ent_template.format(**ent_settings) else: diff --git a/spacy/displacy/templates.py b/spacy/displacy/templates.py index 051f72cb2..53fcc1873 100644 --- a/spacy/displacy/templates.py +++ b/spacy/displacy/templates.py @@ -52,7 +52,7 @@ TPL_ENT = """ {text} {label} - {kb_id} + {kb_link} """ From d2adfe1efaeff2ee466521aaf3ddd3719cdc2135 Mon Sep 17 00:00:00 2001 From: Philip Vollet Date: Thu, 23 Sep 2021 10:56:45 +0200 Subject: [PATCH 67/70] Add projects to spaCy Universe (#9269) * Added spaCy Universe projects * Added user license agreement Philip Vollet * Update website/meta/universe.json Co-authored-by: Sofie Van Landeghem * Update website/meta/universe.json Co-authored-by: Sofie Van Landeghem * Update website/meta/universe.json Co-authored-by: Sofie Van Landeghem Co-authored-by: Sofie Van Landeghem --- .github/contributors/philipvollet.md | 106 ++++++++++++++++++++++++ website/meta/universe.json | 117 ++++++++++++++++++++++++++- 2 files changed, 222 insertions(+), 1 deletion(-) create mode 100644 .github/contributors/philipvollet.md diff --git a/.github/contributors/philipvollet.md b/.github/contributors/philipvollet.md new file mode 100644 index 000000000..0bf58a701 --- /dev/null +++ b/.github/contributors/philipvollet.md @@ -0,0 +1,106 @@ +# spaCy contributor agreement + +This spaCy Contributor Agreement (**"SCA"**) is based on the +[Oracle Contributor Agreement](http://www.oracle.com/technetwork/oca-405177.pdf). +The SCA applies to any contribution that you make to any product or project +managed by us (the **"project"**), and sets out the intellectual property rights +you grant to us in the contributed materials. The term **"us"** shall mean +[ExplosionAI GmbH](https://explosion.ai/legal). The term +**"you"** shall mean the person or entity identified below. + +If you agree to be bound by these terms, fill in the information requested +below and include the filled-in version with your first pull request, under the +folder [`.github/contributors/`](/.github/contributors/). The name of the file +should be your GitHub username, with the extension `.md`. For example, the user +example_user would create the file `.github/contributors/example_user.md`. + +Read this agreement carefully before signing. These terms and conditions +constitute a binding legal agreement. + +## Contributor Agreement + +1. The term "contribution" or "contributed materials" means any source code, +object code, patch, tool, sample, graphic, specification, manual, +documentation, or any other material posted or submitted by you to the project. + +2. With respect to any worldwide copyrights, or copyright applications and +registrations, in your contribution: + + * you hereby assign to us joint ownership, and to the extent that such + assignment is or becomes invalid, ineffective or unenforceable, you hereby + grant to us a perpetual, irrevocable, non-exclusive, worldwide, no-charge, + royalty-free, unrestricted license to exercise all rights under those + copyrights. This includes, at our option, the right to sublicense these same + rights to third parties through multiple levels of sublicensees or other + licensing arrangements; + + * you agree that each of us can do all things in relation to your + contribution as if each of us were the sole owners, and if one of us makes + a derivative work of your contribution, the one who makes the derivative + work (or has it made will be the sole owner of that derivative work; + + * you agree that you will not assert any moral rights in your contribution + against us, our licensees or transferees; + + * you agree that we may register a copyright in your contribution and + exercise all ownership rights associated with it; and + + * you agree that neither of us has any duty to consult with, obtain the + consent of, pay or render an accounting to the other for any use or + distribution of your contribution. + +3. With respect to any patents you own, or that you can license without payment +to any third party, you hereby grant to us a perpetual, irrevocable, +non-exclusive, worldwide, no-charge, royalty-free license to: + + * make, have made, use, sell, offer to sell, import, and otherwise transfer + your contribution in whole or in part, alone or in combination with or + included in any product, work or materials arising out of the project to + which your contribution was submitted, and + + * at our option, to sublicense these same rights to third parties through + multiple levels of sublicensees or other licensing arrangements. + +4. Except as set out above, you keep all right, title, and interest in your +contribution. The rights that you grant to us under these terms are effective +on the date you first submitted a contribution to us, even if your submission +took place before the date you sign these terms. + +5. You covenant, represent, warrant and agree that: + + * Each contribution that you submit is and shall be an original work of + authorship and you can legally grant the rights set out in this SCA; + + * to the best of your knowledge, each contribution will not violate any + third party's copyrights, trademarks, patents, or other intellectual + property rights; and + + * each contribution shall be in compliance with U.S. export control laws and + other applicable export and import laws. You agree to notify us if you + become aware of any circumstance which would make any of the foregoing + representations inaccurate in any respect. We may publicly disclose your + participation in the project, including the fact that you have signed the SCA. + +6. This SCA is governed by the laws of the State of California and applicable +U.S. Federal law. Any choice of law rules will not apply. + +7. Please place an “x” on one of the applicable statement below. Please do NOT +mark both statements: + + * [x] I am signing on behalf of myself as an individual and no other person + or entity, including my employer, has or will have rights with respect to my + contributions. + + * [ ] I am signing on behalf of my employer or a legal entity and I have the + actual authority to contractually bind that entity. + +## Contributor Details + +| Field | Entry | +|------------------------------- | -------------------- | +| Name | Philip Vollet | +| Company name (if applicable) | | +| Title or role (if applicable) | | +| Date | 22.09.2021 | +| GitHub username | philipvollet | +| Website (optional) | | diff --git a/website/meta/universe.json b/website/meta/universe.json index 396f56bf4..28fe058eb 100644 --- a/website/meta/universe.json +++ b/website/meta/universe.json @@ -516,12 +516,12 @@ "title": "NeuroNER", "slogan": "Named-entity recognition using neural networks", "github": "Franck-Dernoncourt/NeuroNER", + "category": ["ner"], "pip": "pyneuroner[cpu]", "code_example": [ "from neuroner import neuromodel", "nn = neuromodel.NeuroNER(train_model=False, use_pretrained_model=True)" ], - "category": ["ner"], "tags": ["standalone"] }, { @@ -1135,6 +1135,26 @@ }, "category": ["visualizers"] }, + { + "id": "deplacy", + "slogan": "CUI-based Tree Visualizer for Universal Dependencies and Immediate Catena Analysis", + "discreption": "Simple dependency visualizer for [spaCy](https://spacy.io/), [UniDic2UD](https://pypi.org/project/unidic2ud), [Stanza](https://stanfordnlp.github.io/stanza/), [NLP-Cube](https://github.com/Adobe/NLP-Cube), [Trankit](https://github.com/nlp-uoregon/trankit), etc.", + "github": "KoichiYasuoka/deplacy", + "image": "https://i.imgur.com/6uOI4Op.png", + "code_example": [ + "import spacy", + "import deplacy", + "", + "nlp=spacy.load('en_core_web_sm')", + "doc=nlp('I saw a horse yesterday which had no name.')", + "deplacy.render(doc)" + ], + "author": "Koichi Yasuoka", + "author_links": { + "github": "KoichiYasuoka" + }, + "category": ["visualizers"] + }, { "id": "scattertext", "slogan": "Beautiful visualizations of how language differs among document types", @@ -1679,6 +1699,22 @@ }, "category": ["books"] }, + { + "type": "education", + "id": "applied-nlp-in-enterprise", + "title": "Applied Natural Language Processing in the Enterprise: Teaching Machines to Read, Write, and Understand", + "slogan": "O'Reilly, 2021", + "description": "Natural language processing (NLP) is one of the hottest topics in AI today. Having lagged behind other deep learning fields such as computer vision for years, NLP only recently gained mainstream popularity. Even though Google, Facebook, and OpenAI have open sourced large pretrained language models to make NLP easier, many organizations today still struggle with developing and productionizing NLP applications. This hands-on guide helps you learn the field quickly.", + "github": "nlpbook/nlpbook", + "cover": "https://i.imgur.com/6RxLBvf.jpg", + "url": "https://www.amazon.com/dp/149206257X", + "author": "Ankur A. Patel", + "author_links": { + "github": "aapatel09", + "website": "https://www.ankurapatel.io" + }, + "category": ["books"] + }, { "type": "education", "id": "learning-path-spacy", @@ -1690,6 +1726,16 @@ "author": "Aaron Kramer", "category": ["courses"] }, + { + "type": "education", + "id": "introduction-into-spacy-3", + "title": "Introduction to spaCy 3", + "slogan": "A free course for beginners by Dr. W.J.B. Mattingly", + "url": "http://spacy.pythonhumanities.com/", + "thumb": "https://spacy.pythonhumanities.com/_static/freecodecamp_small.jpg", + "author": "Dr. W.J.B. Mattingly", + "category": ["courses"] + }, { "type": "education", "id": "spacy-course", @@ -2556,6 +2602,75 @@ "website": "https://explosion.ai" } }, + { + "id": "spacy-huggingface-hub", + "title": "spacy-huggingface-hub", + "slogan": "Push your spaCy pipelines to the Hugging Face Hub", + "description": "This package provides a CLI command for uploading any trained spaCy pipeline packaged with [`spacy package`](https://spacy.io/api/cli#package) to the [Hugging Face Hub](https://huggingface.co). It auto-generates all meta information for you, uploads a pretty README (requires spaCy v3.1+) and handles version control under the hood.", + "github": "explosion/spacy-huggingface-hub", + "thumb": "https://i.imgur.com/j6FO9O6.jpg", + "url": "https://github.com/explosion/spacy-huggingface-hub", + "pip": "spacy-huggingface-hub", + "category": ["pipeline", "models"], + "author": "Explosion", + "author_links": { + "twitter": "explosion_ai", + "github": "explosion", + "website": "https://explosion.ai" + } + }, + { + "id": "spacy-clausie", + "title": "spacy-clausie", + "slogan": "Implementation of the ClausIE information extraction system for Python+spaCy", + "github": "mmxgn/spacy-clausie", + "url": "https://github.com/mmxgn/spacy-clausie", + "description": "ClausIE, a novel, clause-based approach to open information extraction, which extracts relations and their arguments from natural language text", + "category": ["pipeline", "scientific", "research"], + "code_example": [ + "import spacy", + "import claucy", + "", + "nlp = spacy.load(\"en\")", + "claucy.add_to_pipe(nlp)", + "", + "doc = nlp(\"AE died in Princeton in 1955.\")", + "", + "print(doc._.clauses)", + "# Output:", + "# ", + "", + "propositions = doc._.clauses[0].to_propositions(as_text=True)", + "", + "print(propositions)", + "# Output:", + "# [AE died in Princeton in 1955, AE died in 1955, AE died in Princeton" + ], + "author": "Emmanouil Theofanis Chourdakis", + "author_links": { + "github": "mmxgn" + } + }, + { + "id": "ipymarkup", + "slogan": "NER, syntax markup visualizations", + "description": "Collection of NLP visualizations for NER and syntax tree markup. Similar to [displaCy](https://explosion.ai/demos/displacy) and [displaCy ENT](https://explosion.ai/demos/displacy-ent).", + "github": "natasha/ipymarkup", + "image": "https://github.com/natasha/ipymarkup/blob/master/table.png?raw=true", + "pip":"pip install ipymarkup", + "code_example": [ + "from ipymarkup import show_span_ascii_markup, show_dep_ascii_markup", + "", + "text = 'В мероприятии примут участие не только российские учёные, но и зарубежные исследователи, в том числе, Крис Хелмбрехт - управляющий директор и совладелец креативного агентства Kollektiv (Германия, США), Ннека Угбома - руководитель проекта Mushroom works (Великобритания), Гергей Ковач - политик и лидер субкультурной партии «Dog with two tails» (Венгрия), Георг Жено - немецкий режиссёр, один из создателей экспериментального театра «Театр.doc», Театра им. Йозефа Бойса (Германия).'", + "spans = [(102, 116, 'PER'), (186, 194, 'LOC'), (196, 199, 'LOC'), (202, 214, 'PER'), (254, 268, 'LOC'), (271, 283, 'PER'), (324, 342, 'ORG'), (345, 352, 'LOC'), (355, 365, 'PER'), (445, 455, 'ORG'), (456, 468, 'PER'), (470, 478, 'LOC')]", + "show_span_ascii_markup(text, spans)" + ], + "author": "Alexander Kukushkin", + "author_links": { + "github": "kuk" + }, + "category": ["visualizers"] + }, { "id": "negspacy", "title": "negspaCy", From 6bb0324b8181b91832d19de8c00f530c26a8c16e Mon Sep 17 00:00:00 2001 From: Ines Montani Date: Thu, 23 Sep 2021 11:59:02 +0200 Subject: [PATCH 68/70] Adjust kb_id visualizer templating and docs --- spacy/displacy/render.py | 16 +++++++++------- spacy/displacy/templates.py | 11 +++++++---- website/docs/usage/visualizers.md | 11 ++++++++++- 3 files changed, 26 insertions(+), 12 deletions(-) diff --git a/spacy/displacy/render.py b/spacy/displacy/render.py index 406824eb4..14d741a3d 100644 --- a/spacy/displacy/render.py +++ b/spacy/displacy/render.py @@ -3,7 +3,7 @@ import uuid from .templates import TPL_DEP_SVG, TPL_DEP_WORDS, TPL_DEP_WORDS_LEMMA, TPL_DEP_ARCS from .templates import TPL_ENT, TPL_ENT_RTL, TPL_FIGURE, TPL_TITLE, TPL_PAGE -from .templates import TPL_ENTS +from .templates import TPL_ENTS, TPL_KB_LINK from ..util import minify_html, escape_html, registry from ..errors import Errors @@ -315,11 +315,8 @@ class EntityRenderer: start = span["start"] end = span["end"] kb_id = span.get("kb_id", "") - kb_url = span.get("kb_url", "") - if kb_id: - kb_link = """{}""".format(kb_url, kb_id) - else: - kb_link = "" + kb_url = span.get("kb_url", "#") + kb_link = TPL_KB_LINK.format(kb_id=kb_id, kb_url=kb_url) if kb_id else "" additional_params = span.get("params", {}) entity = escape_html(text[start:end]) fragments = text[offset:start].split("\n") @@ -329,7 +326,12 @@ class EntityRenderer: markup += "
" if self.ents is None or label.upper() in self.ents: color = self.colors.get(label.upper(), self.default_color) - ent_settings = {"label": label, "text": entity, "bg": color, "kb_link": kb_link} + ent_settings = { + "label": label, + "text": entity, + "bg": color, + "kb_link": kb_link, + } ent_settings.update(additional_params) markup += self.ent_template.format(**ent_settings) else: diff --git a/spacy/displacy/templates.py b/spacy/displacy/templates.py index 53fcc1873..e7d3d4266 100644 --- a/spacy/displacy/templates.py +++ b/spacy/displacy/templates.py @@ -51,19 +51,22 @@ TPL_ENTS = """ TPL_ENT = """ {text} - {label} - {kb_link} - + {label}{kb_link} """ TPL_ENT_RTL = """ {text} - {label} + {label}{kb_link} """ +# Important: this needs to start with a space! +TPL_KB_LINK = """ + {kb_id} +""" + TPL_PAGE = """ diff --git a/website/docs/usage/visualizers.md b/website/docs/usage/visualizers.md index cb643aed1..072718f91 100644 --- a/website/docs/usage/visualizers.md +++ b/website/docs/usage/visualizers.md @@ -297,7 +297,7 @@ position. > > ```python > ex = [{"text": "But Google is starting from behind.", -> "ents": [{"start": 4, "end": 10, "label": "ORG", "kb_id": "Q95", "kb_url": "https://www.wikidata.org/entity/Q95"}], +> "ents": [{"start": 4, "end": 10, "label": "ORG"}], > "title": None}] > html = displacy.render(ex, style="ent", manual=True) > ``` @@ -321,6 +321,15 @@ position. ```python ### ENT input +{ + "text": "But Google is starting from behind.", + "ents": [{"start": 4, "end": 10, "label": "ORG"}], + "title": None +} +``` + +```python +### ENT input with knowledge base links { "text": "But Google is starting from behind.", "ents": [{"start": 4, "end": 10, "label": "ORG", "kb_id": "Q95", "kb_url": "https://www.wikidata.org/entity/Q95"}], From 4da2af4e0e522496f9418ae3721262f7e8254050 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 24 Sep 2021 10:46:43 +0200 Subject: [PATCH 69/70] Auto-format code with black (#9284) Co-authored-by: explosion-bot --- spacy/tests/doc/test_span.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spacy/tests/doc/test_span.py b/spacy/tests/doc/test_span.py index 5644e5a8b..2503ad94c 100644 --- a/spacy/tests/doc/test_span.py +++ b/spacy/tests/doc/test_span.py @@ -428,9 +428,9 @@ def test_span_with_vectors(doc): ] add_vecs_to_vocab(doc.vocab, vectors) # 0-length span - assert_array_equal(ops.to_numpy(doc[0:0].vector), numpy.zeros((3, ))) + assert_array_equal(ops.to_numpy(doc[0:0].vector), numpy.zeros((3,))) # longer span with no vector - assert_array_equal(ops.to_numpy(doc[0:4].vector), numpy.zeros((3, ))) + assert_array_equal(ops.to_numpy(doc[0:4].vector), numpy.zeros((3,))) # single-token span with vector assert_array_equal(ops.to_numpy(doc[10:11].vector), [-1, -1, -1]) doc.vocab.vectors = prev_vectors From 12ab49342c2be36ade4b55cb851471a7a93a5f6f Mon Sep 17 00:00:00 2001 From: Adriane Boyd Date: Mon, 27 Sep 2021 09:16:31 +0200 Subject: [PATCH 70/70] Sync requirements in setup.cfg --- setup.cfg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.cfg b/setup.cfg index ff12d511a..fe484f92e 100644 --- a/setup.cfg +++ b/setup.cfg @@ -44,7 +44,7 @@ install_requires = murmurhash>=0.28.0,<1.1.0 cymem>=2.0.2,<2.1.0 preshed>=3.0.2,<3.1.0 - thinc>=8.0.9,<8.1.0 + thinc>=8.0.10,<8.1.0 blis>=0.4.0,<0.8.0 wasabi>=0.8.1,<1.1.0 srsly>=2.4.1,<3.0.0