Skip to content

Latest commit

 

History

History
79 lines (64 loc) · 5.21 KB

CONTRIBUTING.md

File metadata and controls

79 lines (64 loc) · 5.21 KB
Raw

Contributing to medaCy

MedaCy seeks to create a unified platform to streamline research efforts in medical text mining while also providing an interface to easily apply models to real world problems. Due to this, contributions to medaCy are often consequences and direct by-products of active research projects. However, if not for the contributions, bug fixes/reports, and suggestions of practioners - medaCy could not grow and thrive.

This contribution guide is designed to inform:

  1. Researchers in how they can efficiently utilize medaCy to make their work more reachable by practioners.
  2. Practioners in how they can tune medaCy's cutting-edge functionalities to their specific application.

Table of contents

  1. Issues and Bug Reports
  2. Development Set-up
  3. Running Unit Tests

Issues And Bug Reports

Please do a search before posting an issue/bug report - your problem may already be solved! If your search comes up for not - congratulations, you may have something to contribute!

Development Environment Setup

At it's most basic one can fork medaCy, clone down their fork, and use their favorite text editor to develop. However, some up-front set-up effort goes a long way towards streamlining the contribution process and keeping organized. This section details a suggested set-up for efficient development, testing, and experimentation with medaCy utilizing PyCharm.

Assumptions of this section:

  • You are working in a UNIX based operating system.
  • Part 2 assumes you have Pycharm Professional installed - Pycharm Professional is provided with the Jetbrains University License. (this isn't entirely necessary but the useful Remote Host feature is disabled on the Community Edition)

Part 1: Development Installation

  1. If you are shaky with git - this link provides an excellent description of the branching model medaCy follows to organize contributions.
  2. Fork medaCy and copy the clone link.
  3. On your machine, insure you have Python 3 installed. Set-up a virtual environment and activate it.
  4. Run the bash commands: python --version and pip list. Upgrade pip to the latest version as suggested. Your python version should be above 3.4 and your installed packages should be few in number - if both of these conditions do not hold return to Step 3.
  5. In a directory separate from the one created by the virtual envirorment set-up command, clone down your fork of medaCy.
  6. Whilst inside your cloned fork, insure you are in at-least the development branch or a branch of the development branch. This can be verified by running git status and branching can be done with git checkout <branch-name>
  7. Run pip install -e . This will install medaCy in editable mode inside of your virtual environment and will take several minutes to install dependencies - medaCy stands on the shoulders of giants! Errors one is likely to encounter here include the installation of sci-py and numpy. Google search the errors as they are easily fixable via the installation of some extra dependencies. Likely, your python installation is missing C headers required by scipy.

Part 2: Developing with PyCharm PyCharm can streamline development efforts - especially if you are developing locally and running medaCy on a remote machine for model building.

Part 3: Logging

MedaCy uses the logging module to allow users insight into how medaCy is handling their data. Insure you are logging critical steps in any functionality you implement at the appropriate logging levels to make it easy for users to debug.

Running Unit Tests

All components of medaCy have associated unit tests. Please insure these all pass before submitting pull requests. When medaCy runs unit tests, it first automatically installs the END dataset then uses it to test various functionalities of the package. Some tests involve building a model over the dataset - these may take some time to complete.

After installing medaCy for development, make sure that pytest is installed. Then:

  1. For quick testing of the whole framework, run:
    python setup.py test.

  2. For more fine-grained testing on individual files with colorful log output run:
    pytest -s tests/tools/test_data_manager.py -o log_cli=True --log-cli-level=INFO.

    This will show log output during tests and allow you to adust logging level for the test file being run. Read the pytest documentation for details.

Note that some of the unit tests require knowledge about the configuration of your machine, and that those tests will be skipped if those configuration settings are not specified in the config.json file. These settings include the location of a MetaMap binary file on your machine, which GPU core to use for certain tests, and the location of a word embeddings file. It may be that your contributions will not affect functionality that depend on these features, however, all pull requests will be tested against the full unit test suite.