bede11b67c
This patch does a few smallish things that tighten up the training workflow a little, and allow memory use during training to be reduced by letting the GoldCorpus stream data properly. Previously, the parser and entity recognizer read and saved labels as lists, with extra labels noted separately. Lists were used becaue ordering is very important, to ensure that the label-to-class mapping is stable. We now manage labels as nested dictionaries, first keyed by the action, and then keyed by the label. Values are frequencies. The trick is, how do we save new labels? We need to make sure we iterate over these in the same order they're added. Otherwise, we'll get different class IDs, and the model's predictions won't make sense. To allow stable sorting, we map the new labels to negative values. If we have two new labels, they'll be noted as having "frequency" -1 and -2. The next new label will then have "frequency" -3. When we sort by (frequency, label), we then get a stable sort. Storing frequencies then allows us to make the next nice improvement. Previously we had to iterate over the whole training set, to pre-process it for the deprojectivisation. This led to storing the whole training set in memory. This was most of the required memory during training. To prevent this, we now store the frequencies as we stream in the data, and deprojectivize as we go. Once we've built the frequencies, we can then apply a frequency cut-off when we decide how many classes to make. Finally, to allow proper data streaming, we also have to have some way of shuffling the iterator. This is awkward if the training files have multiple documents in them. To solve this, the GoldCorpus class now writes the training data to disk in msgpack files, one per document. We can then shuffle the data by shuffling the paths. This is a squash merge, as I made a lot of very small commits. Individual commit messages below. * Simplify label management for TransitionSystem and its subclasses * Fix serialization for new label handling format in parser * Simplify and improve GoldCorpus class. Reduce memory use, write to temp dir * Set actions in transition system * Require thinc 6.11.1.dev4 * Fix error in parser init * Add unicode declaration * Fix unicode declaration * Update textcat test * Try to get model training on less memory * Print json loc for now * Try rapidjson to reduce memory use * Remove rapidjson requirement * Try rapidjson for reduced mem usage * Handle None heads when projectivising * Stream json docs * Fix train script * Handle projectivity in GoldParse * Fix projectivity handling * Add minibatch_by_words util from ud_train * Minibatch by number of words in spacy.cli.train * Move minibatch_by_words util to spacy.util * Fix label handling * More hacking at label management in parser * Fix encoding in msgpack serialization in GoldParse * Adjust batch sizes in parser training * Fix minibatch_by_words * Add merge_subtokens function to pipeline.pyx * Register merge_subtokens factory * Restore use of msgpack tmp directory * Use minibatch-by-words in train * Handle retokenization in scorer * Change back-off approach for missing labels. Use 'dep' label * Update NER for new label management * Set NER tags for over-segmented words * Fix label alignment in gold * Fix label back-off for infrequent labels * Fix int type in labels dict key * Fix int type in labels dict key * Update feature definition for 8 feature set * Update ud-train script for new label stuff * Fix json streamer * Print the line number if conll eval fails * Update children and sentence boundaries after deprojectivisation * Export set_children_from_heads from doc.pxd * Render parses during UD training * Remove print statement * Require thinc 6.11.1.dev6. Try adding wheel as install_requires * Set different dev version, to flush pip cache * Update thinc version * Update GoldCorpus docs * Remove print statements * Fix formatting and links [ci skip] |
||
|---|---|---|
| .. | ||
| _includes | ||
| api | ||
| assets | ||
| models | ||
| usage | ||
| _data.json | ||
| _harp.json | ||
| _layout.jade | ||
| 404.jade | ||
| index.jade | ||
| package.json | ||
| README.md | ||
| robots.txt.jade | ||
| styleguide.jade | ||
spacy.io website and docs
The spacy.io website is implemented in Jade (aka Pug), and is built or served by Harp. Jade is an extensible templating language with a readable syntax, that compiles to HTML. The website source makes extensive use of Jade mixins, so that the design system is abstracted away from the content you're writing. You can read more about our approach in our blog post, "Rebuilding a Website with Modular Markup".
Viewing the site locally
sudo npm install --global harp
git clone https://github.com/explosion/spaCy
cd spaCy/website
harp server
This will serve the site on http://localhost:9000.
Making changes to the site
The docs can always use another example or more detail, and they should always be up to date and not misleading. If you see something, say something – we always appreciate a pull request. To quickly find the correct file to edit, simply click on the "Suggest edits" button at the bottom of a page.
File structure
While all page content lives in the .jade files, article meta (page titles, sidebars etc.) is stored as JSON. Each folder contains a _data.json with all required meta for its files.
For simplicity, all sites linked in the tutorials and showcase are also stored as JSON. So in order to edit those pages, there's no need to dig into the Jade files – simply edit the _data.json.
Markup language and conventions
Jade/Pug is a whitespace-sensitive markup language that compiles to HTML. Indentation is used to nest elements, and for template logic, like if/else or for, mainly used to iterate over objects and arrays in the meta data. It also allows inline JavaScript expressions.
For an overview of Harp and Jade, see this blog post. For more info on the Jade/Pug syntax, check out their documentation.
In the spacy.io source, we use 4 spaces to indent and hard-wrap at 80 characters.
p This is a very short paragraph. It stays inline.
p
| This is a much longer paragraph. It's hard-wrapped at 80 characters to
| make it easier to read on GitHub and in editors that do not have soft
| wrapping enabled. To prevent Jade from interpreting each line as a new
| element, it's prefixed with a pipe and two spaces. This ensures that no
| spaces are dropped – for example, if your editor strips out trailing
| whitespace by default. Inline links are added using the inline syntax,
| like this: #[+a("https://google.com") Google].
Note that for external links, +a("...") is used instead of a(href="...") – it's a mixin that takes care of adding all required attributes. If possible, always use a mixin instead of regular HTML elements. The only plain HTML elements we use are:
| Element | Description |
|---|---|
p |
paragraphs |
code |
inline code |
em |
italicized text |
strong |
bold text |
Mixins
Each file includes a collection of custom mixins that make it easier to add content components – no HTML or class names required.
For example:
//- Bulleted list
+list
+item This is a list item.
+item This is another list item.
//- Table with header
+table([ "Header one", "Header two" ])
+row
+cell Table cell
+cell Another one
+row
+cell And one more.
+cell And the last one.
//- Headlines with optional permalinks
+h(2, "link-id") Headline 2 with link to #link-id
Code blocks are implemented using +code or +aside-code (to display them in the right sidebar). A . is added after the mixin call to preserve whitespace:
+code("This is a label").
import spacy
en_nlp = spacy.load('en')
en_doc = en_nlp(u'Hello, world. Here are two sentences.')
You can find the documentation for the available mixins in _includes/_mixins.jade.
Helpers for linking to content
Aside from the +a() mixin, there are three other helpers to make linking to content more convenient.
Linking to GitHub
Since GitHub links can be long and tricky, you can use the gh() function to generate them automatically for spaCy and all repositories owned by explosion:
// Syntax: gh(repo, [file], [branch])
gh("spaCy", "spacy/matcher.pyx")
// https://github.com/explosion/spaCy/blob/master/spacy/matcher.pyx
Linking to source
+src() generates a link with a little source icon to indicate it's linking to a code source. Ideally, it's used in combination with gh():
+src(gh("spaCy", "spacy/matcher.pyx")) matcher.pxy
Linking to API reference
+api() generates a link to a page in the API docs, with an added icon. It should only be used across the workflows in the usage section, and only on the first mention of the respective class.
It takes the slug of an API page as the argument. You can also use anchors to link to specific sections – they're usually the method or property names.
+api("tokenizer") #[code Tokenizer]
+api("doc#similarity") #[code Doc.similarity()]
Most common causes of compile errors
| Problem | Fix |
|---|---|
| JSON formatting errors | make sure last elements of objects don't end with commas and/or use a JSON linter |
unescaped characters like < or > and sometimes ' in inline elements |
replace with encoded version: <, > etc. |
| "Cannot read property 'call' of undefined" / "foo is not a function" | make sure mixin names are spelled correctly and mixins file is included with the correct path |
| "no closing bracket found" | make sure inline elements end with a ], like #[code spacy.load('en')] and for nested inline elements, make sure they're all on the same line and contain spaces between them (bad: #[+api("doc")#[code Doc]]) |
If Harp fails and throws a Jade error, don't take the reported line number at face value – it's often wrong, as the page is compiled from templates and several files.