{"id":38335282,"url":"https://github.com/cedergrouphub/materialparser","last_synced_at":"2026-01-17T02:55:49.221Z","repository":{"id":95061399,"uuid":"125573476","full_name":"CederGroupHub/MaterialParser","owner":"CederGroupHub","description":"Utility to compile string of chemical terms into data structure with chemical formula and composition","archived":false,"fork":false,"pushed_at":"2021-09-17T12:58:28.000Z","size":1290,"stargazers_count":13,"open_issues_count":5,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-09-09T23:38:56.637Z","etag":null,"topics":["chemical-compounds","chemical-terms","composition","material-parser","materials-science","natural-language-processing","python","text-mining"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CederGroupHub.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-03-16T21:51:37.000Z","updated_at":"2024-01-14T09:29:57.000Z","dependencies_parsed_at":"2023-03-29T01:03:08.301Z","dependency_job_id":null,"html_url":"https://github.com/CederGroupHub/MaterialParser","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/CederGroupHub/MaterialParser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CederGroupHub%2FMaterialParser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CederGroupHub%2FMaterialParser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CederGroupHub%2FMaterialParser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CederGroupHub%2FMaterialParser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CederGroupHub","download_url":"https://codeload.github.com/CederGroupHub/MaterialParser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CederGroupHub%2FMaterialParser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28492591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T02:39:23.645Z","status":"ssl_error","status_checked_at":"2026-01-17T02:34:19.649Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["chemical-compounds","chemical-terms","composition","material-parser","materials-science","natural-language-processing","python","text-mining"],"created_at":"2026-01-17T02:55:49.136Z","updated_at":"2026-01-17T02:55:49.212Z","avatar_url":"https://github.com/CederGroupHub.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MaterialParser\n\nThis is an old repo for the text2chem parser. The new one is available at https://github.com/CederGroupHub/text2chem.\n\nMaterial Parser is a package that provides various functionality to parse material entities and convert them into a\nchemical structure.\n\nThe Material Parser addresses the problem of unification of materials entities widely used in scientific literature.\n\nThis tool is build to facilitate and promote text mining research in material science.\n\n**Material Parser** functionality includes:\n\n * converting standard chemical terms into a chemical formula\n * parsing chemical formula into chemical composition,\n * constructing dictionary of materials abbreviations from a text snippets,\n * finding the values of stoichiometric and elements variables from text snippets,\n * splitting mixtures/composites/alloys/solid solutions into compounds\n\nNote: Material Parser is not intended to be used for finding material entities in the text or to perform any\nchemical named entities recognition (NER) in a text.\nIt rather processes and standardizes already extracted chemical (material) entities and extracts relevant chemical\ninformation from them.\n\nThe parser was tested to work well for inorganic material terms, its performance on organic terms was not\nevaluated thoroughly.\n\n### Pipeline overview\n\nMaterial Parser runs as a pipeline of default, pre- and post-processing modules.\nDefault module of the pipeline process chemical formula and converts into a chemical structure.\nPreprocessing modules deal with an input material string,\nseparate relevant information from an input string and fill it into an output chemical structure.\nPostprocessing modules augment chemical structure with any other information that can be found in a surrounding text.\n\nThe current version of Material Parser package includes the following preprocessing modules:\n * ``PhaseProcessing`` - gets information about material phase if it is presented in the string,\ne.g. for \"P2-Na2/3(CoxNi1/3-xMn2/3)O2\", \"P2\" will be separated and stored in the structure\nwhile the rest of the string will be sent down the pipeline.\n * ``AdditivesProcessing`` - gets information about any additives, such as dopants, stabilizers or mixed compounds,\ne.g. i) for \"(Na0.5K0.5)NbO3 + 1.5 mol% CuF2\", \"CuF2\" will be separated as an additive\nand \"(Na0.5K0.5)NbO3\" will be sent down the pipeline; ii) for \"Ca2BO3Cl:Sm3+, Eu3+\", \"Sm3+\" and \"Eu3+\" will be separated\nand \"Ca2BO3Cl\" will be sent down the pipeline.\n * ``ChemicalNameProcessing`` - attempts to convert sequence of chemical terms into a formula,\ne.g. \"zinc (II) acetate dihydrate\" will be converted into \"Zn(CH3COO)2·2H2O\" that will be sent down the pipeline\nand the chemical terms will be stored in output structure as material name.\nThis tool can also separate chemical formula from the rest of the terms is they are combined by tokenizer,\ne.g.  \"ammonium molybdate (NH4)6Mo7O24⋅4H2O\" will be split into \"ammonium molybdate\" - material name\nand \"(NH4)6Mo7O24⋅4H2O\" - chemical formula that will be sent down the pipeline.\n * ``MixtureProcessing`` - split mixture/solid solution/alloy/composite/hydrate into constituting compounds,\ne.g. \"(1-x-y)BaTiO3-xBaBiO3-y(Bi0.5Na0.5)TiO3\" will be split into \"BaTiO3\", \"BaBiO3\", and \"(Bi0.5Na0.5)TiO3\"\nwith the corresponding amounts \"(1-x-y)\", \"x\" and \"y\", respectively.\n * ``PubchemPreprocessing`` - looks up chemical terms in PubChem database, if chemical formula is not found.\nThis step usually slows down the overall pipeline perfomance.\n\nThe postprocessing module includes:\n * ``Substitute_Additives`` - appends dopand elements to the formula to have integer total stoichiometry\nor add mixture compound to the composition,\ne.g. i) \"Zn1.92-2xYxLixSiO4:0.08Mn2+\" becomes \"Mn0.08Zn1.92-2xYxLixSiO4\" and\nii) \"(Na0.5K0.5)NbO3 + 1.5 mol% CuF2\" becomes \"(1-x)(Na0.5K0.5)NbO3-(x)CuF2\".\n\n\n### Installation:\n```\ngit clone https://github.com/CederGroupHub/MaterialParser.git\ncd MaterialParser\npip install -r requirements.txt -e .\n```\n\n### Running default setup:\n\nBy default, Material Parser gets chemical composition from a proper material formula\n(i.e. no chemical terms, dopants or mixtures):\n\n```\nfrom material_parser.core.material_parser import MaterialParserBuilder\nmp = mp = MaterialParserBuilder().build()\noutput = mp.parse(\"Li5+xLa3Ta2-xGexO12\")\nprint(output.to_dict())\n\n```\nOutput:\n```\n{'additives': [],\n 'amounts_x': {'x': []},\n 'composition': [{'amount': '1',\n                  'elements': OrderedDict([('Li', 'x+5'),\n                                           ('La', '3'),\n                                           ('Ta', '2-x'),\n                                           ('Ge', 'x'),\n                                           ('O', '12')]),\n                  'formula': 'Li5+xLa3Ta2-xGexO12',\n                  'species': OrderedDict([('Li', 'x+5'),\n                                          ('La', '3'),\n                                          ('Ta', '2-x'),\n                                          ('Ge', 'x'),\n                                          ('O', '12')])}],\n 'elements_x': {},\n 'material_formula': 'Li5+xLa3Ta2-xGexO12',\n 'material_name': '',\n 'material_string': 'Li5+xLa3Ta2-xGexO12',\n 'oxygen_deficiency': '',\n 'phase': ''}\n```\nOther attributes can be filled using additional pipeline blockes if required.\n\n### Adding modules to the pipeline:\n```\nfrom material_parser.core.material_parser import MaterialParserBuilder\nfrom material_parser.core.preprocessing_tools.additives_processing import AdditivesProcessing\nfrom material_parser.core.preprocessing_tools.chemical_name_processing import ChemicalNameProcessing\nfrom material_parser.core.preprocessing_tools.mixture_processing import MixtureProcessing\nfrom material_parser.core.preprocessing_tools.phase_processing import PhaseProcessing\nfrom material_parser.core.postprocessing_tools.substitute_additives import SubstituteAdditives\n\nmp = MaterialParserBuilder() \\\n    .addPreprocessing(AdditivesProcessing()) \\\n    .addPreprocessing(ChemicalNameProcessing()) \\\n    .addPreprocessing(PhaseProcessing()) \\\n    .addPreprocessing(MixtureProcessing())\\\n    .addPostprocessing(SubstituteAdditives())\\\n    .build()\n\nmp.parse(\"Nasicon (Na1+x+yZr2-yYySixP3-xO12)\")\n\n```\nOutput:\n```\n{'additives': [],\n 'amounts_x': {'x': [], 'y': []},\n 'composition': [{'amount': '1',\n                  'elements': OrderedDict([('Na', 'x+y+1'),\n                                           ('Zr', '2-y'),\n                                           ('Y', 'y'),\n                                           ('Si', 'x'),\n                                           ('P', '3-x'),\n                                           ('O', '12')]),\n                  'formula': 'Na1+x+yZr2-yYySixP3-xO12',\n                  'species': OrderedDict([('Na', 'x+y+1'),\n                                          ('Zr', '2-y'),\n                                          ('Y', 'y'),\n                                          ('Si', 'x'),\n                                          ('P', '3-x'),\n                                          ('O', '12')])}],\n 'elements_x': {},\n 'material_formula': 'Na1+x+yZr2-yYySixP3-xO12',\n 'material_name': 'Nasicon',\n 'material_string': 'Nasicon (Na1+x+yZr2-yYySixP3-xO12)',\n 'oxygen_deficiency': '',\n 'phase': ''}\n\n```\nNote: the order of the modules may affect the resulted output.\n\n\n### Running customized pipeline:\n\nMaterial Parser provides capabilities for creating customized pre- and post-processing modules.\nThis are defined by the corresponding interface:\n``core/preprocessing_tools/preprocessing_abc.py`` and ``core/postprocessing_tools/postprocessing_abc.py``.\nAdd the class implementing the interface into a corresponding directory and import as a regular module.\n\n### Output\n\nmp.parse() output the ChemicalStructure with the following attributes:\n\n * material_string: ``string``\n * material_name: ``string``\n * material_formula: ``string``\n * additives: ``list`` or ``string``\n * phase: ``string``\n * oxygen_deficiency: ``char``\n * amounts_x: ``Variables``\n * elements_x: ``Variables``\n * composition: ``list`` of ``Compound``\n\n\n### Citing\n\nIf you use Material Parser in your work, please cite the following paper:\n\n * Kononova et. al \"Text-mined dataset of inorganic materials synthesis recipes\", Scientific Data 6 (1), 1-11 (2019)\n [10.1038/s41597-019-0224-1](https://www.nature.com/articles/s41597-019-0224-1)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedergrouphub%2Fmaterialparser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcedergrouphub%2Fmaterialparser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedergrouphub%2Fmaterialparser/lists"}