├── .github └── workflows │ ├── pypi.yml │ └── python-package.yml ├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── docs ├── Makefile ├── make.bat └── source │ ├── api_calls.rst │ ├── area_data.rst │ ├── conf.py │ ├── index.rst │ ├── metadata.rst │ ├── modules.rst │ ├── requirements.txt │ └── retrieve_data.rst ├── pyproject.toml ├── readthedocs.yml ├── requirements.txt ├── src └── fingertips_py │ ├── __init__.py │ ├── api_calls.py │ ├── area_data.py │ ├── metadata.py │ └── retrieve_data.py └── tests ├── __init__.py └── test_all.py /.github/workflows/pypi.yml: -------------------------------------------------------------------------------- 1 | name: Publish to PyPi 2 | 3 | on: 4 | push: 5 | branches: [ "main" ] 6 | 7 | jobs: 8 | build: 9 | name: Build distribution 📦 10 | runs-on: ubuntu-latest 11 | 12 | steps: 13 | - uses: actions/checkout@v4 14 | - name: Set up Python 15 | uses: actions/setup-python@v5 16 | with: 17 | python-version: "3.x" 18 | - name: Install pypa/build 19 | run: >- 20 | python3 -m 21 | pip install 22 | build 23 | --user 24 | - name: Build a binary wheel and a source tarball 25 | run: python3 -m build 26 | - name: Store the distribution packages 27 | uses: actions/upload-artifact@v3 28 | with: 29 | name: python-package-distributions 30 | path: dist/ 31 | 32 | publish-to-pypi: 33 | name: >- 34 | Publish Python 🐍 distribution 📦 to PyPI 35 | needs: 36 | - build 37 | runs-on: ubuntu-latest 38 | environment: 39 | name: pypi 40 | url: https://pypi.org/p/fingertips-py # Replace with your PyPI project name 41 | permissions: 42 | id-token: write # IMPORTANT: mandatory for trusted publishing 43 | 44 | steps: 45 | - name: Download all the dists 46 | uses: actions/download-artifact@v3 47 | with: 48 | name: python-package-distributions 49 | path: dist/ 50 | - name: Publish distribution 📦 to PyPI 51 | uses: pypa/gh-action-pypi-publish@release/v1 52 | -------------------------------------------------------------------------------- /.github/workflows/python-package.yml: -------------------------------------------------------------------------------- 1 | # This workflow will install Python dependencies, run tests and lint with a variety of Python versions 2 | # For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python 3 | 4 | name: Run PyTest 5 | 6 | on: 7 | push: 8 | branches: [ "main", "development"] 9 | pull_request: 10 | branches: [ "main" ] 11 | 12 | jobs: 13 | build: 14 | 15 | runs-on: ubuntu-latest 16 | strategy: 17 | fail-fast: false 18 | matrix: 19 | python-version: ["3.9"] 20 | 21 | steps: 22 | - uses: actions/checkout@v3 23 | - name: Set up Python ${{ matrix.python-version }} 24 | uses: actions/setup-python@v3 25 | with: 26 | python-version: ${{ matrix.python-version }} 27 | - name: Install dependencies 28 | run: | 29 | python -m pip install --upgrade pip 30 | python -m pip install flake8 pytest 31 | python -m pip install . 32 | - name: Lint with flake8 33 | run: | 34 | # stop the build if there are Python syntax errors or undefined names 35 | flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics 36 | # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide 37 | flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics 38 | - name: Test with pytest 39 | run: | 40 | pytest 41 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | __pycache__/ 2 | .pytest_cache/ 3 | *.iml 4 | out 5 | gen 6 | venv/ 7 | *.egg-info 8 | dist/ 9 | docs/build/ 10 | 11 | # IDE files 12 | .idea 13 | .spyproject 14 | .vscode -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Fingertips_py V 0.4.2 2 | * No change for user. Fixed issue with displaying README on pypi. 3 | 4 | # Fingertips_py V 0.4.1 5 | * Function get_data_in_tuple has been removed. 6 | * Fixed bug in get_metadata when indicator_ids and profile_ids provided. 7 | * Fixed bug which prevented get_data_by_indicator_ids, get_all_data_for_profile 8 | and get_all_data_for_indicators running. 9 | 10 | # Fingertips_py V 0.4.0 11 | * Added pyproject.toml -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # fingertips_py 2 | 3 | This is a python package to interact with OHID's 4 | [Fingertips](https://fingertips.phe.org.uk/) data tool. Fingertips is a 5 | major repository of population and public health indicators for England. 6 | The site presents the information in many ways to improve accessibility 7 | for a wide range of audiences ranging from public health professionals 8 | and researchers to the general public. The information presented is a 9 | mixture of data available from other public sources, and those that are 10 | available through user access agreements with other organisations. The 11 | source of each indicator presented is available using the 12 | `get_metadata_for_indicator()` function. 13 | 14 | 15 | This package can be used to load data from the Fingertips API into 16 | python for further use. 17 | 18 | ## Installation 19 | 20 | This packaged should be installed using pip: 21 | 22 | ``` 23 | pip install fingertips_py 24 | ``` 25 | 26 | Or it can be compiled from source (still requires pip): 27 | 28 | ``` 29 | pip install git+https://github.com/PublicHealthEngland/PHDS_fingertips_py.git 30 | ``` 31 | 32 | ## Usage 33 | 34 | fingertips_py should be imported and used in line with standard python 35 | conventions. It is suggested that if the whole package is to be imported 36 | then the following convention is used: 37 | 38 | ``` 39 | import fingertips_py as ftp 40 | ``` 41 | 42 | The package returns data in a variety of types dependent on the 43 | function. 44 | 45 | For more information on any function, you can use: 46 | 47 | ``` 48 | help(*fingertips_py function name*) 49 | ``` 50 | 51 | Or you can view the documents [here](https://fingertips-py.readthedocs.io/en/latest/). 52 | 53 | ## Example 54 | 55 | This is an example of a workflow for retrieving data for the indicator 56 | on *Healthy Life Expectancy at Birth* from the *Public Health Outcomes 57 | Framework* profile. 58 | 59 | ``` 60 | import fingertips_py as ftp 61 | 62 | 63 | phof = ftp.get_profile_by_name('public health outcomes framework') 64 | phof_meta = ftp.get_metadata_for_profile_as_dataframe(phof['Id']) 65 | indicator_meta = phof_meta[phof_meta['Indicator'].str.contains('Healthy')] 66 | print(indicator_meta) 67 | 68 | Indicator ID Indicator ... 69 | 0 90362 0.1i - Healthy life expectancy at birth ... 70 | 55 92543 2.05ii - Proportion of children aged 2-2½yrs r... ... 71 | ``` 72 | 73 | We can see that the *Healthy life expectancy at birth* indicator has an 74 | id of 90362. The data for this indicator at all geographical breakdowns 75 | can be retrieved using `get_data_for_indicator_at_all_available_geographies()` 76 | 77 | ``` 78 | healthy_life_data = ftp.get_data_for_indicator_at_all_available_geographies(90362) 79 | ``` 80 | 81 | ## Licence 82 | 83 | This project is released under the [GPL-3](https://opensource.org/licenses/GPL-3.0) 84 | licence. 85 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = source 9 | BUILDDIR = build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /docs/make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=source 11 | set BUILDDIR=build 12 | 13 | %SPHINXBUILD% >NUL 2>NUL 14 | if errorlevel 9009 ( 15 | echo. 16 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 17 | echo.installed, then set the SPHINXBUILD environment variable to point 18 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 19 | echo.may add the Sphinx directory to PATH. 20 | echo. 21 | echo.If you don't have Sphinx installed, grab it from 22 | echo.https://www.sphinx-doc.org/ 23 | exit /b 1 24 | ) 25 | 26 | if "%1" == "" goto help 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 33 | 34 | :end 35 | popd 36 | -------------------------------------------------------------------------------- /docs/source/api_calls.rst: -------------------------------------------------------------------------------- 1 | api_calls 2 | ********* 3 | 4 | .. automodule:: fingertips_py.api_calls 5 | :members: -------------------------------------------------------------------------------- /docs/source/area_data.rst: -------------------------------------------------------------------------------- 1 | area_data 2 | ********* 3 | 4 | .. automodule:: fingertips_py.area_data 5 | :members: -------------------------------------------------------------------------------- /docs/source/conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # For the full list of built-in configuration values, see the documentation: 4 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 5 | 6 | 7 | import fingertips_py as ftp 8 | version = ftp.__version__ 9 | 10 | 11 | # -- Project information ----------------------------------------------------- 12 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information 13 | 14 | project = 'fingertips_py' 15 | copyright = '2024, Crown Copyright' 16 | author = 'Russell Plunkett, Olivia Box Power' 17 | release = version 18 | 19 | # -- General configuration --------------------------------------------------- 20 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration 21 | 22 | extensions = [ 23 | 'sphinx.ext.duration', 24 | 'sphinx.ext.autodoc', 25 | 'sphinx_rtd_theme' 26 | ] 27 | 28 | templates_path = ['_templates'] 29 | exclude_patterns = [] 30 | 31 | 32 | 33 | # -- Options for HTML output ------------------------------------------------- 34 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output 35 | 36 | html_theme = 'sphinx_rtd_theme' 37 | html_static_path = ['_static'] 38 | -------------------------------------------------------------------------------- /docs/source/index.rst: -------------------------------------------------------------------------------- 1 | .. fingertips_py documentation master file, created by 2 | sphinx-quickstart on Mon Oct 21 13:56:10 2024. 3 | You can adapt this file completely to your liking, but it should at least 4 | contain the root `toctree` directive. 5 | 6 | fingertips_py documentation 7 | *************************** 8 | 9 | Introduction 10 | ============ 11 | 12 | This is a python package to interact with the Office for Health Improvement & Disparities' 13 | `Fingertips `_ data tool. Fingertips is a 14 | major repository of population and public health indicators for England. 15 | The site presents the information in many ways to improve accessibility 16 | for a wide range of audiences ranging from public health professionals 17 | and researchers to the general public. The information presented is a 18 | mixture of data available from other public sources, and those that are 19 | available through user access agreements with other organisations. The 20 | source of each indicator presented is available using the 21 | `get_metadata_for_indicator()` function. 22 | 23 | 24 | This package can be used to load data from the Fingertips API into 25 | python for further use. 26 | 27 | Installation 28 | ============ 29 | 30 | This packaged should be installed using pip: 31 | 32 | .. code-block:: 33 | 34 | pip install fingertips_py 35 | 36 | 37 | Or it can be compiled from source (still requires pip): 38 | 39 | .. code-block:: 40 | 41 | pip install git+https://github.com/ukhsa-collaboration/PHDS_fingertips_py.git 42 | 43 | 44 | Usage 45 | ===== 46 | 47 | fingertips_py should be imported and used in line with standard python conventions. 48 | It is suggested that if the whole package is to be imported then the following convention is used: 49 | 50 | .. code-block:: 51 | 52 | import fingertips_py as ftp 53 | 54 | 55 | The package returns data in a variety of types dependent on the 56 | function. 57 | 58 | For more information on any function, you can use: 59 | 60 | .. code-block:: 61 | 62 | help(*fingertips_py function name*) 63 | 64 | 65 | Example 66 | ======= 67 | 68 | This is an example of a workflow for retrieving data for the indicator 69 | on *Healthy Life Expectancy at Birth* from the *Public Health Outcomes 70 | Framework* profile. 71 | 72 | .. code-block:: 73 | 74 | import fingertips_py as ftp 75 | 76 | phof = ftp.get_profile_by_name('public health outcomes framework') 77 | phof_meta = ftp.get_metadata_for_profile_as_dataframe(phof['Id']) 78 | indicator_meta = phof_meta[phof_meta['Indicator'].str.contains('Healthy')] 79 | print(indicator_meta) 80 | 81 | Indicator ID Indicator ... 82 | 0 90362 0.1i - Healthy life expectancy at birth ... 83 | 55 92543 2.05ii - Proportion of children aged 2-2½yrs r... ... 84 | 85 | 86 | 87 | We can see that the *Healthy life expectancy at birth* indicator has an 88 | id of 90362. The data for this indicator at all geographical breakdowns 89 | can be retrieved using `get_data_for_indicator_at_all_available_geographies()` 90 | 91 | .. code-block:: 92 | 93 | healthy_life_data = ftp.get_data_for_indicator_at_all_available_geographies(90362) 94 | 95 | 96 | 97 | Licence 98 | ======= 99 | 100 | This project is released under the `GPL-3 `_ 101 | licence. 102 | 103 | 104 | .. toctree:: 105 | :maxdepth: 2 106 | :hidden: 107 | 108 | modules 109 | 110 | -------------------------------------------------------------------------------- /docs/source/metadata.rst: -------------------------------------------------------------------------------- 1 | metadata 2 | ********* 3 | 4 | .. automodule:: fingertips_py.metadata 5 | :members: -------------------------------------------------------------------------------- /docs/source/modules.rst: -------------------------------------------------------------------------------- 1 | Modules 2 | ******* 3 | .. toctree:: 4 | :maxdepth: 2 5 | 6 | api_calls 7 | area_data 8 | metadata 9 | retrieve_data -------------------------------------------------------------------------------- /docs/source/requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx_rtd_theme 2 | sphinx 3 | . -------------------------------------------------------------------------------- /docs/source/retrieve_data.rst: -------------------------------------------------------------------------------- 1 | retrieve_data 2 | ************* 3 | 4 | .. automodule:: fingertips_py.retrieve_data 5 | :members: -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["setuptools"] 3 | build-backend = "setuptools.build_meta" 4 | 5 | [project] 6 | name = "fingertips_py" 7 | 8 | dynamic = ["version"] 9 | 10 | license = {file = "LICENSE"} 11 | 12 | authors = [ 13 | {name = "Russell Plunkett"}, 14 | {name = "Annabel Westermann"}, 15 | {name = "Hadley Nanayakkara"}, 16 | {name = "Olivia Box Power"} 17 | ] 18 | 19 | maintainers = [ 20 | {name = "DHSC", email = "DataScience@dhsc.gov.uk"} 21 | ] 22 | 23 | description = "This is a python package to interact with OHID Fingertips data tool. This can be used to load data from the Fingertips API into Python for further manipulation." 24 | 25 | dependencies = [ 26 | "pandas>=1.5", 27 | "requests" 28 | ] 29 | 30 | readme = "README.md" 31 | 32 | requires-python = ">=3.8" 33 | 34 | classifiers = [ 35 | "Development Status :: 4 - Beta", 36 | "Programming Language :: Python :: 3", 37 | "Operating System :: OS Independent" 38 | ] 39 | 40 | keywords = [ 41 | "DHSC", 42 | "Department of Health and Social Care", 43 | "OHID", 44 | "Office for Health Improvement and Disparities", 45 | "Public Health", 46 | "indicators", 47 | "Fingertips" 48 | ] 49 | 50 | [project.urls] 51 | Homepage = "https://github.com/ukhsa-collaboration/PHDS_fingertips_py?tab=readme-ov-file" 52 | Documentation = "https://fingertips-py.readthedocs.io/en/latest/" 53 | Repository = "https://github.com/ukhsa-collaboration/PHDS_fingertips_py" 54 | Issues = "https://github.com/ukhsa-collaboration/PHDS_fingertips_py/issues" 55 | Changelog = "https://github.com/ukhsa-collaboration/PHDS_fingertips_py/blob/master/CHANGELOG.md" 56 | 57 | [tool.setuptools.dynamic] 58 | version = {attr = "fingertips_py.__version__"} -------------------------------------------------------------------------------- /readthedocs.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | 3 | build: 4 | os: ubuntu-24.04 5 | tools: 6 | python: "3" 7 | 8 | sphinx: 9 | configuration: docs/source/conf.py 10 | 11 | python: 12 | install: 13 | - requirements: docs/source/requirements.txt -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | pandas 2 | requests 3 | pytest 4 | sphinx 5 | sphinx_rtd_theme -------------------------------------------------------------------------------- /src/fingertips_py/__init__.py: -------------------------------------------------------------------------------- 1 | 2 | __version__ = '0.4.2' 3 | 4 | from fingertips_py.api_calls import get_json, make_request 5 | from fingertips_py.retrieve_data import get_all_data_for_profile, get_all_data_for_indicators, get_data_by_indicator_ids, \ 6 | get_all_areas_for_all_indicators, get_data_for_indicator_at_all_available_geographies 7 | from fingertips_py.metadata import get_metadata_for_profile_as_dataframe, get_metadata, get_metadata_for_indicator_as_dataframe, \ 8 | get_metadata_for_domain_as_dataframe, get_all_value_notes, get_profile_by_name, get_area_types_for_profile,\ 9 | get_domains_in_profile, get_all_profiles, get_area_types_as_dict, get_age_from_id, get_area_type_ids_for_profile, \ 10 | get_profile_by_id, get_age_id, get_all_ages, get_all_sexes, get_areas_for_area_type, get_metadata_for_indicator, \ 11 | get_multiplier_and_calculation_for_indicator, get_sex_from_id, get_sex_id, get_value_note_id, \ 12 | get_metadata_for_all_indicators, get_metadata_for_all_indicators_from_csv, get_all_areas 13 | from fingertips_py.area_data import deprivation_decile 14 | -------------------------------------------------------------------------------- /src/fingertips_py/api_calls.py: -------------------------------------------------------------------------------- 1 | """ 2 | A group of functions to query the Fingertips api and retrieve data in a variety of formats. 3 | """ 4 | 5 | 6 | import requests 7 | import json 8 | import pandas as pd 9 | from io import StringIO 10 | 11 | 12 | def make_request(url, attr=None): 13 | """ 14 | :param url: A url to make a request 15 | :param attr: The attribute that needs to be returned 16 | :return: a dict of the attribute and associated data 17 | 18 | """ 19 | try: 20 | req = requests.get(url) 21 | except requests.exceptions.SSLError: 22 | req = requests.get(url, verify=False) 23 | json_response = json.loads(req.content.decode('utf-8')) 24 | data = {} 25 | for item in json_response: 26 | name = item.pop(attr) 27 | data[name] = item 28 | return data 29 | 30 | 31 | def get_json(url): 32 | """ 33 | :param url: A url to make a request 34 | :return: A parsed JSON object 35 | """ 36 | try: 37 | req = requests.get(url) 38 | except requests.exceptions.SSLError: 39 | req = requests.get(url, verify=False) 40 | json_resp = json.loads(req.content.decode('utf-8')) 41 | return json_resp 42 | 43 | 44 | def get_json_return_df(url, transpose=True): 45 | """ 46 | :param url: A url to make a request 47 | :param transpose: [OPTIONAL] transposes dataframe. Default True. 48 | :return: Dataframe generated from JSON response. 49 | 50 | :meta private: 51 | """ 52 | try: 53 | req = requests.get(url) 54 | except requests.exceptions.SSLError: 55 | req = requests.get(url, verify=False) 56 | try: 57 | df = pd.read_json(req.content, encoding='utf-8') 58 | except TypeError: 59 | df = pd.DataFrame.from_dict([req.json()]) 60 | if transpose: 61 | df = df.transpose() 62 | return df 63 | 64 | 65 | def get_data_in_dict(url, key = None, value = None): 66 | """ 67 | :param url: A url to make a request 68 | :param key: The item in the JSON to be used as the dictionary key 69 | :param value: The item in the JSON to be used as the dictionary value 70 | :return: A dictionary of returned data using first item as dictionary key by default 71 | 72 | :meta private: 73 | """ 74 | json_list = get_json(url) 75 | if key is None: 76 | key = list(json_list[0].keys())[0] 77 | json_dict = {} 78 | if value is None: 79 | for js in json_list: 80 | json_dict[js.get(key)] = js 81 | else: 82 | for js in json_list: 83 | json_dict[js.get(key)] = js.get(value) 84 | return json_dict 85 | 86 | 87 | def deal_with_url_error(url): 88 | """ 89 | :param url: A url that returns a URL Error based on SSL errors 90 | :return: A dataframe from the URL with varify set to false. 91 | 92 | :meta private: 93 | """ 94 | req = requests.get(url, verify=False) 95 | s = str(req.content, 'utf-8') 96 | data = StringIO(s) 97 | df = pd.read_csv(data) 98 | return df 99 | 100 | 101 | base_url = 'https://fingertips.phe.org.uk/api/' 102 | 103 | 104 | -------------------------------------------------------------------------------- /src/fingertips_py/area_data.py: -------------------------------------------------------------------------------- 1 | """ 2 | Functions to retrieve data that are specific to areas and relevant to all indicators. For example: Deprivation decile. 3 | """ 4 | 5 | 6 | import pandas as pd 7 | import warnings 8 | from fingertips_py.retrieve_data import get_data_by_indicator_ids 9 | 10 | def defined_qcut(df, value_series, number_of_bins, bins_for_extras, labels=False): 11 | """ 12 | Allows users to define how values are split into bins when clustering. 13 | 14 | :param df: Dataframe of values 15 | :param value_series: Name of value column to rank upon 16 | :param number_of_bins: Integer of number of bins to create 17 | :param bins_for_extras: Ordered list of bin numbers to assign uneven splits 18 | :param labels: Optional. Labels for bins if required 19 | :return: A dataframe with a new column 'bins' which contains the cluster numbers 20 | """ 21 | if max(bins_for_extras) > number_of_bins or any(x < 0 for x in bins_for_extras): 22 | raise ValueError('Attempted to allocate to a bin that doesnt exist') 23 | base_number, number_of_values_to_allocate = divmod(df[value_series].count(), number_of_bins) 24 | bins_for_extras = bins_for_extras[:number_of_values_to_allocate] 25 | if number_of_values_to_allocate == 0: 26 | df['bins'] = pd.qcut(df[value_series], number_of_bins, labels=labels) 27 | return df 28 | elif number_of_values_to_allocate > len(bins_for_extras): 29 | raise ValueError('There are more values to allocate than the list provided, please select more bins') 30 | bins = {} 31 | for i in range(number_of_bins): 32 | number_of_values_in_bin = base_number 33 | if i in bins_for_extras: 34 | number_of_values_in_bin += 1 35 | bins[i] = number_of_values_in_bin 36 | df['rank'] = df[value_series].rank() 37 | df = df.sort_values(by=['rank']) 38 | df['bins'] = 0 39 | row_to_start_allocate = 0 40 | row_to_end_allocate = 0 41 | for bin_number, number_in_bin in bins.items(): 42 | row_to_end_allocate += number_in_bin 43 | bins.update({bin_number: [number_in_bin, row_to_start_allocate, row_to_end_allocate]}) 44 | row_to_start_allocate = row_to_end_allocate 45 | conditions = [df['rank'].iloc[v[1]: v[2]] for k, v in bins.items()] 46 | series_to_add = pd.Series() 47 | for idx, series in enumerate(conditions): 48 | series[series > -1] = idx 49 | series_to_add = series_to_add.append(series) 50 | df['bins'] = series_to_add 51 | df['bins'] = df['bins'] + 1 52 | df = df.reset_index() 53 | return df 54 | 55 | 56 | extra_areas = { 57 | 1: [0], 58 | 2: [0, 5], 59 | 3: [0, 3, 7], 60 | 4: [0, 2, 6, 8], 61 | 5: [0, 2, 4, 6, 8], 62 | 6: [0, 1, 3, 5, 6, 8], 63 | 7: [0, 1, 2, 4, 5, 7, 8], 64 | 8: [0, 1, 2, 3, 5, 6, 7, 8], 65 | 9: [0, 1, 2, 3, 4, 5, 6, 7, 8] 66 | } 67 | 68 | 69 | def deprivation_decile(area_type_id, year='2015', area_code=None): 70 | """ 71 | Takes in an area type id and returns a pandas series of deprivation deciles for those areas (with the areas as an 72 | index. If a specific area is requested, it returns just the deprivation decile value. 73 | 74 | :param area_type_id: Area type id as denoted by the Fingertips API 75 | :param year: Year of deprivation score 76 | :param area_code: Optional. Area code for area type to return a single value for that area 77 | :return: A pandas series of deprivation scores with area codes as the index. Or single value if area is specified. 78 | """ 79 | warnings.warn('Caution, the deprivation deciles are being calculated on the fly and might show some inconsistencies' 80 | ' from the live Fingertips site.') 81 | acceptable_deprivation_years_la = ['2010', '2015'] 82 | acceptable_deprivation_years_gp = ['2015'] 83 | acceptable_area_types = [3, 101, 102, 7, 153] 84 | order_of_extra_values = [] 85 | if not isinstance(year, str): 86 | year = str(year) 87 | if year not in acceptable_deprivation_years_la and area_type_id != 7: 88 | raise ValueError \ 89 | ('The acceptable years are 2010 and 2015 for local authorities and CCGs, please select one of these') 90 | elif year not in acceptable_deprivation_years_gp: 91 | raise ValueError('The acceptable years are 2015, please select this') 92 | if area_type_id not in acceptable_area_types: 93 | raise ValueError('Currently, we support deprivation decile for District & UA, County & UA, MSOA and GP area ' 94 | 'types') 95 | if area_type_id == 3: 96 | indicator_id = 93275 97 | area_dep_dec = get_data_by_indicator_ids(indicator_id, area_type_id, parent_area_type_id=101, profile_id=143, 98 | include_sortable_time_periods=True) 99 | else: 100 | indicator_id = 91872 101 | area_dep_dec = get_data_by_indicator_ids(indicator_id, area_type_id) 102 | if area_type_id == 102: 103 | order_of_extra_values = [0, 9, 1, 2, 3, 4, 5, 6, 7, 8] 104 | 105 | area_dep_dec = area_dep_dec[area_dep_dec['Area Code'] != 'E92000001'] 106 | if not order_of_extra_values: 107 | order_of_extra_values = extra_areas[area_dep_dec['Value'].count() % 10] 108 | area_dep_dec = defined_qcut(area_dep_dec, 'Value', 10, order_of_extra_values) 109 | area_dep_dec.set_index('Area Code', inplace=True) 110 | if area_code: 111 | try: 112 | return area_dep_dec.loc[area_code, 'decile'] 113 | except KeyError: 114 | raise KeyError('This area is not available at in this area type. Please try another area type') 115 | return area_dep_dec['bins'] 116 | 117 | 118 | 119 | -------------------------------------------------------------------------------- /src/fingertips_py/metadata.py: -------------------------------------------------------------------------------- 1 | """ 2 | Calls used to retrieve metadata about areas, ages, sexes, value notes, calculation methods, rates, and indicator 3 | metadata. 4 | """ 5 | 6 | import pandas as pd 7 | from urllib.error import HTTPError, URLError 8 | from fingertips_py.api_calls import base_url, make_request, get_json, get_json_return_df, deal_with_url_error, get_data_in_dict 9 | 10 | 11 | def get_all_ages(is_test=False): 12 | """ 13 | Returns a dictionary of all the age categories and their IDs as the dictionary key. 14 | 15 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 16 | :return: Age codes used in Fingertips in a dictionary 17 | """ 18 | ages = get_data_in_dict(base_url + 'ages') 19 | if is_test: 20 | return ages, base_url + 'ages' 21 | return ages 22 | 23 | 24 | def get_all_areas(is_test=False): 25 | """ 26 | Retreives all area types. 27 | 28 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 29 | :return: A dictionary of all area types used in Fingertips 30 | """ 31 | areas = make_request(base_url + 'area_types', 'Id') 32 | if is_test: 33 | return areas, base_url + 'area_types' 34 | return areas 35 | 36 | 37 | def get_age_id(age, is_test=False): 38 | """ 39 | Returns an ID for a given age. 40 | 41 | :param age: Search term of an age or age range as a string 42 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 43 | :return: Code used in Fingertips to represent the age as an integer or age range as a string 44 | """ 45 | ages = make_request(base_url + 'ages', 'Name') 46 | if is_test: 47 | return ages[age]['Id'], base_url + 'ages' 48 | return ages[age]['Id'] 49 | 50 | 51 | def get_age_from_id(age_id, is_test=False): 52 | """ 53 | Returns an age name from given id. 54 | 55 | :param age_id: Age id used in Fingertips as an integer 56 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 57 | :return: Age, or age range, as a string 58 | """ 59 | ages = make_request(base_url + 'ages', 'Id') 60 | if is_test: 61 | return ages[age_id]['Name'], base_url + 'ages' 62 | return ages[age_id]['Name'] 63 | 64 | 65 | def get_all_sexes(is_test=False): 66 | """ 67 | Returns a dictionary of all sex categories and their IDs as dictionary key. 68 | 69 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 70 | :return: Sex categories used in Fingertips with associated codes as a dictionary 71 | """ 72 | sexes = get_data_in_dict(base_url + 'sexes', value = 'Name') 73 | if is_test: 74 | return sexes, base_url + 'sexes' 75 | return sexes 76 | 77 | 78 | def get_sex_id(sex, is_test=False): 79 | """ 80 | Returns an ID for a given sex. 81 | 82 | :param sex: Sex category as string (Case sensitive) 83 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 84 | :return: ID used in Fingertips to represent the sex as an integer 85 | """ 86 | sexes = make_request(base_url + 'sexes', 'Name') 87 | if is_test: 88 | return sexes[sex]['Id'], base_url + 'sexes' 89 | return sexes[sex]['Id'] 90 | 91 | 92 | def get_sex_from_id(sex_id, is_test=False): 93 | """ 94 | Returns a sex name given an ID. 95 | 96 | :param sex_id: ID used in Fingertips to represent the sex as integer 97 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 98 | :return: Sex category as string 99 | """ 100 | sexes = make_request(base_url + 'sexes', 'Id') 101 | if is_test: 102 | return sexes[sex_id]['Name'], base_url + 'sexes' 103 | return sexes[sex_id]['Name'] 104 | 105 | 106 | def get_all_value_notes(is_test=False): 107 | """ 108 | Returns a dictionary of all value notes and their IDs as dictionary key. 109 | 110 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 111 | :return: Data value notes and their associated codes that are used in Fingertips as a dictionary 112 | """ 113 | value_notes = get_data_in_dict(base_url + 'value_notes', value = 'Text') 114 | if is_test: 115 | return value_notes, base_url + 'value_notes' 116 | return value_notes 117 | 118 | 119 | def get_value_note_id(value_note, is_test=False): 120 | """ 121 | Returns a value note ID for a given value note. 122 | 123 | :param value_note: Value note as string 124 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 125 | :return: ID used in Fingertips to represent the value note as an integer 126 | """ 127 | value_notes = make_request(base_url + 'value_notes', 'Text') 128 | if is_test: 129 | return value_notes[value_note]['Id'], base_url + 'value_notes' 130 | return value_notes[value_note]['Id'] 131 | 132 | 133 | def get_areas_for_area_type(area_type_id, is_test=False): 134 | """ 135 | Returns a dictionary of areas that match an area type id given the id as integer or string. 136 | 137 | :param area_type_id: ID of area type (ID of General Practice is 7 etc) used in Fingertips as integer or string 138 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 139 | :return: A dictionary of dictionaries with area codes as the key 140 | """ 141 | areas = make_request(base_url + 'areas/by_area_type?area_type_id=' + str(area_type_id), 'Code') 142 | if is_test: 143 | return areas, base_url + 'areas/by_area_type?area_type_id=' + str(area_type_id) 144 | return areas 145 | 146 | 147 | def get_metadata_for_indicator(indicator_number, is_test=False): 148 | """ 149 | Returns the metadata for an indicator given the indicator number as integer or string. 150 | 151 | :param indicator_number: Number used to identify an indicator within Fingertips as integer or string 152 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 153 | :return: A dictionary of metadata for the given indicator 154 | """ 155 | metadata = get_json(base_url + 'indicator_metadata/by_indicator_id?indicator_ids=' + str(indicator_number)) 156 | metadata_dict = metadata.get(str(indicator_number)) 157 | if is_test: 158 | return metadata, base_url + 'indicator_metadata/by_indicator_id?indicator_ids=' + str(indicator_number) 159 | return metadata_dict 160 | 161 | 162 | def get_metadata_for_all_indicators_from_csv(is_test=False): 163 | """ 164 | Returns a dataframe from the csv of all metadata for all indicators. 165 | 166 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 167 | :return: A dataframe of all metadata for all indicators 168 | """ 169 | try: 170 | metadata = pd.read_csv(base_url + 'indicator_metadata/csv/all') 171 | except URLError: 172 | metadata = deal_with_url_error(base_url + 'indicator_metadata/csv/all') 173 | if is_test: 174 | return metadata, base_url + 'indicator_metadata/csv/all' 175 | return metadata 176 | 177 | 178 | def get_metadata_for_all_indicators(include_definition='no', include_system_content='no', is_test=False): 179 | """ 180 | Returns the metadata for all indicators in a dictionary. 181 | 182 | :param include_definition: optional to include definitions 183 | :param include_system_content: optional to include system content 184 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 185 | :return: dictionary of all indicators 186 | """ 187 | url_suffix = f'indicator_metadata/all?include_definition={include_definition}&include_system_content={include_system_content}' 188 | metadata_dict = get_json(base_url + url_suffix) 189 | if is_test: 190 | return metadata_dict, base_url + url_suffix 191 | return metadata_dict 192 | 193 | 194 | def get_multiplier_and_calculation_for_indicator(indicator_number): 195 | """ 196 | Returns the multiplier and calculation method for a given indicator. 197 | 198 | :param indicator_number: Number used to identify an indicator within Fingertips as integer or string 199 | :return: A tuple of multiplier and calculation method from Fingetips metadata 200 | """ 201 | metadata = get_metadata_for_indicator(indicator_number) 202 | multiplier = metadata.get('Unit').get('Value') 203 | calc_metadata = metadata.get('ConfidenceIntervalMethod').get('Name') 204 | if 'wilson' in calc_metadata.lower(): 205 | calc = 'Wilson' 206 | elif 'byar' in calc_metadata.lower(): 207 | calc = 'Byar' 208 | else: 209 | calc = None 210 | return multiplier, calc 211 | 212 | 213 | def get_area_types_as_dict(is_test=False): 214 | """ 215 | Returns all area types and related information such as ID and name with dictionary key value as ID. 216 | 217 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 218 | :return: A dictionary of area types 219 | """ 220 | areas = get_data_in_dict(base_url + 'area_types') 221 | if is_test: 222 | return areas, base_url + 'area_types' 223 | return areas 224 | 225 | 226 | def get_profile_by_id(profile_id, is_test=False): 227 | """ 228 | Returns a profile as an dictionary which contains information about domains and sequencing. 229 | 230 | :param profile_id: ID used in Fingertips to identify a profile as integer or string 231 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 232 | :return: A dictionary of information about the profile 233 | """ 234 | if is_test: 235 | return get_json(base_url + 'profile?profile_id=' + str(profile_id)), base_url + 'profile?profile_id=' + \ 236 | str(profile_id) 237 | return get_json(base_url + 'profile?profile_id=' + str(profile_id)) 238 | 239 | 240 | def get_all_profiles(is_test=False): 241 | """ 242 | Returns all profiles. 243 | 244 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 245 | :return: A dictionary of all profiles in Fingertips including information on domains and sequencing 246 | """ 247 | profiles = get_data_in_dict(base_url + 'profiles') 248 | if is_test: 249 | return profiles, base_url + 'profiles' 250 | return profiles 251 | 252 | 253 | def get_domains_in_profile(profile_id): 254 | """ 255 | Returns the domain IDs for a given profile. 256 | 257 | :param profile_id: ID used in Fingertips to identify a profile as integer or string 258 | :return: A list of domain IDs 259 | """ 260 | profile = get_profile_by_id(profile_id) 261 | return profile['GroupIds'] 262 | 263 | 264 | def get_area_types_for_profile(profile_id, is_test=False): 265 | """ 266 | Retrieves all the area types that have data for a given profile. 267 | 268 | :param profile_id: ID used in Fingertips to identify a profile as integer or string 269 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 270 | :return: A list of dictionaries of area types with relevant information 271 | """ 272 | if is_test: 273 | return get_data_in_dict(base_url + 'area_types?profile_ids=' + str(profile_id)), base_url + 'area_types?profile_ids=' + \ 274 | str(profile_id) 275 | return get_data_in_dict(base_url + 'area_types?profile_ids=' + str(profile_id)) 276 | 277 | 278 | def get_area_type_ids_for_profile(profile_id): 279 | """ 280 | Returns a list of area types used within a given profile. 281 | 282 | :param profile_id: ID used in Fingertips to identify a profile as integer or string 283 | :return: A list of area type IDs used within a given profile 284 | """ 285 | area_type_obj = get_area_types_for_profile(profile_id) 286 | area_type_list = [value.get('Id') for value in area_type_obj.values()] 287 | return area_type_list 288 | 289 | 290 | def get_profile_by_name(profile_name): 291 | """ 292 | Returns a profile object given a name to search – try to be specific to get better results. 293 | 294 | :param profile_name: A string or part of a string that is used as the profile name 295 | :return: A dictionary of the profile metadata including domain information or an error message 296 | """ 297 | all_profiles = get_all_profiles() 298 | profile_obj = '' 299 | for profile in all_profiles.values(): 300 | if profile_name.lower() in profile.get('Name').lower(): 301 | profile_obj = profile 302 | if not profile_obj: 303 | return 'Profile could not be found' 304 | else: 305 | return profile_obj 306 | 307 | 308 | def get_profile_by_key(profile_key): 309 | """ 310 | Returns a profile object given a key (as the stub following 'profile' in the website URL). For example, 311 | give, a URL of the form `https://fingertips.phe.org.uk/profile/general-practice/data#page/3/gid/2000...`, 312 | the key is 'general-practice'. 313 | 314 | :param profile_key: The exact key for the profile. 315 | :return: A dictionary of the profile metadata including domain information or an error message 316 | """ 317 | all_profiles = get_all_profiles() 318 | for profile_id, profile_object in all_profiles.items(): 319 | if profile_object.get('Key') == profile_key: 320 | return profile_object 321 | return 'Profile could not be found' 322 | 323 | 324 | def get_metadata_for_indicator_as_dataframe(indicator_ids, is_test=False): 325 | """ 326 | Returns a dataframe of metadata for a given indicator ID or list of indicator IDs. 327 | 328 | :param indicator_ids: Number or list of numbers used to identify an indicator within Fingertips as integer or string 329 | :return: Dataframe object with metadate for the indicator ID 330 | """ 331 | url_suffix = "indicator_metadata/csv/by_indicator_id?indicator_ids={}" 332 | if isinstance(indicator_ids, list): 333 | indicator_ids = ','.join(list(map(str, indicator_ids))) 334 | try: 335 | df = pd.read_csv(base_url + url_suffix.format(str(indicator_ids))) 336 | except HTTPError: 337 | raise NameError(f'Indicator {indicator_ids} does not exist') 338 | except URLError: 339 | df = deal_with_url_error(base_url + url_suffix.format(str(indicator_ids))) 340 | if is_test: 341 | return df, base_url + url_suffix.format(str(indicator_ids)) 342 | return df 343 | 344 | 345 | def get_metadata_for_domain_as_dataframe(group_ids, is_test=False): 346 | """ 347 | Returns a dataframe of metadata for a given domain ID or list of domain IDs. 348 | 349 | :param group_ids: Number or list of numbers used to identify a domain within Fingertips as integer or string 350 | :return: Dataframe object with metadata for the indicators for a given domain ID 351 | """ 352 | url_suffix = "indicator_metadata/csv/by_group_id?group_id={}" 353 | if isinstance(group_ids, list): 354 | df = pd.DataFrame() 355 | for group_id in group_ids: 356 | try: 357 | df = pd.concat([df, pd.read_csv(base_url + url_suffix.format(str(group_id)))]) 358 | except HTTPError: 359 | raise NameError(f'Domain {group_id} does not exist') 360 | except URLError: 361 | df = deal_with_url_error(base_url + url_suffix.format(str(group_id))) 362 | else: 363 | try: 364 | df = pd.read_csv(base_url + url_suffix.format(str(group_ids))) 365 | except HTTPError: 366 | raise NameError(f'Domain {group_ids} does not exist') 367 | except URLError: 368 | df = deal_with_url_error(base_url + url_suffix.format(str(group_ids))) 369 | if is_test: 370 | return df, base_url + url_suffix.format(str(group_ids)) 371 | return df 372 | 373 | 374 | def get_metadata_for_profile_as_dataframe(profile_ids): 375 | """ 376 | Returns a dataframe of metadata for a given profile ID or list of profile IDs. 377 | 378 | :param profile_ids: ID or list of IDs used in Fingertips to identify a profile as integer or string 379 | :return: Dataframe object with metadata for the indicators for a given group ID 380 | """ 381 | url_suffix = "indicator_metadata/csv/by_profile_id?profile_id={}" 382 | if isinstance(profile_ids, list): 383 | df = pd.DataFrame() 384 | for profile_id in profile_ids: 385 | try: 386 | df = pd.concat([df, pd.read_csv(base_url + url_suffix.format(str(profile_id)))]) 387 | except HTTPError: 388 | raise NameError(f'Profile {profile_id} does not exist') 389 | except URLError: 390 | df = deal_with_url_error(base_url + url_suffix.format(str(profile_id))) 391 | else: 392 | try: 393 | df = pd.read_csv(base_url + url_suffix.format(str(profile_ids))) 394 | except HTTPError: 395 | raise NameError(f'Profile {profile_ids} does not exist') 396 | except URLError: 397 | df = deal_with_url_error(base_url + url_suffix.format(str(profile_ids))) 398 | return df 399 | 400 | 401 | def get_metadata(indicator_ids=None, domain_ids=None, profile_ids=None): 402 | """ 403 | Returns a dataframe object of metadata for a given indicator, domain, and/or profile given the relevant IDs. At 404 | least one of these IDs has to be given otherwise an error is raised. 405 | 406 | :param indicator_ids: [OPTIONAL] Number used to identify an indicator within Fingertips as integer or string 407 | :param domain_ids: [OPTIONAL] Number used to identify a domain within Fingertips as integer or string 408 | :param profile_ids: [OPTIONAL] ID used in Fingertips to identify a profile as integer or string 409 | :return: A dataframe object with metadata for the given IDs or an error if nothing is specified 410 | """ 411 | if indicator_ids and domain_ids and profile_ids: 412 | df = get_metadata_for_profile_as_dataframe(profile_ids) 413 | df = pd.concat([df, get_metadata_for_domain_as_dataframe(domain_ids)]) 414 | df = pd.concat([df, get_metadata_for_indicator_as_dataframe(indicator_ids)]) 415 | return df 416 | if indicator_ids and domain_ids: 417 | df = get_metadata_for_domain_as_dataframe(domain_ids) 418 | df = pd.concat([df, get_metadata_for_indicator_as_dataframe(indicator_ids)]) 419 | return df 420 | if indicator_ids and profile_ids: 421 | df = get_metadata_for_profile_as_dataframe(profile_ids) 422 | df = pd.concat([df, get_metadata_for_indicator_as_dataframe(indicator_ids)]) 423 | return df 424 | if domain_ids and profile_ids: 425 | df = get_metadata_for_profile_as_dataframe(profile_ids) 426 | df = pd.concat([df, get_metadata_for_domain_as_dataframe(domain_ids)]) 427 | return df 428 | if profile_ids: 429 | return get_metadata_for_profile_as_dataframe(profile_ids) 430 | if domain_ids: 431 | return get_metadata_for_domain_as_dataframe(domain_ids) 432 | if indicator_ids: 433 | return get_metadata_for_indicator_as_dataframe(indicator_ids) 434 | raise NameError('Must use a valid indicator IDs, domain IDs or profile IDs') 435 | -------------------------------------------------------------------------------- /src/fingertips_py/retrieve_data.py: -------------------------------------------------------------------------------- 1 | """ 2 | A group of functions to retrieve data from Fingertips by indicator, profile, domain (group), or geography. 3 | """ 4 | 5 | 6 | import pandas as pd 7 | from urllib.error import URLError, HTTPError 8 | from fingertips_py.api_calls import base_url, deal_with_url_error, get_json 9 | from fingertips_py.metadata import get_area_type_ids_for_profile, get_metadata_for_all_indicators, get_all_areas 10 | 11 | 12 | def get_data_by_indicator_ids(indicator_ids, area_type_id, parent_area_type_id=15, profile_id=None, 13 | include_sortable_time_periods=None, is_test=False): 14 | """ 15 | Returns a dataframe of indicator data given a list of indicators and area types. 16 | :param indicator_ids: Single indicator ID or list of indicator IDs, as integers or strings 17 | :param area_type_id: ID of area type (eg. CCG, Upper Tier Local Authority) used in Fingertips as integer or string 18 | :param parent_area_type_id: Area type of parent area - defaults to England value 19 | :param profile_id: ID of profile to select by as either int or string 20 | :param include_sortable_time_periods: Boolean as to whether to include a sort-friendly data field 21 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 22 | :return: A dataframe of data relating to the given indicators 23 | """ 24 | 25 | url_suffix = 'all_data/csv/by_indicator_id?indicator_ids={}&child_area_type_id={}&parent_area_type_id={}' 26 | if profile_id and not include_sortable_time_periods: 27 | url_addition = f'&profile_id={profile_id}' 28 | url_suffix = url_suffix + url_addition 29 | elif include_sortable_time_periods and not profile_id: 30 | url_addition = '&include_sortable_time_periods=yes' 31 | url_suffix = url_suffix + url_addition 32 | elif profile_id and include_sortable_time_periods: 33 | url_addition = f'&profile_id={profile_id}&include_sortable_time_periods=yes' 34 | url_suffix = url_suffix + url_addition 35 | if isinstance(indicator_ids, list): 36 | if any(isinstance(ind, int) for ind in indicator_ids): 37 | indicator_ids = ','.join(str(ind) for ind in indicator_ids) 38 | else: 39 | indicator_ids = ','.join(indicator_ids) 40 | else: 41 | indicator_ids = str(indicator_ids) 42 | populated_url = url_suffix.format(indicator_ids, str(area_type_id), parent_area_type_id) 43 | try: 44 | df = pd.read_csv(base_url + populated_url, low_memory = False) 45 | except URLError: 46 | df = deal_with_url_error(base_url + populated_url) 47 | if is_test: 48 | return df, base_url + populated_url 49 | return df 50 | 51 | 52 | def get_all_data_for_profile(profile_id, parent_area_type_id=15, area_type_id = None, filter_by_area_codes=None, 53 | is_test=False): 54 | """ 55 | Returns a dataframe of data for all indicators within a profile. 56 | 57 | :param profile_id: ID used in Fingertips to identify a profile as integer or string 58 | :param parent_area_type_id: Area type of parent area - defaults to England value 59 | :param area_type_id: Option to only return data for a given area type. Area type ids are string, int or a list. 60 | :param filter_by_area_codes: Option to limit returned data to areas. Areas as either string or list of strings. 61 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 62 | :return: A dataframe of data for all indicators within a profile with any filters applied 63 | """ 64 | if area_type_id is not None: 65 | if type(area_type_id) == int: 66 | area_types = [area_type_id] 67 | else: 68 | area_types = area_type_id 69 | else: 70 | area_types = get_area_type_ids_for_profile(profile_id) 71 | df = pd.DataFrame() 72 | for area in area_types: 73 | populated_url = (f'all_data/csv/by_profile_id?child_area_type_id={area}&' 74 | f'parent_area_type_id={parent_area_type_id}&' 75 | f'profile_id={profile_id}') 76 | try: 77 | df_returned = pd.read_csv(base_url + populated_url, low_memory = False) 78 | except HTTPError: 79 | raise Exception('There has been a server error with Fingertips for this request. ') 80 | except URLError: 81 | df_returned = deal_with_url_error(base_url + populated_url) 82 | df = pd.concat([df, df_returned]) 83 | if filter_by_area_codes: 84 | if isinstance(filter_by_area_codes, list): 85 | df = df.loc[df['Area Code'].isin(filter_by_area_codes)] 86 | elif isinstance(filter_by_area_codes, str): 87 | df = df.loc[df['Area Code'] == filter_by_area_codes] 88 | df = df.reset_index() 89 | if is_test: 90 | return df, base_url + populated_url 91 | return df 92 | 93 | def get_all_data_for_indicators(indicators, area_type_id, parent_area_type_id=15, filter_by_area_codes=None, 94 | is_test=False): 95 | """ 96 | Returns a dataframe of data for given indicators at an area. 97 | 98 | :param indicators: List or integer or string of indicator IDs 99 | :param area_type_id: ID of area type (eg. ID of General Practice is 7 etc) used in Fingertips as integer or string 100 | :param parent_area_type_id: Area type of parent area - defaults to England value 101 | :param filter_by_area_codes: Option to limit returned data to areas. Areas as either string or list of strings 102 | :param is_test: Used for testing. Returns a tuple of expected return and the URL called to retrieve the data 103 | :return: Dataframe of data for given indicators at an area 104 | """ 105 | if isinstance(indicators, list): 106 | if any(isinstance(ind, int) for ind in indicators): 107 | indicators = ','.join(str(ind) for ind in indicators) 108 | else: 109 | indicators = ','.join(indicators) 110 | else: 111 | indicators = str(indicators) 112 | 113 | populated_url = (f'all_data/csv/by_indicator_id?indicator_ids={indicators}&' 114 | f'child_area_type_id={area_type_id}&' 115 | f'parent_area_type_id={parent_area_type_id}') 116 | try: 117 | df = pd.read_csv(base_url + populated_url, low_memory = False) 118 | except URLError: 119 | df = deal_with_url_error(base_url + populated_url) 120 | df.reset_index() 121 | if filter_by_area_codes: 122 | if isinstance(filter_by_area_codes, list): 123 | df = df.loc[df['Area Code'].isin(filter_by_area_codes)] 124 | elif isinstance(filter_by_area_codes, str): 125 | df = df.loc[df['Area Code'] == filter_by_area_codes] 126 | df = df.reset_index() 127 | if is_test: 128 | return df, base_url + populated_url 129 | return df 130 | 131 | 132 | def get_all_areas_for_all_indicators(): 133 | """ 134 | Returns a dictionary of all indicators and their geographical breakdowns. 135 | 136 | :return: Dictionary of all indicators (ID as key) and their geographical breakdowns 137 | """ 138 | url_suffix = 'available_data' 139 | all_area_ids = get_json(base_url + url_suffix) 140 | all_indicators = list(set([x.get('IndicatorId') for x in all_area_ids])) 141 | all_indicators.sort() 142 | area_dict = {} 143 | for ind in all_indicators: 144 | area_list = [] 145 | for item in all_area_ids: 146 | if item.get('IndicatorId') == ind: 147 | area_list.append(item.get('AreaTypeId')) 148 | area_dict[ind] = area_list 149 | return area_dict 150 | 151 | 152 | def get_data_for_indicator_at_all_available_geographies(indicator_id): 153 | """ 154 | Returns a dataframe of all data for an indicator for all available geographies. 155 | 156 | :param indicator_id: Indicator id 157 | :return: Dataframe of data for indicator for all available areas for all time periods 158 | """ 159 | all_area_for_all_indicators = get_all_areas_for_all_indicators() 160 | areas_to_get = all_area_for_all_indicators.get(indicator_id) 161 | df = pd.DataFrame() 162 | for area in areas_to_get: 163 | df_temp = get_data_by_indicator_ids(indicator_id, area) 164 | df = pd.concat([df, df_temp]) 165 | df.drop_duplicates(inplace=True) 166 | return df 167 | -------------------------------------------------------------------------------- /tests/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/DataS-DHSC/fingertips_py/ead40794902f15e6b63b362a360d358e391a88f2/tests/__init__.py -------------------------------------------------------------------------------- /tests/test_all.py: -------------------------------------------------------------------------------- 1 | import pandas as pd 2 | import pytest 3 | from fingertips_py.api_calls import get_json, make_request, get_json_return_df, base_url 4 | from fingertips_py.retrieve_data import get_all_data_for_profile, get_all_data_for_indicators, get_data_by_indicator_ids, \ 5 | get_all_areas_for_all_indicators, get_data_for_indicator_at_all_available_geographies 6 | from fingertips_py.metadata import get_metadata_for_profile_as_dataframe, get_metadata, get_metadata_for_indicator_as_dataframe, \ 7 | get_metadata_for_domain_as_dataframe, get_all_value_notes, get_profile_by_name, get_area_types_for_profile, \ 8 | get_domains_in_profile, get_all_profiles, get_area_types_as_dict, get_age_from_id, get_area_type_ids_for_profile, \ 9 | get_profile_by_id, get_age_id, get_all_ages, get_all_sexes, get_areas_for_area_type, get_metadata_for_indicator, \ 10 | get_multiplier_and_calculation_for_indicator, get_sex_from_id, get_sex_id, get_value_note_id, \ 11 | get_metadata_for_all_indicators, get_metadata_for_all_indicators_from_csv, get_all_areas, get_profile_by_key 12 | from fingertips_py.area_data import deprivation_decile 13 | 14 | 15 | def test_get_json(): 16 | data = get_json('https://jsonplaceholder.typicode.com/todos/1') 17 | assert data['userId'] == 1 18 | assert isinstance(data, dict) 19 | 20 | def test_make_request(): 21 | data = make_request(base_url + 'area_types', 'Id') 22 | assert type(data) == dict 23 | assert data[15]['Name'] == 'England' 24 | 25 | 26 | def test_get_json_return_df(): 27 | data = get_json_return_df('https://jsonplaceholder.typicode.com/todos/1') 28 | assert isinstance(data, pd.DataFrame) is True 29 | 30 | 31 | # need to think about this one 32 | def test_get_all_data_for_profile(): 33 | data = get_all_data_for_profile(84, area_type_id=402, is_test=True) 34 | assert isinstance(data[0], pd.DataFrame) is True 35 | assert data[1] == base_url + 'all_data/csv/by_profile_id?child_area_type_id=402&parent_area_type_id=15&profile_id=84' 36 | 37 | 38 | def test_get_all_areas(): 39 | test_dict, url = get_all_areas(is_test=True) 40 | first_dict = test_dict.get(next(iter(test_dict))) 41 | assert isinstance(test_dict, dict) is True 42 | assert isinstance(first_dict, dict) is True 43 | assert isinstance(first_dict.get('Name'), str) is True 44 | assert url == 'https://fingertips.phe.org.uk/api/area_types' 45 | 46 | 47 | def test_get_all_data_for_indicators(): 48 | data, url = get_all_data_for_indicators([92949, 92998], area_type_id=102, is_test=True) 49 | assert isinstance(data, pd.DataFrame) is True 50 | assert data.shape[1] == 27 51 | assert url == 'https://fingertips.phe.org.uk/api/all_data/csv/by_indicator_id?indicator_ids=92949,92998&child_area_type_id=102&parent_area_type_id=15' 52 | 53 | 54 | def test_get_data_by_indicator_ids(): 55 | data, url = get_data_by_indicator_ids([92949, 92998], 102, is_test=True) 56 | assert isinstance(data, pd.DataFrame) is True 57 | assert data.shape[1] == 27 58 | assert url == 'https://fingertips.phe.org.uk/api/all_data/csv/by_indicator_id?indicator_ids=92949,92998&child_area_type_id=102&parent_area_type_id=15' 59 | 60 | 61 | def test_get_all_areas_for_all_indicators(): 62 | test_dict = get_all_areas_for_all_indicators() 63 | first_list = test_dict.get(next(iter(test_dict))) 64 | assert isinstance(test_dict, dict) is True 65 | assert 15 in first_list 66 | 67 | 68 | def test_get_data_for_indicator_at_all_available_geographies(): 69 | data = get_data_for_indicator_at_all_available_geographies(92998) 70 | assert isinstance(data, pd.DataFrame) is True 71 | assert data.shape[1] == 27 72 | 73 | 74 | def test_get_metadata_for_profile_as_dataframe(): 75 | data = get_metadata_for_profile_as_dataframe(84) 76 | assert isinstance(data, pd.DataFrame) is True 77 | assert data.shape[1] == 32 78 | 79 | 80 | def test_get_metadata(): 81 | data_indicators = get_metadata(indicator_ids=[92949, 90581]) 82 | data_domain = get_metadata(domain_ids=[1938133052, 1938132811]) 83 | data_profile = get_metadata(profile_ids=84) 84 | data_indicators_and_domain = get_metadata(indicator_ids=[92949, 90581], domain_ids=[1938133052, 1938132811]) 85 | data_domain_and_profile = get_metadata(domain_ids=[1938133052, 1938132811], profile_ids=84) 86 | #data_profile_and_indicators = get_metadata(indicator_ids=[92949, 90581], profile_ids=84) ####! 87 | data_all = get_metadata(indicator_ids=[92949, 90581], domain_ids=[1938133052, 1938132811], profile_ids=84) 88 | assert isinstance(data_indicators, pd.DataFrame) is True 89 | assert data_indicators.shape[1] == 32 90 | assert isinstance(data_domain, pd.DataFrame) is True 91 | assert data_domain.shape[1] == 32 92 | assert isinstance(data_profile, pd.DataFrame) is True 93 | assert data_profile.shape[1] == 32 94 | assert isinstance(data_indicators_and_domain, pd.DataFrame) is True 95 | assert data_indicators_and_domain.shape[1] == 32 96 | assert isinstance(data_domain_and_profile, pd.DataFrame) is True 97 | assert data_domain_and_profile.shape[1] == 32 98 | #assert isinstance(data_profile_and_indicators, pd.DataFrame) is True 99 | #assert data_profile_and_indicators.shape[1] == 32 100 | assert isinstance(data_all, pd.DataFrame) is True 101 | assert data_all.shape[1] == 32 102 | 103 | 104 | def test_get_metadata_for_indicator_as_dataframe(): 105 | data = get_metadata_for_indicator_as_dataframe(247, is_test=True) 106 | assert isinstance(data[0], pd.DataFrame) is True 107 | assert data[0].shape[1] == 32 108 | assert data[1] == 'https://fingertips.phe.org.uk/api/indicator_metadata/csv/by_indicator_id?indicator_ids=247' 109 | 110 | 111 | def test_get_metadata_for_domain_as_dataframe(): 112 | data = get_metadata_for_domain_as_dataframe(1938132811, is_test=True) 113 | assert isinstance(data[0], pd.DataFrame) is True 114 | assert data[0].shape[1] == 32 115 | assert data[1] == 'https://fingertips.phe.org.uk/api/indicator_metadata/csv/by_group_id?group_id=1938132811' 116 | 117 | 118 | def test_get_all_value_notes(): 119 | test_dict = get_all_value_notes() 120 | first_item = test_dict.get(next(iter(test_dict))) 121 | assert isinstance(test_dict, dict) is True 122 | assert isinstance(first_item, str) is True 123 | 124 | 125 | def test_get_profile_by_name(): 126 | data = get_profile_by_name('dementia') 127 | assert isinstance(data, dict) is True 128 | assert data['Id'] == 84 129 | 130 | 131 | def test_get_profile_by_key(): 132 | data = get_profile_by_key("general-practice") 133 | assert isinstance(data, dict) is True 134 | assert data['Id'] == 20 135 | 136 | # no 137 | def test_get_area_types_for_profile(): 138 | test_dict = get_area_types_for_profile(84) 139 | first_item = test_dict.get(next(iter(test_dict))) 140 | assert isinstance(test_dict, dict) is True 141 | assert isinstance(first_item, dict) is True 142 | 143 | 144 | def test_get_domains_in_profile(): 145 | test_list = get_domains_in_profile(84) 146 | assert isinstance(test_list, list) is True 147 | assert isinstance(test_list[0], int) is True 148 | 149 | 150 | def test_get_all_profiles(): 151 | test_dict = get_all_profiles() 152 | first_item = test_dict.get(next(iter(test_dict))) 153 | assert isinstance(test_dict, dict) is True 154 | assert isinstance(first_item, dict) is True 155 | 156 | 157 | def test_get_area_types_as_dict(): 158 | test_dict = get_area_types_as_dict() 159 | first_item = test_dict.get(next(iter(test_dict))) 160 | assert isinstance(test_dict, dict) is True 161 | assert isinstance(first_item, dict) is True 162 | 163 | 164 | def test_get_age_from_id(): 165 | data = get_age_from_id(1) 166 | assert data == 'All ages' 167 | 168 | 169 | def test_get_area_type_ids_for_profile(): 170 | data = get_area_type_ids_for_profile(84) 171 | assert isinstance(data, list) is True 172 | assert isinstance(data[1], int) is True 173 | 174 | 175 | def test_get_profile_by_id(): 176 | data = get_profile_by_id(84) 177 | assert isinstance(data, dict) is True 178 | 179 | 180 | def test_get_age_id(): 181 | data = get_age_id('All ages') 182 | assert data == 1 183 | 184 | 185 | def test_get_all_ages(): 186 | test_dict = get_all_ages() 187 | first_item = test_dict.get(next(iter(test_dict))) 188 | assert isinstance(test_dict, dict) is True 189 | assert isinstance(first_item, dict) is True 190 | 191 | 192 | def test_get_all_sexes(): 193 | test_dict = get_all_sexes() 194 | first_item = test_dict.get(next(iter(test_dict))) 195 | assert isinstance(test_dict, dict) is True 196 | assert isinstance(first_item, str) is True 197 | 198 | 199 | def test_get_areas_for_area_type(): 200 | data = get_areas_for_area_type(102) 201 | assert isinstance(data, dict) is True 202 | assert isinstance(list(data.values())[0], dict) is True 203 | 204 | 205 | def test_get_metadata_for_indicator(): 206 | data = get_metadata_for_indicator(247) 207 | assert isinstance(data, dict) is True 208 | 209 | 210 | def test_get_multiplier_and_calculation_for_indicator(): 211 | data = get_multiplier_and_calculation_for_indicator(247) 212 | assert isinstance(data, tuple) is True 213 | assert data[0] == 100 214 | 215 | 216 | def test_get_sex_from_id(): 217 | data = get_sex_from_id(1) 218 | assert data == 'Male' 219 | 220 | 221 | def test_get_sex_id(): 222 | data = get_sex_id('Male') 223 | assert data == 1 224 | 225 | 226 | def test_get_value_note_id(): 227 | data = get_value_note_id('Value suppressed for disclosure control due to small count') 228 | assert data == 101 229 | 230 | 231 | def test_get_metadata_for_all_indicators(): 232 | test_dict = get_metadata_for_all_indicators() 233 | first_item = test_dict.get(next(iter(test_dict))) 234 | assert isinstance(test_dict, dict) is True 235 | assert len(first_item.keys()) == 15 236 | 237 | 238 | def test_get_metadata_for_all_indicators_from_csv(): 239 | data = get_metadata_for_all_indicators_from_csv() 240 | assert isinstance(data, pd.DataFrame) is True 241 | assert data.shape[1] == 32 242 | 243 | # deprivation decile needs to work 244 | def test_deprivation_decile(): 245 | data = deprivation_decile(7) 246 | assert len(data.unique()) == 10 247 | --------------------------------------------------------------------------------