fpsim 0.28.1

用户指南

FPsim被设计为家庭规划研究的一个开源工具。然而，它不是一个万能工具。它旨在回答关于复杂社会和行为系统中新兴动态的复杂问题。它的优势来自于生命周期方法，这允许研究人员检查累加和时效效应如何在女性的生活中展开，以及这些个体层面的变化如何导致宏观层面的结果。

在开始使用FPsim之前，请参考以下指南

• FPsim的效果取决于提供的数据和假设。在使用FPsim之前，请确保您熟悉这两者。

• FPsim 并不能替代高质量的数据。该模型无法告诉您假设方法的需求将如何。

• FPsim 并不能替代描述性统计。在使用 FPsim 之前，评估您的主要研究问题。这些问题可以使用描述性统计来回答吗？

• FPsim 无法预测外生事件。在解释和展示结果时要谨慎。例如，FPsim 无法预测地区冲突或流行病，以及它们对 FP 服务的影响。

仓库结构

结构如下

• FPsim，位于 fpsim 文件夹中，是一个独立的 Python 库，用于执行计划生育分析。

• 在 fpsim 中，locations 文件夹包含所有已校准国家的参数和输入数据。

• 文档位于 docs 文件夹中。

• 示例位于 examples 文件夹中。

• 测试位于 tests 文件夹中。

安装

运行 pip install fpsim 从 PyPI 安装及其依赖项。或者，克隆仓库并运行 pip install -e .（包括最后的点！）

文档

文档可在 https://docs.fpsim.org 查找。

贡献

风格指南

请遵循以下位置的风格指南：https://github.com/amath-idm/styleguide

问题

• 您正在工作的所有内容都必须与一个问题相关联。如果您注意到某些事情需要完成（即使是小事或几乎完成的事情），但没有相关问题，请创建一个问题。这有助于跟踪谁在做什么以及为什么。

• 使用 in progress 标签标记您目前正在处理的问题，以进行跟踪，并避免工作意外重复。

• 优先级高的问题按从上（最紧急）到下（最不紧急）的顺序组织，并可以适当标记为 urgent 或 blocking。如果您正在处理紧急或阻碍其他开发的事情，请为审查设置一个合理的截止日期（可以更新，当然！）

• 海德拉多头效应：通常当您解决一个问题，两个新的问题会出现在其位置。当这种情况发生时，关闭原始问题，并开始新的（相关）问题以进行分类。

• 如果您的問題与两个以上的不同任务相关联，请在文本中包含一个检查表，以便我们跟踪哪些问题的组成部分已解决，哪些需要支持。

• 如果您的問題是一个测试未能捕获的错误，并且包含一个可以严格检查的具体预期值，请包含或请求一个测试补丁，以便测试因错误而失败。

拉取请求

• 所有 PR 都应至少与一个问题相关联。如上所述，如果您正在处理一个 PR，并且没有与之相关的问题，您可以创建一个问题。然而，在这样做之前，请问自己是否真的需要这样做。

• 所有 PR 都应指定另一人进行审查。如果指定给多个人，请使用评论部分指定问题所有者/主要审查员。这里要根据自己的最好判断，因为角色是会变化的，但一般来说

  • @MOBrien-IDM 作为 FPsim 负责人（需要批准才能合并）

  • 您与此问题一对一合作过的任何人

  • @cliffckerr 确保新功能性能与 FPsim 兼容

  • @mzimmermann-IDM 对主题领域专业知识、经济和赋权问题、建模最佳实践问题

  • @avictorious 对历史 FPsim 决策和主题领域专业知识问题

• 尽可能保持 PR 尽可能小：例如，一个问题，一个 PR。小 PR 更容易审查和合并。

• 有时可能会有问题积压，但PR的积压绝不应该太大。（如果你不确定是否要创建PR，先写一个详细的issue。）

  • 如果同时有两个人在处理PR呢？

  • 查看问题优先级。解决更高优先级问题的PR应该先合并。确保在推送你的PR更改之前，在合并之后从新master分支拉取。如果两个问题都是高优先级，那么时间敏感的提交更多的那个应该先合并。如果有疑问，请咨询。

• 如果我们确实有PR的积压，从你当前的PR分支创建一个新的分支，并从这个分支创建一个新的PR是可行的。这些“累积PR”并不理想，但它们比与你自己的merge冲突要好！

• 在开始工作之前，请确保你已经从master分支拉取。如果你在PR上花了几天时间，请确保你定期从master分支拉取。在创建PR之前，确保你的分支与master分支保持最新。

• 请在你准备好后，尽快在一个活跃的分支上创建一个草稿PR。在创建草稿PR时，请尽量大方。这有助于提高透明度，在你遇到问题时可以更快地获得支持。

• 确保你的PR上的测试通过。如果没有，在测试通过之前，将PR标记为草稿。

• 即使你的工作还不适合创建PR，也要定期推送。一个指导原则是每几分钟提交一次，每1-2小时推送到你的分支。

• 每个添加新功能或新功能的PR，如果可以进行硬检查（因此，不包括绘图功能等），都应该包含相应的unittest。

测试

• 开发和调试

  • 开发者负责确保他们开发的新功能的功能性

    • 调试和测试代码是确保功能的核心特性

    • 在活跃开发模式中进行调试时，请确保你的新功能不仅与FPsim的单次运行兼容，而且与多场景兼容

    • 确保新功能在场景中引入新方法时兼容

    • 在开发过程中，使用example_scens.py快速调试你的新功能

• 测试覆盖率

  • 每次添加新功能时，开发者都应该开发一个unittest来检查该功能的基本实现

  • unittest就是一个以“test”开头的函数，尽可能简洁地实现一个功能，并通过断言检查预期的输出

  • 如果你在开始unittest时遇到困难，请随意查看一些示例 这里

  • 一些测试套件 将测试组织到一个具有配置函数（称为setUp()）的类中。在实现此类中的unittest之后，你可能想利用在setUp()中定义的共享资产来最小化你的测试代码行数。

  • 新的unittest应遵循starsim风格指南中规定的风格指南

  • 新的测试应包含一个docstring，详细说明正在测试的内容、如何测试（它与什么进行核对）以及预期值

  • 测试应显示足够的信息的错误消息，以便创建bug报告（摘要、预期值和实际值）

免责声明

本仓库中的代码由IDM和其他合作者共同开发，以支持我们对计划生育的研究。我们已在MIT许可证下将其公开，以便他人更好地了解我们的研究，并为他们的工作提供参考。请注意，FPsim依赖于一些用户安装的Python包，这些包可以通过pip install自动安装。我们不保证代码按预期工作，也不会提供支持、解决发现的问题或接受拉取请求。您可以根据MIT许可证的规定，创建自己的分支并修改代码以适应您的建模需求。有关更多信息，请参阅贡献和行为准则README。