You want to help? Woohoo! We welcome that and are willing to help newbies get started.
Please see our contribution guidelines for instructions on setting up your development environment
- Identify an issue that suits your skill level
- Only look for issues in the Backlog category
- If you're new to open source, please look for issues with the
bug low
,help wanted
, ordocs
tags - Please reach out with questions on details and where to start
- Create a topic branch to work in; here are instructions
- Create a throwaway file on the Desktop (or somewhere outside the repo), based on an example
- Make changes and use the throwaway file to validate that your packages changes work
- Make small commits after getting a small piece working
- Push often so your changes are backed up. See this for more details.
- Early on, create a pull request such that Levi and team can discuss the changes that you're making. Conversation is good.
- When you have resolved the issue you chose, do the following:
- Check that the unit tests are passing
- Check that pyflakes and pylint don't show any issues
- Merge the master branch into your topic branch (so that you have the latest changes from master)
git checkout LeviBugFix git fetch git merge --no-ff origin/master
- Again, check that the unit tests are passing
- Now that your changes are working, communicate that to Levi in the pull request, such that he knows to do the code review associated with the PR. Please don't do tons of work and then start a PR. Early is good.
- Download and install git for Windows
- Choose "64-bit Git for Windows Setup" (assuming you're on modern hardware)
- On the Select Components screen, accept the defaults
- After selecting install location, choose "Use Git from the Windows Command Prompt"
- Checkout using Windows-style
- Choose MinTTy
see macOS instructions for macOS and
- Download Anaconda for Windows (Python 3.5)
There are a number of ways to install python 3.5 on macOS. Here are a few different ways:
- If you already have homebrew, (a package manager for macOS), you can simply run
brew install python3
- You can also install with the excellent Anaconda distribution
- You can also follow the Hitchhiker's Guide to Python instructions if you prefer a more hands-on approach.
- Use your package manager (apt-get, yum, etc), for example
sudo apt-get install python3
- Open the terminal (i.e., git bash, if using Windows)
- run
conda install pyodbc
Install directly from our repo
- run
pip install https://github.com/HealthCatalyst/healthcareai-py/zipball/master
- Fork this repo (look for the link in the top right corner of the current page)
- At the top of the repo homepage click the green 'Clone or download' button and copy the https link
- In your terminal run
git clone <PASTE THE LINK HERE>
cd
healthcareai-py directory
If you like using virtual environments (not required):
- In terminal, run
conda env create
to create the hcconda virtual environment - To activate your virtual environment, in terminal run
activate hcconda
(orsource activate hcconda
if using bash) - You might have to update packages, especially sklearn. The best way to do this is through Settings->Project->Project Interpreter and update scikit-learn
- Install PyCharm Community Edition
- Set path to git.exe via File -> settings -> Version Control -> Git
- Clone repo (if you haven't) via PyCharm -> VCS (at top) -> Checkout from version control -> Github
- Grab .git url from healthcareai-py repo in Github
- File -> Open and look for the healthcareai project (if it didn’t come up already)
Note that there are only a few true integration tests that use MSSQL server as a destination. If you are not interested in running these few tests, feel free to skip this section.
If on Windows, install both Server Express and SSMS Express
- Navigate to the downloads page
- Look for and download ENU\x64\SQLEXPRWT_x64_ENU.exe
- When installing, be sure to check the box to install SSMS
- Create tables on localhost
Note that these will go in the SAM database, if using the Health Catalyst analytics environment
```sql
CREATE TABLE [SAM].[dbo].[HCAIPredictionClassificationBASE] (
[BindingID] [int] ,
[BindingNM] [varchar] (255),
[LastLoadDTS] [datetime2] (7),
[PatientEncounterID] [decimal] (38, 0),
[PredictedProbNBR] [decimal] (38, 2),
[Factor1TXT] [varchar] (255),
[Factor2TXT] [varchar] (255),
[Factor3TXT] [varchar] (255))
CREATE TABLE [SAM].[dbo].[HCAIPredictionRegressionBASE] (
[BindingID] [int],
[BindingNM] [varchar] (255),
[LastLoadDTS] [datetime2] (7),
[PatientEncounterID] [decimal] (38, 0),
[PredictedValueNBR] [decimal] (38, 2),
[Factor1TXT] [varchar] (255),
[Factor2TXT] [varchar] (255),
[Factor3TXT] [varchar] (255))
```
You will need to have an alias called "localhost" that points to your SQL database.
- Open SQL Server Configuration Manager
- On the left pane, expand SQL Native Client 11.0 Configuration and right click Aliases. Select New Alias.
- In the pop up dialog box, enter the following and then press OK:
- Alias Name: localhost
- Port No: 1433
- Protocol: TCP/IP
- Server: YOUR_COMPUTER_NAME (this should be something like HC2080, if you can connect to HC2080 in SSMS)
- On the left pane, expand SQL Server Network Configuration and click on Protocols for SQLEXPRESS.
- Right click on TCP/IP and click Properties. In the dialog box, enter the following and then press OK:
- Under the Protocol tab, verify that Enabled is set to Yes.
- Under the IP Addresses tab, scroll all the way to the bottom.
- Under IPALL, TCP Dynamic Ports should be blank
- Under IPALL, TCP Port should be set to 1433
- Right click on TCP/IP and click Properties. In the dialog box, enter the following and then press OK:
- Working in Configuration Manager,
- Expand SQL Server Services
- Right-click on your SQL Server instance
- Restart SQL Server
- Open SSMS and verify that you can connect to the server
localhost
.
- Right click on tests folder under healthcareai-py/healthcareai
- Click on Run Nosetest in test
- Note the text ‘Git: master’ in bottom-right of PyCharm
- Create new test branch via VCS -> Git -> Branches -> New Branch
- Push branch to github (ie, create origin) via VCS -> Git -> Push (CTRL-SHIFT-K)
- Install the following packages via the command line:
python -m pip install packagename
- pylint
- pyflakes
- Set these up via http://www.mantidproject.org/How_to_run_Pylint#PyCharm_-_JetBrains
- If your python is installed in
C:\Pythonxx
, then your parameters will be: - Program:
C:\Python34\Scripts\pylint.exe
- Parameters:
$FilePath$
- Working dir:
C:\Python34\Scripts
- If you are using a different Python distribution, you may need to find where Pylint is installed. For example, the same three parameters from above might be:
C:\Users\user.name\AppData\Local\Continuum\Anaconda3\Scripts\pylint
- Parameters:
$FilePath$
C:\Users\user.name\AppData\Local\Continuum\Anaconda3\Scripts
- Instead of using default parameter, use
$FilePath$
- For Anaconda, you may have to use
C:\Users\user.name\AppData\Local\Continuum\Anaconda3\Scripts\pylint
- Check all boxes
- Make sure pylint and pyflakes work
- Right-click on relevant directory in PyCharm (this will be where you’ve done work)
- Navigate to external tools
- Run both pylint and pyflakes
- Verify that there aren’t any issues with your code; please do this before sending pull requests
- Set maximum line width to 79 via Settings -> Editor -> Code Style -> Right margin
- Set tabs as spaces via Edit -> Convert Indents -> To Spaces
- Click Code -> Inspect code -> Whole project -> Look for section on Package requirements
- Under the lines related to sklearn, click ‘Ignore Requirement’
Set up your email and username for git (otherwise no attribution in github)
- Open a terminal (ie, git bash, if on Windows)
- Set up your email and user name for proper attribution
git config user.name "Billy Everyteen"
git config --global user.email "[email protected]"
- Configure line endings for windows:
git config core.autocrlf true
- Make git case sensitive for file names:
git config core.ignorecase false
- Improve merge conflict resolution via
git config --global merge.conflictstyle diff3
- If you use a personal email for github, and would rather have notifications go to your Health Cataylst email
- See GitHub Notification Settings -> Notification email -> Custom routing
- Set up SSH (if desired) so you can push to topic branch without password
- Open the terminal (whether in Git Bash, in Spyder, etc)
- Type
git checkout -b nameofbranch
- This creates the your local branch for work
- Note this branch should have your name in it
- Type
git push origin nameofbranch
- This pushes the branch to github (and now it's backed-up)
When your dev environment is set up, see the contribution workflow.