{"id":15454729,"url":"https://github.com/argilla-io/adept-augmentations","last_synced_at":"2025-07-21T08:33:17.051Z","repository":{"id":64250062,"uuid":"570452643","full_name":"argilla-io/adept-augmentations","owner":"argilla-io","description":"A Python library aimed at dissecting and augmenting NER training data.","archived":false,"fork":false,"pushed_at":"2023-05-11T07:16:36.000Z","size":292,"stargazers_count":58,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-22T04:41:14.319Z","etag":null,"topics":["dataset","datasets","few-shot-learning","machine-learning","natural-language-processing","nlp","spacy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/argilla-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-11-25T08:21:34.000Z","updated_at":"2025-01-31T07:26:32.000Z","dependencies_parsed_at":"2023-08-27T09:12:23.477Z","dependency_job_id":null,"html_url":"https://github.com/argilla-io/adept-augmentations","commit_stats":null,"previous_names":["davidberenstein1957/adept-augmentations"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/argilla-io/adept-augmentations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/argilla-io%2Fadept-augmentations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/argilla-io%2Fadept-augmentations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/argilla-io%2Fadept-augmentations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/argilla-io%2Fadept-augmentations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/argilla-io","download_url":"https://codeload.github.com/argilla-io/adept-augmentations/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/argilla-io%2Fadept-augmentations/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266267291,"owners_count":23902334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dataset","datasets","few-shot-learning","machine-learning","natural-language-processing","nlp","spacy"],"created_at":"2024-10-01T22:05:09.563Z","updated_at":"2025-07-21T08:33:17.028Z","avatar_url":"https://github.com/argilla-io.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Adept Augmentations\n\nWelcome to Adept Augmentations, which can be used for creating additional data in Few Shot Named Entity Recognition (NER) settings!\n\nAdept Augmentation is a Python package that provides data augmentation functionalities for NER training data using the `spacy` and `datasets` packages. Currently, we support one augmentor `EntitySwapAugmenter`, however, we plan on [adding some more](#implemented-augmenters).\n\n`EntitySwapAugmenter` takes either a `datasets.Dataset` or a `spacy.tokens.DocBin`. Additionally, it is optional to provide a set of `labels`. It initially creates a knowledge base of entities belonging to a certain label. When running `augmenter.augment()` for `N` runs, it then creates `N` new sentences with random swaps of the original entities with an entity of the same corresponding label from the knowledge base.\n\nFor example, assuming that we have knowledge base for `PERSONS`, `LOCATIONS` and `PRODUCTS`. We can then create additional data for the sentence \"Momofuko Ando created instant noodles in Osaka.\" using `augmenter.augment(N=2)`, resulting in \"David created instant noodles in Madrid.\" or \"Tom created Adept Augmentations in the Netherlands\".\n\nAdept Augmentation works for NER labels using the IOB, IOB2, BIOES and BILUO tagging schemes, as well as labels not following any tagging scheme.\n\n## Usage\n\n### Datasets\n\n```python\nfrom adept_augmentations import EntitySwapAugmenter\nfrom datasets import load_dataset\n\ngolden_dataset = load_dataset(\"conll2003\", split=\"train[:3]\")\naugmenter = EntitySwapAugmenter(golden_dataset)\naugmented_dataset = augmenter.augment(N=4)\n\nfor entry in augmented_dataset[\"tokens\"]:\n    print(entry)\n\n# ['EU', 'rejects', 'British', 'call', 'to', 'boycott', 'British', 'lamb', '.']\n# ['EU', 'rejects', 'German', 'call', 'to', 'boycott', 'German', 'lamb', '.']\n# ['EU', 'rejects', 'German', 'call', 'to', 'boycott', 'British', 'lamb', '.']\n# ['Peter', 'Blackburn']\n# ['BRUSSELS', '1996-08-22']\n```\n\n### spaCy\n\n```python\nfrom adept_augmentations import EntitySwapAugmenter\nimport spacy\nfrom spacy.tokens import Doc, DocBin\n\nnlp = spacy.blank(\"en\")\n\n# Create some example golden data\nexample_data = [\n    (\"Apple is looking at buying U.K. startup for $1 billion\", [(0, 5, \"ORG\"), (27, 31, \"LOC\"), (44, 54, \"MONEY\")]),\n    (\"Microsoft acquires GitHub for $7.5 billion\", [(0, 9, \"ORG\"), (19, 25, \"ORG\"), (30, 42, \"MONEY\")]),\n]\n\n# Create a new DocBin\nnlp = spacy.blank(\"en\")\ndocs = []\nfor entry in example_data:\n    doc = Doc(nlp.vocab, words=entry[0].split())\n    doc.ents = [doc.char_span(ent[0], ent[1], label=ent[2]) for ent in entry[1]]\n    docs.append(doc)\ngolden_dataset = DocBin(docs=docs)\n\n# Augment Data\naugmented_dataset = EntitySwapAugmenter(golden_dataset).augment(4)\nfor doc in augmented_dataset.get_docs(nlp.vocab):\n    print(doc.text)\n    \n# GitHub is looking at buying U.K. startup for $ 7.5 billion\n# Microsoft is looking at buying U.K. startup for $ 1 billion\n# Microsoft is looking at buying U.K. startup for $ 7.5 billion\n# GitHub is looking at buying U.K. startup for $ 1 billion\n# Microsoft acquires Apple for $ 7.5 billion\n# Apple acquires Microsoft for $ 1 billion\n# Microsoft acquires Microsoft for $ 7.5 billion\n# GitHub acquires GitHub for $ 1 billion\n```\n\n## Potential performance gains\nData augmentation can significantly improve model performance in low-data scenarios.\nTo showcase this, we trained a [SpanMarker](https://github.com/tomaarsen/SpanMarkerNER) NER model on\nthe 50, 100, 200, 400 and 800 first [CoNLL03](https://huggingface.co/datasets/conll2003) training samples.\n\nThe augmented dataset is generated like so:\n```python\n# Select N (50, 100, 200, 400 or 800) samples from the gold training dataset\ngolden_dataset = dataset[\"train\"].select(range(N))\n\n# Generate augmented dataset, with 4 * N samples\naugmented_dataset = Augmenter(golden_dataset).augment(N=4)\n\n# Combine the original with the augmented to produce the full dataset\n# to produce a dataset 5 times as big as the original\naugmented_dataset = concatenate_datasets([augmented_dataset, golden_dataset])\n```\n\nNote that the baseline uses 5 epochs. This way, the training time and steps are identical between the two experiments. All scenarios are executed 5 times,\nand we report means and standard errors.\n\n|       | Original - 5 Epochs | Augmented - 1 Epoch |\n|-------|--|--|\n| N=50  | 0.387 ± 0.042 F1 | **0.484 ± 0.054 F1** |\n| N=100 | 0.585 ± 0.070 F1 | **0.663 ± 0.038 F1** |\n| N=200 | 0.717 ± 0.053 F1 | **0.757 ± 0.025 F1** |\n| N=400 | 0.816 ± 0.017 F1 | **0.826 ± 0.011 F1** |\n| N=800 | 0.859 ± 0.004 F1 | **0.862 ± 0.002 F1** |\n\n(Note: These results are not optimized and do not indicate maximum performances with SpanMarker.)\n\nFrom these results, it is clear that performing data augmentation using `adept_augmentations` can heavily improve performance in low-data settings.\n\n## Implemented Augmenters\n\n- [X] `EntitySwapAugmenter`\n- [ ] `KnowledgeBaseSwapAugmenter`\n- [ ] `CoreferenceSwapAugmenter`\n- [ ] `SentenceCropAugmenter`\n\n## Potential integrations\n\nPotentially, we can look into integrations of other augmentations packages that do not preserve gold standard knowledge. Good sources for inspiration are:\n\n- \u003chttps://github.com/KennethEnevoldsen/augmenty\u003e\n  - \u003chttps://kennethenevoldsen.github.io/augmenty/tutorials/introduction.html\u003e\n- \u003chttps://github.com/QData/TextAttack\u003e\n- \u003chttps://github.com/infinitylogesh/mutate\u003e\n\n## Logo Attribution\n\nAugmented Reality by KΛPKLΛM from \u003ca href=\"https://thenounproject.com/browse/icons/term/augmented-reality/\" target=\"_blank\" title=\"Augmented Reality Icons\"\u003eNoun Project\u003c/a\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fargilla-io%2Fadept-augmentations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fargilla-io%2Fadept-augmentations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fargilla-io%2Fadept-augmentations/lists"}