{"id":30974062,"url":"https://github.com/stephenhky/npdict","last_synced_at":"2026-01-20T17:30:55.055Z","repository":{"id":301813043,"uuid":"1009959127","full_name":"stephenhky/npdict","owner":"stephenhky","description":"Python Package for Dictionary Wrappers for Numpy Arrays","archived":false,"fork":false,"pushed_at":"2025-08-28T21:31:05.000Z","size":49,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-12T04:38:59.908Z","etag":null,"topics":["dict","numpy"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/npdict/","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/stephenhky.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}},"created_at":"2025-06-28T03:46:51.000Z","updated_at":"2025-08-28T18:41:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"176a0428-dfbf-4c71-b031-e0d9d75ff74b","html_url":"https://github.com/stephenhky/npdict","commit_stats":null,"previous_names":["stephenhky/npdict"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/stephenhky/npdict","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephenhky%2Fnpdict","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephenhky%2Fnpdict/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephenhky%2Fnpdict/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephenhky%2Fnpdict/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stephenhky","download_url":"https://codeload.github.com/stephenhky/npdict/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephenhky%2Fnpdict/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278219770,"owners_count":25950350,"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","status":"online","status_checked_at":"2025-10-03T02:00:06.070Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["dict","numpy"],"created_at":"2025-09-12T04:09:56.117Z","updated_at":"2025-10-03T19:57:14.875Z","avatar_url":"https://github.com/stephenhky.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n[![GitHub release](https://img.shields.io/github/release/stephenhky/npdict.svg?maxAge=3600)](https://github.com/stephenhky/npdict/releases)\n[![pypi](https://img.shields.io/pypi/v/npdict.svg?maxAge=3600)](https://pypi.org/project/npdict/)\n[![download](https://img.shields.io/pypi/dm/npdict.svg?maxAge=2592000\u0026label=installs\u0026color=%2327B1FF)](https://pypi.org/project/npdict/)\n[![Documentation Status](https://readthedocs.org/projects/npdict/badge/?version=latest)](https://npdict.readthedocs.io/en/latest/?badge=latest)\n\n# `npdict`: Python Package for Dictionary Wrappers for Numpy Arrays\n\nThis Python package, `npdict`, aims at facilitating holding numerical\nvalues in a Python dictionary, but at the same time retaining the\nultra-high performance supported by NumPy. It supports an object\nwhich is a Python dictionary on the surface, but numpy behind the\nback, facilitating fast assignment and retrieval of values\nand fast computation of numpy arrays.\n\n## Installation\n\nTo install, in your terminal, simply enter:\n\n```\npip install npdict\n```\n\n## Quickstart\n\n### Instantiation\n\nSuppose you are doing a similarity dictionary between two sets of words.\nAnd each of these sets have words:\n\n```\ndocument1 = ['president', 'computer', 'tree']\ndocument2 = ['chairman', 'abacus', 'trees']\n```\n\nAnd you can build a dictionary like this:\n\n```\nimport numpy as np\nfrom npdict import NumpyNDArrayWrappedDict\n\nsimilarity_dict = NumpyNDArrayWrappedDict([document1, document2])\n```\n\nAn `npdict.NumpyNDArrayWrappedDict` instance is instantiated. It is \na Python dict:\n\n```\nisinstance(similarity_dict, dict)  # which gives `True`\n```\n\nIt has a matrix inside with default value 0.0 (and the initial default value can\nbe changed to other values when the instance is instantiated.)\n\n```\nsimilarity_dict.to_numpy()\n```\ngiving\n```\narray([[0., 0., 0.],\n       [0., 0., 0.],\n       [0., 0., 0.]])\n```\n\n### Value Assignments\n\nNow you can assign values just like what you do to a Python dictionary:\n\n```\nsimilarity_dict['president', 'chairman'] = 0.9\nsimilarity_dict['computer', 'abacus'] = 0.7\nsimilarity_dict['tree', 'trees'] = 0.95\n```\n\nAnd it has changed the inside numpy array to be:\n\n```\narray([[0.9  , 0.  , 0.  ],\n       [0.  , 0.7 , 0.  ],\n       [0.  , 0.  , 0.95]])\n```\n\n### Generation of New Object from the Old One\n\nIf you want to create another dict using the same words, but \na manipulation of the original value, 25 percent discount\nof the original one for example, you can do something like this:\n\n```\nnew_similarity_dict = similarity_dict.generate_dict(similarity_dict.to_numpy()*0.75)\n```\n\nAnd you got a new dictionary with numpy array to be:\n\n```\nnew_similarity_dict.to_numpy()\n```\ngiving\n```\narray([[0.675 , 0.    , 0.    ],\n       [0.    , 0.525 , 0.    ],\n       [0.    , 0.    , 0.7125]])\n```\n\nThis is a simple operation. But the design of this wrapped Python\ndictionary is that you can perform any fast or optimized operation\non your numpy array (using numba or Cython, for examples),\nwhile retaining the keywords as your dictionary.\n\n### Retrieval of Values\n\nAt the same time, you can set new values just like above, or retrieve\nvalues as if it is a Python dictionary:\n\n```\nsimilarity_dict['president', 'chairman']\n```\n\n### Conversion to a Python Dictionary\n\nYou can also convert this to an ordinary Python dictionary:\n\n```\nraw_similarity_dict = similarity_dict.to_dict()\n```\n\n### Instantiation from a Python Dictionary\n\nAnd you can convert a Python dictionary of this type back to \n`npdict.NumpyNDArrayWrappedDict` by (recommended)\n\n```\nnew_similarity_dict_2 = NumpyNDArrayWrappedDict.from_dict_given_keywords([document1, document2], raw_similarity_dict)\n```\n\nOr you can even do this (not recommended):\n\n```\nnew_similarity_dict_3 = NumpyNDArrayWrappedDict.from_dict(raw_similarity_dict)\n```\n\nIt is not recommended because the order of the keys are not retained in this way.\nUse it with caution.\n\n## Working with Sparse Arrays\n\nFor large, sparse matrices where most elements are zero, using `SparseArrayWrappedDict` can be more memory-efficient than the standard `NumpyNDArrayWrappedDict`.\n\n### Instantiation\n\nSimilar to the regular dictionary wrapper, you can instantiate a sparse array wrapper:\n\n```python\nfrom npdict import SparseArrayWrappedDict\n\ndocument1 = ['president', 'computer', 'tree', 'car', 'house', 'book']\ndocument2 = ['chairman', 'abacus', 'trees', 'vehicle', 'building', 'paper']\n\n# Create a sparse dictionary - efficient for large, sparse matrices\nsparse_similarity_dict = SparseArrayWrappedDict([document1, document2])\n```\n\n### Value Assignments\n\nAssign values just like with a regular dictionary:\n\n```python\n# Only assign values for the few non-zero elements\nsparse_similarity_dict['president', 'chairman'] = 0.9\nsparse_similarity_dict['computer', 'abacus'] = 0.7\nsparse_similarity_dict['tree', 'trees'] = 0.95\n```\n\nThe sparse implementation only stores the non-zero values, making it memory-efficient for large, sparse matrices.\n\n### Converting Between Formats\n\nYou can convert between dense and sparse formats:\n\n```python\n# Convert to NumPy array (dense format)\ndense_array = sparse_similarity_dict.to_numpy()\n\n# Convert to COO format (another sparse format)\ncoo_array = sparse_similarity_dict.to_coo()\n\n# Get the underlying DOK (Dictionary of Keys) sparse array\ndok_array = sparse_similarity_dict.to_dok()\n```\n\n### Generating New Dictionaries\n\nYou can generate new dictionaries from existing ones, with options to convert between sparse and dense formats:\n\n```python\n# Generate a new sparse dictionary\nnew_sparse_dict = sparse_similarity_dict.generate_dict(\n    sparse_similarity_dict.to_coo() * 0.75\n)\n\n# Generate a dense dictionary from a sparse one\ndense_dict = sparse_similarity_dict.generate_dict(\n    sparse_similarity_dict.to_numpy(),\n    dense=True  # This parameter converts to a dense NumpyNDArrayWrappedDict\n)\n```\n\n### When to Use Sparse Arrays\n\nUse `SparseArrayWrappedDict` when:\n- Your data is mostly zeros (sparse)\n- You're working with large dimensions where memory usage is a concern\n- You need to perform operations that are optimized for sparse matrices\n\nUse `NumpyNDArrayWrappedDict` when:\n- Your data has few zeros (dense)\n- You need faster element-wise access\n- You're working with smaller dimensions where memory usage is less of a concern","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephenhky%2Fnpdict","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephenhky%2Fnpdict","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephenhky%2Fnpdict/lists"}