diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..eab0fd0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,43 @@ +--- +name: Bug Report +about: Use to report a bug +title: '' +labels: bug +assignees: '' +--- + +## Bug Report + +### Description + +Provide a brief overview of the bug encountered. Describe the behavior observed when the bug occurs and explain the behavior expected when the bug is not present. + +### Reproducibility + +- [ ] The bug is reproducible. +- [ ] The bug is intermittent. +- [ ] The bug occurs only under specific conditions. + +#### Steps to Reproduce + +1. List the steps to reproduce the bug. +2. Be as detailed as possible to help with replication. + +#### Screenshots / Error Messages (if applicable) + +Insert any relevant screenshots or error messages related to the bug. + +#### Environment + +- **Operating System**: [e.g., Windows 10, macOS, Linux] +- **Browser (if applicable)**: [e.g., Google Chrome, Firefox, Safari] +- **Application Version/Commit**: [e.g., v1.2.3, Git commit hash] +- **Additional Environment Details**: [e.g., hardware specifications, network conditions] + +### Additional Context + +Provide any additional context or information about the bug. + +### Possible Fix + +If you have suggestions for a fix, please describe them here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..bbcbbe7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: '' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/peer_review.md b/.github/ISSUE_TEMPLATE/peer_review.md new file mode 100644 index 0000000..251d8a1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/peer_review.md @@ -0,0 +1,42 @@ +--- +name: Peer Review +about: Use to submit a peer review +title: '' +labels: review +assignees: '' +--- + +## Peer Review for Reproducibility Checks + +### Review Checklist + +Please review the following aspects related to reproducibility checks: + +- [ ] **Environment Setup**: + - [ ] Were detailed instructions provided for setting up the development environment? + - [ ] Are all necessary dependencies and libraries clearly documented? +- [ ] **Data Preparation**: + - [ ] Are source data files and preprocessing steps clearly documented? + - [ ] Are scripts or commands for data transformation included and well-documented? +- [ ] **Code Execution**: + - [ ] Were clear instructions provided for running the code? + - [ ] Does the code execute without errors and produce expected outputs? +- [ ] **Configuration Management**: + - [ ] Is version control information (e.g., Git commit hash) included for reproducibility? + - [ ] Are any configuration files or parameters used properly documented? +- [ ] **Results Verification**: + - [ ] Are output results (e.g., metrics, visualizations) included and matched with expected outcomes? + - [ ] Have any discrepancies between expected and actual results been identified and explained? +- [ ] **Documentation**: + - [ ] Is there a detailed README or documentation explaining the experiment setup and execution process? + - [ ] Are code comments and documentation clear and informative? +- [ ] **External Dependencies**: + - [ ] Are any external data sources or APIs used accessible and well-documented? + - [ ] Are external libraries or packages properly cited and versioned for reproducibility? +- [ ] **Validation**: + - [ ] Can an independent reviewer replicate the experiment using the provided instructions? + - [ ] Are the results consistent across different environments or platforms? + +### Additional Comments + +Include any additional comments, concerns, or suggestions related to reproducibility. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..6a7695c --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..72132d3 --- /dev/null +++ b/.github/workflows/gh-pages.yml @@ -0,0 +1,31 @@ +name: Publish to GitHub Pages + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.10" + cache: "pip" + - name: Dependencies + run: | + if [ -f docs/requirements.txt ]; then pip install -r docs/requirements.txt; fi + if [ -f pyproject.toml ]; then pip install ".[docs]"; fi + - name: Build Jupyter Book + run: | + jupyter-book build . --config docs/_config.yml --toc docs/_toc.yml + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/main' && job.status == 'success' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./_build/html + enable_jekyll: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..3474f25 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,39 @@ +# See https://pre-commit.com for more information +# See https://pre-commit.com/hooks.html for more hooks +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + - id: check-ast + - id: check-json + - id: detect-aws-credentials + args: [--allow-missing-credentials] + - id: detect-private-key + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.39.0 + hooks: + - id: markdownlint + name: Markdownlint + files: \.(md|mdown|markdown)$ + args: [ + "--disable=MD013", # line-length + "--disable=MD033", # no-inline-html + ] + - repo: https://github.com/codespell-project/codespell + rev: v2.2.6 + hooks: + - id: codespell + name: codespell + description: Checks for common misspellings in text files + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.3.3 + hooks: + - id: ruff + types_or: [python, pyi, jupyter] + args: [--fix] + - id: ruff-format + types_or: [python, pyi, jupyter] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ef17e49 --- /dev/null +++ b/LICENSE @@ -0,0 +1,385 @@ +Mozilla Public License Version 2.0 +================================== + +1. Definitions + +-------------- + +1.1. "Contributor" + means each individual or legal entity that creates, contributes to + the creation of, or owns Covered Software. + +1.2. "Contributor Version" + means the combination of the Contributions of others (if any) used + by a Contributor and that particular Contributor's Contribution. + +1.3. "Contribution" + means Covered Software of a particular Contributor. + +1.4. "Covered Software" + means Source Code Form to which the initial Contributor has attached + the notice in Exhibit A, the Executable Form of such Source Code + Form, and Modifications of such Source Code Form, in each case + including portions thereof. + +1.5. "Incompatible With Secondary Licenses" + means + + (a) that the initial Contributor has attached the notice described + in Exhibit B to the Covered Software; or + + (b) that the Covered Software was made available under the terms of + version 1.1 or earlier of the License, but not also under the + terms of a Secondary License. + +1.6. "Executable Form" + means any form of the work other than Source Code Form. + +1.7. "Larger Work" + means a work that combines Covered Software with other material, in + a separate file or files, that is not Covered Software. + +1.8. "License" + means this document. + +1.9. "Licensable" + means having the right to grant, to the maximum extent possible, + whether at the time of the initial grant or subsequently, any and + all of the rights conveyed by this License. + +1.10. "Modifications" + means any of the following: + + (a) any file in Source Code Form that results from an addition to, + deletion from, or modification of the contents of Covered + Software; or + + (b) any new file in Source Code Form that contains any Covered + Software. + +1.11. "Patent Claims" of a Contributor + means any patent claim(s), including without limitation, method, + process, and apparatus claims, in any patent Licensable by such + Contributor that would be infringed, but for the grant of the + License, by the making, using, selling, offering for sale, having + made, import, or transfer of either its Contributions or its + Contributor Version. + +1.12. "Secondary License" + means either the GNU General Public License, Version 2.0, the GNU + Lesser General Public License, Version 2.1, the GNU Affero General + Public License, Version 3.0, or any later versions of those + licenses. + +1.13. "Source Code Form" + means the form of the work preferred for making modifications. + +1.14. "You" (or "Your") + means an individual or a legal entity exercising rights under this + License. For legal entities, "You" includes any entity that + controls, is controlled by, or is under common control with You. For + purposes of this definition, "control" means (a) the power, direct + or indirect, to cause the direction or management of such entity, + whether by contract or otherwise, or (b) ownership of more than + fifty percent (50%) of the outstanding shares or beneficial + ownership of such entity. + +2. License Grants and Conditions + +-------------------------------- + +2.1. Grants + +Each Contributor hereby grants You a world-wide, royalty-free, +non-exclusive license: + +(a) under intellectual property rights (other than patent or trademark) + Licensable by such Contributor to use, reproduce, make available, + modify, display, perform, distribute, and otherwise exploit its + Contributions, either on an unmodified basis, with Modifications, or + as part of a Larger Work; and + +(b) under Patent Claims of such Contributor to make, use, sell, offer + for sale, have made, import, and otherwise transfer either its + Contributions or its Contributor Version. + +2.2. Effective Date + +The licenses granted in Section 2.1 with respect to any Contribution +become effective for each Contribution on the date the Contributor first +distributes such Contribution. + +2.3. Limitations on Grant Scope + +The licenses granted in this Section 2 are the only rights granted under +this License. No additional rights or licenses will be implied from the +distribution or licensing of Covered Software under this License. +Notwithstanding Section 2.1(b) above, no patent license is granted by a +Contributor: + +(a) for any code that a Contributor has removed from Covered Software; + or + +(b) for infringements caused by: (i) Your and any other third party's + modifications of Covered Software, or (ii) the combination of its + Contributions with other software (except as part of its Contributor + Version); or + +(c) under Patent Claims infringed by Covered Software in the absence of + its Contributions. + +This License does not grant any rights in the trademarks, service marks, +or logos of any Contributor (except as may be necessary to comply with +the notice requirements in Section 3.4). + +2.4. Subsequent Licenses + +No Contributor makes additional grants as a result of Your choice to +distribute the Covered Software under a subsequent version of this +License (see Section 10.2) or under the terms of a Secondary License (if +permitted under the terms of Section 3.3). + +2.5. Representation + +Each Contributor represents that the Contributor believes its +Contributions are its original creation(s) or it has sufficient rights +to grant the rights to its Contributions conveyed by this License. + +2.6. Fair Use + +This License is not intended to limit any rights You have under +applicable copyright doctrines of fair use, fair dealing, or other +equivalents. + +2.7. Conditions + +Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted +in Section 2.1. + +3. Responsibilities + +------------------- + +3.1. Distribution of Source Form + +All distribution of Covered Software in Source Code Form, including any +Modifications that You create or to which You contribute, must be under +the terms of this License. You must inform recipients that the Source +Code Form of the Covered Software is governed by the terms of this +License, and how they can obtain a copy of this License. You may not +attempt to alter or restrict the recipients' rights in the Source Code +Form. + +3.2. Distribution of Executable Form + +If You distribute Covered Software in Executable Form then: + +(a) such Covered Software must also be made available in Source Code + Form, as described in Section 3.1, and You must inform recipients of + the Executable Form how they can obtain a copy of such Source Code + Form by reasonable means in a timely manner, at a charge no more + than the cost of distribution to the recipient; and + +(b) You may distribute such Executable Form under the terms of this + License, or sublicense it under different terms, provided that the + license for the Executable Form does not attempt to limit or alter + the recipients' rights in the Source Code Form under this License. + +3.3. Distribution of a Larger Work + +You may create and distribute a Larger Work under terms of Your choice, +provided that You also comply with the requirements of this License for +the Covered Software. If the Larger Work is a combination of Covered +Software with a work governed by one or more Secondary Licenses, and the +Covered Software is not Incompatible With Secondary Licenses, this +License permits You to additionally distribute such Covered Software +under the terms of such Secondary License(s), so that the recipient of +the Larger Work may, at their option, further distribute the Covered +Software under the terms of either this License or such Secondary +License(s). + +3.4. Notices + +You may not remove or alter the substance of any license notices +(including copyright notices, patent notices, disclaimers of warranty, +or limitations of liability) contained within the Source Code Form of +the Covered Software, except that You may alter any license notices to +the extent required to remedy known factual inaccuracies. + +3.5. Application of Additional Terms + +You may choose to offer, and to charge a fee for, warranty, support, +indemnity or liability obligations to one or more recipients of Covered +Software. However, You may do so only on Your own behalf, and not on +behalf of any Contributor. You must make it absolutely clear that any +such warranty, support, indemnity, or liability obligation is offered by +You alone, and You hereby agree to indemnify every Contributor for any +liability incurred by such Contributor as a result of warranty, support, +indemnity or liability terms You offer. You may include additional +disclaimers of warranty and limitations of liability specific to any +jurisdiction. + +4. Inability to Comply Due to Statute or Regulation + +--------------------------------------------------- + +If it is impossible for You to comply with any of the terms of this +License with respect to some or all of the Covered Software due to +statute, judicial order, or regulation then You must: (a) comply with +the terms of this License to the maximum extent possible; and (b) +describe the limitations and the code they affect. Such description must +be placed in a text file included with all distributions of the Covered +Software under this License. Except to the extent prohibited by statute +or regulation, such description must be sufficiently detailed for a +recipient of ordinary skill to be able to understand it. + +5. Termination + +-------------- + +5.1. The rights granted under this License will terminate automatically +if You fail to comply with any of its terms. However, if You become +compliant, then the rights granted under this License from a particular +Contributor are reinstated (a) provisionally, unless and until such +Contributor explicitly and finally terminates Your grants, and (b) on an +ongoing basis, if such Contributor fails to notify You of the +non-compliance by some reasonable means prior to 60 days after You have +come back into compliance. Moreover, Your grants from a particular +Contributor are reinstated on an ongoing basis if such Contributor +notifies You of the non-compliance by some reasonable means, this is the +first time You have received notice of non-compliance with this License +from such Contributor, and You become compliant prior to 30 days after +Your receipt of the notice. + +5.2. If You initiate litigation against any entity by asserting a patent +infringement claim (excluding declaratory judgment actions, +counter-claims, and cross-claims) alleging that a Contributor Version +directly or indirectly infringes any patent, then the rights granted to +You by any and all Contributors for the Covered Software under Section +2.1 of this License shall terminate. + +5.3. In the event of termination under Sections 5.1 or 5.2 above, all +end user license agreements (excluding distributors and resellers) which +have been validly granted by You or Your distributors under this License +prior to termination shall survive termination. + +************************************************************************ + +* * +* 6. Disclaimer of Warranty * +* ------------------------- * +* * +* Covered Software is provided under this License on an "as is" * +* basis, without warranty of any kind, either expressed, implied, or * +* statutory, including, without limitation, warranties that the * +* Covered Software is free of defects, merchantable, fit for a * +* particular purpose or non-infringing. The entire risk as to the * +* quality and performance of the Covered Software is with You. * +* Should any Covered Software prove defective in any respect, You * +* (not any Contributor) assume the cost of any necessary servicing, * +* repair, or correction. This disclaimer of warranty constitutes an * +* essential part of this License. No use of any Covered Software is * +* authorized under this License except under this disclaimer. * +* * + +************************************************************************ + +************************************************************************ + +* * +* 7. Limitation of Liability * +* -------------------------- * +* * +* Under no circumstances and under no legal theory, whether tort * +* (including negligence), contract, or otherwise, shall any * +* Contributor, or anyone who distributes Covered Software as * +* permitted above, be liable to You for any direct, indirect, * +* special, incidental, or consequential damages of any character * +* including, without limitation, damages for lost profits, loss of * +* goodwill, work stoppage, computer failure or malfunction, or any * +* and all other commercial damages or losses, even if such party * +* shall have been informed of the possibility of such damages. This * +* limitation of liability shall not apply to liability for death or * +* personal injury resulting from such party's negligence to the * +* extent applicable law prohibits such limitation. Some * +* jurisdictions do not allow the exclusion or limitation of * +* incidental or consequential damages, so this exclusion and * +* limitation may not apply to You. * +* * + +************************************************************************ + +8. Litigation + +------------- + +Any litigation relating to this License may be brought only in the +courts of a jurisdiction where the defendant maintains its principal +place of business and such litigation shall be governed by laws of that +jurisdiction, without reference to its conflict-of-law provisions. +Nothing in this Section shall prevent a party's ability to bring +cross-claims or counter-claims. + +9. Miscellaneous + +---------------- + +This License represents the complete agreement concerning the subject +matter hereof. If any provision of this License is held to be +unenforceable, such provision shall be reformed only to the extent +necessary to make it enforceable. Any law or regulation which provides +that the language of a contract shall be construed against the drafter +shall not be used to construe this License against a Contributor. + +10. Versions of the License + +--------------------------- + +10.1. New Versions + +Mozilla Foundation is the license steward. Except as provided in Section +10.3, no one other than the license steward has the right to modify or +publish new versions of this License. Each version will be given a +distinguishing version number. + +10.2. Effect of New Versions + +You may distribute the Covered Software under the terms of the version +of the License under which You originally received the Covered Software, +or under the terms of any subsequent version published by the license +steward. + +10.3. Modified Versions + +If you create software not governed by this License, and you want to +create a new license for such software, you may create and use a +modified version of this License if you rename the license and remove +any references to the name of the license steward (except to note that +such modified license differs from this License). + +10.4. Distributing Source Code Form that is Incompatible With Secondary +Licenses + +If You choose to distribute Source Code Form that is Incompatible With +Secondary Licenses under the terms of this version of the License, the +notice described in Exhibit B of this License must be attached. + +Exhibit A - Source Code Form License Notice +------------------------------------------- + + This Source Code Form is subject to the terms of the Mozilla Public + License, v. 2.0. If a copy of the MPL was not distributed with this + file, You can obtain one at . + +If it is not possible or desirable to put the notice in a particular +file, then You may include the notice in a location (such as a LICENSE +file in a relevant directory) where a recipient would be likely to look +for such a notice. + +You may add additional accurate notices of copyright ownership. + +Exhibit B - "Incompatible With Secondary Licenses" Notice +--------------------------------------------------------- + + This Source Code Form is "Incompatible With Secondary Licenses", as + defined by the Mozilla Public License, v. 2.0. diff --git a/README.md b/README.md new file mode 100644 index 0000000..cc5feea --- /dev/null +++ b/README.md @@ -0,0 +1,18 @@ +# Mobilyze: Mobility Analysis + +![Development Status](https://img.shields.io/badge/status-in%20development-orange) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/datapartnership/mobilyze/main.svg)](https://results.pre-commit.ci/latest/github/datapartnership/mobilyze/main) + +## Overview + +**Mobilyze** is a Python package currently in development, designed to analyze and quantify activity levels based on mobility data, aiming to offer a set of tools to process, visualize, and interpret movement data, providing valuable insights into activity intensity and patterns. + +### Features + +- **Data Processing:** Efficiently preprocess and clean raw mobility data. +- **Activity Level Calculation:** Determine activity intensity based on mobility data. +- **Customizable Metrics:** Define and calculate custom mobility metrics tailored to your specific needs. + +## License + +This project is licensed under the [**Mozilla Public License**](https://opensource.org/license/mpl-2-0/) - see the [LICENSE](LICENSE) file for details. diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..9d623a1 --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,119 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[github@worldbank.org](mailto:github@worldbank.org) +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.0. Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..88ff556 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,93 @@ +# CONTRIBUTING + +Thank you for considering contributing to this project! Your involvement helps improve the overall quality and functionality of the project and its codebase. Please take a moment to review the following guidelines to ensure a collaborative contribution process. + +## Code of Conduct + +Please note that we have a [Code of Conduct](CODE_OF_CONDUCT.md) in place. We expect all contributors to adhere to it, both in interactions within this project and in interactions with other project members to promote a welcoming and inclusive environment for everyone. + +## How Can I Contribute? + +There are several ways you can contribute to this project: + +- **🐞 Bug Reports:** If you encounter a bug or unexpected behavior, please open an issue on GitHub. Be sure to include as much detail as possible to help us identify and fix the problem. + +- **✨ Feature Requests**: If you have an idea for a new feature or enhancement, please open an issue on GitHub. Describe the feature and its use case in detail. + +- **πŸ“£ Community Engagement:** Ask questions, help other contributors and engage with the community on our [Discussions](https://github.com/orgs/worldbank/discussions). + +- **πŸ“– Documentation Feedback:** If you find any errors or have suggestions for improving our documentation, you can report the issue on GitHub. + +- **πŸ—οΈ Pull Requests (PR):** If you'd like to contribute code or documentation changes, we encourage you to submit a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). + +## Contributing to the Code and Documentation + +Whether you are novice and expert, your contribution is valuable. If you're contributing code, we recommend getting started with [GitHub Guides](https://github.com/git-guides), [GitHub Skills](https://skills.github.com/), [GitHub Desktop](https://desktop.github.com) and/or [GitHub Docs](https://docs.github.com/en/get-started). In special, see also [collaborating with pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests). When ready, you may follow these guidelines: + +1. **[Fork the Repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)**: Click the "Fork" button on the top-right corner of this repository on GitHub. This will create a copy of the project in your GitHub account. Then, clone or download this repository to your local machine. Then, navigate to the root directory of the repository. + +2. **[Create a Branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository):** Create a new branch for your feature or bug fix. Use a clear and descriptive name for your branch, like `feature/new-feature`. + +3. **Code Review and Changes:** Make your code changes and ensure they adhere to our coding standards. + +4. **Test:** Ensure that your changes do not break existing functionality. + +5. **[Commit and Push](https://github.com/git-guides/git-commit):** Commit your changes with a clear and concise commit message. Reference any related issues or pull requests in your commit message. Push your branch to your forked repository on GitHub. + +6. **[Create a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request):** Open a pull request against the main branch of this repository. Provide a clear description of your changes and reference any relevant issues. Your PR will be reviewed by maintainers. + +7. **[Review and Iterate](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review):** Expect feedback and be prepared to make additional changes if necessary. We may request changes, and once everything looks good, your PR will be merged. + +### Cloning the Repository Locally + +[Cloning](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository), in the context of version control systems like [Git](https://git-scm.com), refers to the process of creating a copy of a repository from a remote location (such as a [GitHub](https://github.com) repository) onto your local machine. When you clone a repository, you replicate all of its files, folders, commit history, and branches onto your local system. This allows you to work on the project's codebase locally, make changes, create new branches, and contribute to the project without affecting the original repository. + +To clone a repository, you'll need the repository's URL and a Git client installed on your computer. First, open your [Git](https://git-scm.com) client of choice, such as [GitHub Desktop](https://desktop.github.com) or [GitKraken](https://www.gitkraken.com). Then, locate the option to clone a repository. In most [Git](https://git-scm.com) clients, this option is typically found under the "File" or "Repository" menu. Next, paste the URL of the repository you want to clone into the designated field. This URL can usually be found on the repository's [GitHub](https://github.com) page by clicking the green "Code" button and copying the URL provided. Once you've pasted the URL, choose the local directory where you want to save the cloned repository on your computer. Finally, initiate the cloning process by clicking the "Clone" button. The [Git](https://git-scm.com) client will then download a copy of the repository to your local machine, allowing you to work on the files locally and collaborate with others on the project. + +Alternatively, with you're using [Git CLI](https://git-scm.com/downloads), please follow the step below: + + ```shell + git clone https://github.com/PATH-TO/REPOSITORY + ``` + +### Running Notebooks Locally + +This repository provides a Conda/Mamba environment configuration to ensure consistent dependencies across different environments. [Conda](https://docs.conda.io)/[Mamba](https://mamba.readthedocs.io) are prevalent (interoperable) package managers. If haven't installed either, you may follow the installation instructions on the respective documentation. + +To run the notebooks locally, after (1) and (2) above, please follow these steps: + +- Create (or update) the environment: + + ```shell + mamba env create -f notebooks/environment.yml + ``` + + This command will create a new environment based on the specifications provided in the `environment.yml` file. + +- [Activate the environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment), run [JupyterLab](https://jupyterlab.readthedocs.io) and execute `notebooks`: + + ```shell + jupyterlab + ``` + +### Building Documentation Locally + +To build the documentation locally, after (1) and (2) above, please follow these steps: + +- Install the documentation dependencies: + + ```shell + pip install -r docs/requirements.txt + ``` + +- Build the documentation: + + ```shell + jupyter-book build . --config docs/_config.yml --toc docs/_toc.yml + ``` + +The generated documentation will be available in the `_build/html` directory. Open the `index.html` file in a web browser to view it. + +## Licensing + +By contributing to this project, you agree that your contributions will be licensed under the project's [LICENSE](LICENSE). diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..04fa31d --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,44 @@ +# Book settings +title: +author: Development Data Group +logo: docs/images/logo.png +only_build_toc_files: true + +repository: + url: https://github.com/datapartnership/mobilyze + branch: main + +####################################################################################### +# HTML-specific settings +html: + home_page_in_navbar: true + extra_navbar: "" + use_edit_page_button: true + use_repository_button: true + use_issues_button: true + baseurl: https://datapartnership.github.io/mobilyze + extra_footer: | +
+ Country borders or names do not necessarily reflect the World Bank Group’s official position. All maps are for illustrative purposes and do not imply the expression of any opinion on the part of the World Bank, concerning the legal status of any country or territory or concerning the delimitation of frontiers or boundaries +
+
+ All content (unless otherwise specified) is subject to the Mozilla Public License. +
+ favicon: docs/images/favicon.ico + +####################################################################################### +# Execution settings +execute: + execute_notebooks: off + +####################################################################################### +# Bibliography settings +bibtex_bibfiles: + - docs/bibliography.bib + +####################################################################################### +# Sphinx settings +sphinx: + config: + html_show_copyright: false + html_last_updated_fmt: "%b %d, %Y" diff --git a/docs/_toc.yml b/docs/_toc.yml new file mode 100644 index 0000000..db6cae3 --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,7 @@ +format: jb-book +root: README + +parts: + - caption: Literature Review & Methodology + chapters: + - file: docs/methodology \ No newline at end of file diff --git a/docs/bibliography.bib b/docs/bibliography.bib new file mode 100644 index 0000000..b9354f4 --- /dev/null +++ b/docs/bibliography.bib @@ -0,0 +1,46 @@ +@misc{Achyunda2020MeasuringTE, + title={Measuring the Economics of a Pandemic: How People Mobility depict Economics? An Evidence of People's Mobility Data towards Economic Activities. Randra Putra, Silvia Arini}, + author={Rendra Achyunda and Anugrah Putra and Silvia Fitri Mei Arini}, + year={2020}, + url={https://www.imf.org/-/media/Files/Conferences/2020/8th-stats-forum/paper-rendra-putra-and-silvia-arini.ashx} +} +@article{Makris2022MechanicalAF, + title={Mechanical analogue for cities}, + author={Nicos Makris and Gholamreza Moghimi and Eric Godat and Tue M. Vu}, + journal={Royal Society Open Science}, + year={2022}, + volume={10}, + doi={10.1098/rsos.220943} +} +@article{Saha2020LockdownFC, + title={{Lockdown for COVID-19 and its impact on community mobility in India: An analysis of the COVID-19 Community Mobility Reports, 2020}}, + author={Jay Saha and Bikash Barman and Pradip Chouhan}, + journal={Children and Youth Services Review}, + year={2020}, + volume={116}, + pages={105160 - 105160}, + doi={10.1016/j.childyouth.2020.105160} +} +@book{10.1145/3292500.3340412, +author = {Maas, Paige}, +title = {Facebook Disaster Maps: Aggregate Insights for Crisis Response \& Recovery}, +year = {2019}, +isbn = {9781450362016}, +publisher = {Association for Computing Machinery}, +address = {New York, NY, USA}, +url = {https://doi.org/10.1145/3292500.3340412}, +doi = {10.1145/3292500.3340412}, +abstract = {After a natural disaster or other crisis, humanitarian organizations need to know where affected people are located and what resources they need. While this information is difficult to capture quickly through conventional methods, aggregate usage patterns of social media apps like Facebook can help fill these information gaps. This talk will describe the data and methodology that power Facebook Disaster Maps. These maps utilize information about Facebook usage in areas impacted by natural hazards, producing insights into how the population is affected by and responding to the hazard. In addition to methodology details, including efforts taken to ensure the security and privacy of Facebook users, I'll also discuss how we worked with humanitarian partners to develop the maps, which are actively used in disaster response today. I'll give examples of insights generated from the maps and I'll also discuss some limitations of the current methodologies, challenges, and opportunities for improvement.}, +booktitle = {Proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery \& Data Mining}, +pages = {3173}, +numpages = {1}, +keywords = {disaster response, mapping}, +location = {Anchorage, AK, USA}, +series = {KDD '19} +} +@online{worldbankeca, +title = {{Climate Change in Europe and Central Asia}}, +url = {https://www.worldbank.org/en/region/eca/brief/climate-change-in-europe-and-central-asia}, +urldate = {2023-01-05}, +} + diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 0000000..6fa0889 Binary files /dev/null and b/docs/images/favicon.ico differ diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 0000000..9c46884 Binary files /dev/null and b/docs/images/logo.png differ diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..19b85ac --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,50 @@ +[build-system] +requires = ["hatchling>=1.21.0", "hatch-vcs>=0.3.0"] +build-backend = "hatchling.build" + +[project] +name = "mobilyze" +description = "A Python package harnessing mobility data to quantify movement intensity" +readme = { file = "README.md", content-type = "text/markdown" } +license = { file = "LICENSE" } +keywords = ["mobility"] +authors = [{ name = "Development Data Group", email = "datalab@worldbank.org" }] +classifiers = [ + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3 :: Only", + "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)", + "Operating System :: OS Independent", + "Intended Audience :: Developers", + "Topic :: Scientific/Engineering", +] +dynamic = ["version"] + +requires-python = ">=3.10" +dependencies = ["pandas>=2", "dask>=2024.1.0"] +[project.optional-dependencies] +docs = [ + "docutils==0.17.1", # https://jupyterbook.org/en/stable/content/citations.html?highlight=docutils#citations-and-bibliographies + "jupyter-book >=1,<2", +] + +[project.urls] +"Homepage" = "https://github.com/datapartnership/mobilyze" +"Bug Reports" = "https://github.com/datapartnershipank/mobilyze/issues" +"Source" = "https://github.com/datapartnershipank/mobilyze" + +[tool.codespell] +skip = 'docs/_build,docs/bibliography.bib,*.png,*.gz,*.whl' +ignore-regex = '^\s*"image\/png":\s.*' +ignore-words-list = "," + +[tool.hatch.build.targets.wheel] +packages = ["src/*"] + +[tool.hatch.version] +source = "vcs" + +[tool.ruff.lint.pydocstyle] +convention = "numpy" diff --git a/src/mobilyze/__init__.py b/src/mobilyze/__init__.py new file mode 100644 index 0000000..c1f221f --- /dev/null +++ b/src/mobilyze/__init__.py @@ -0,0 +1,7 @@ +from importlib.metadata import version, PackageNotFoundError + +try: + __version__ = version("mobilyze") +except PackageNotFoundError: + # package is not installed + pass