Project management

Project management

"Learning about the importance and benefits of project management adhering to community standards to achieve shareable science."

Information

The estimated time to complete this training module is 4h.

The prerequisites to take this module are:

If you have any questions regarding the module content please ask them in the relevant module channel on the school Discord server. If you do not have access to the server and would like to join, please send us an email at school.brainhack [at] gmail [dot] com

Resources

This module was presented by Elizabeth Dupre during the QLSC 612 course in 2020, with content adapted from presentations by Chris Gorgolewski.

The slides are available here.

The video of her presentation is available below:

Exercise

Your understanding of project management

Prepare your answers in an online document (e.g. using hackmd.io).

  • Let’s pick a license…
    • you want to share code and make sure it can be used as widely as possible, but you still get credited. Which license do you pick and why?
    • you want to share data, get credited, allow for modifications but not commercial usage. Which license do you pick and why?
  • Pick a public dataset and explain if it is FAIR. You can pick from the list below if you need inspiration.
  • Find an example of a neuroimaging paper described on the open science framework (or somewhere else), with 1. Code available? 2. Documentation for data analysis available? 3. Data available? For each aspect, summarize briefly the standards followed (if any).

Create a project template for your Brainhack School project

We have learned about the community standard of data sharing in the previous exercise and how that improves communication and collaboration with researchers. The same principle can be applied to your analysis code. Using a consistent project template will help when your project grow in the long run. For this section, please prepare your answer as a GitHub repository. We will follow the first lesson Set up your project in the Good Research Code Handbook

📝 Please skip the Install a project package section. We recommend to revisit this part after completing the python packaging module.

The end result will be a logically organized project skeleton that’s synced to version control. The instructor should be able to verify your progress through 1. a public GitHub repository and 2. clone and test your project on their own machine.

  • Pick a short and descriptive name for your project….

    • Create a folder in your home directory.
    • You should have created a GitHub account when you completed the installation module. Now we want to create a GitHub repository of the same name, for convenience.
    • Now you should see some suggestions on the GitHub page to help you initialise the project repository. Which one should you use?

  • The next step is to create a virtual environment and an associated file describing the environment, so you can reinstall everything if you need to start fresh.

    • Create a conda environment of the same name of your project.
    • Activate this environment and install the same packages you did in the installation module.
    • Export this environment and save it as a file named environment.yml at the root of your project repository.
    • Now commit and push this environment file to your GitHub repository.

  • Next, let’s create a .gitignore file with the help of GitHub magic.

    • On your GitHub repository page, click on Add file - create new file.
    • Now enter .gitignore into the file name. You will see a drop down menu appear on the right hand side.
    • Pick the python template. Commit this file.
    • Now use the terminal and pull this change to your local directory.

    💡 With the same principle, you can also create a LICENSE file through GitHub.

  • Next we will populate the directory with a project skeleton and some basic descriptions.

    • Create the directories described in the lesson with command mkdir.
    • Try to add these changes to git. You should notice empty directories are not added, this is because git will only push files.
    • To work around this issue, let’s create a file named .gitkeep in each of the empty directory using command touch.
    • Now try to add and commit these files again.

  • (Optional) Creating a project package Creating a project package can be difficult for the first time, but the pay off is substantial: your project structure will be clean, you won’t need to change Python’s path, and your project will be pip installable. This is the standard approach in the data science world. This is a minimal demo for a installable package. We encourage you to revisit Install a project package after completing the python packaging module.

    • Create a file under src/ named helloworld.py, with one line print('hello world').
    • Create a file under src/ named __init__.py.
    • Create a setup.py file in the root directory with the following lines:
      from setuptools import find_packages, setup

setup(
    name='src',
    packages=find_packages(),
)
    • Finally, activate the project virtual environment you created earlier. Install your package:
      pip install -e .
    • To verify the completion of this part, you should be able to run the following code from a python kernel as long as the virtual environment is activated:
      import src.helloworld
>>> hello world

  • Follow up with your local TA(s) to validate you completed the exercise correctly.

  • 🎉 🎉 🎉 you completed this training module! 🎉 🎉 🎉

More resources

If you are curious to learn more about BIDS, check the BIDS specifications. There will also be a training module on BIDS in week 2. We encourage you to revisit Install a project package after completing the python packaging module.

Some documentation on standards for project organization:

Check out this repository which follows the principle of the project set up in the Good Research Code Handbook.

Finally, a blog post on choosing a license for open science projects by Titus Brown.