MacOS Installation Guide - JSuryatenggara/ChIP-AP GitHub Wiki

ChIP-AP Setup Guide for MacOS v1

This installation guide was performed on MacOS Catalina (10.15.7) but should be compatible with all versions 10.15 (Catalina) and later. Please note you will need administrator installation access for this installation, there is no way around that for macOS installations unfortunately. If this is your personal computer/laptop, this is just the password you use for any installation/login as normal. In the following tutorial, we will ignore any steps where you are asked for your password (as it may/will appear multiple times), when it does appear just enter the password and continue with the remainder of the instructions.

ChIP-AP works on Mac computers with Intel processors as well as Apple-Silicon processors (such as the M1 or later).

To make sure you’re Mac has the right processor, go to the Apple menu in the top left (a), click “About This Mac” (b) and then check that you have an “Intel” processor (c).

Newer versions of MacOS have updated security to restrict you installing software from anywhere other than the AppStore – because Apple is the gatekeeper of course. So, you may need to turn this restriction off before proceeding in the installation. To do this, go to the Apple menu in the top left (a), click “System Preferences” (b), “Security and Privacy” (c).

Next, go to “General” (a), then make sure that you can make changes by ensuring the lock is open (b), then finally click Allow apps downloaded from “App Store and identified developers” (c).

Now you can proceed with the installation and should be ok.

A reminder about the installation requirements. In terms of storage space, the installation of ChIP-AP and all its required generated genome files etc... will take up ~50-60Gb alone – this is NOT including any of your chip or analysis files. So, make sure you set up this on a drive/computer with enough storage space to accommodate these heavy requirements. Off-loading some of the installation directories to an external drive for example is possible (using hard/symbolic links) but is an advanced topic and is beyond the scope of this tutorial. Again, google is your friend here.

Prerequisite Installation

Before installing ChIP-AP, you need to make sure that Anaconda 3 is installed. There are thorough guides online but we will cover the basic steps here.

  1. Firstly, in your web-browser of choice, search for “anaconda3 individual install”

  1. Download (a) the right installer for your system (should be a 64-bit Graphical Installer [go command line installer if you’re feeling gung-ho!]) (b) and save it in your Downloads folder (c). When the download completes, you can press the magnifying glass icon to be taken to where the installer was downloaded (d)

  1. Next, double click on the installer package to start it

  1. At the first window, click “Continue” on the first sheet

  1. Click “Continue” again

  1. Accept the license and End User agreements and click “Continue”

  1. Agree to the agreement

  1. Next click “Install.” If you are more familiar with setting up Anaconda you can change the installation location, or if you want to install it to an external drive if your built-in storage isn’t large enough, then do so as required for your system.

  1. Once complete, you will be asked about the PyCharm IDE environment as well – click “Continue”

  1. On the next window, click “Close”

  1. Great! Anaconda 3 is now installed. If you are asked to move the installer to the bin, do so since you will no longer need it, this is only done on some versions of Safari so if you’re not asked about it don’t worry.

    If you installed Anaconda from the command line you must choose “yes” to initialize anaconda and then close the Terminal entirely and reopen it before proceeding. If you don’t you the remaining installation steps will fail to complete properly.

  1. The next thing we need to make sure to install is Java since some newer versions of macOS don’t come with it pre-installed – thanks Apple!!! Ok so you need to go to (Java SE Development Kit 16 - Downloads (oracle.com)) and download the macOS Installer (a), accept the license terms (b), download it (c), and allow downloads (e)

    Next, start the downloaded package by double-clicking on it.

    Run through the installer process accepting all defaults unless you know how to configure the installer yourself. Enter the password when prompted to. You can delete the installer when complete as its no longer needed.

Setting up ChIP-AP

Now down to the “meat” of the installation! Actually, when we first started writing we thought ”pffttt it works fine in Linux, macOS is Unix it’ll be a breeze to adapt....” Oh boy were we wrong!!! OK let's start...

  1. To start, we recommend you create a sub-folder in your “Documents” directory named “tools”

  1. Within the “tools” folder, create a sub-folder named “chip_ap.” Notice the underscore here rather than dash, this is to simplify a number of steps unbeknownst to you later

  1. Download the latest version of ChIP-AP from our github page (https://github.com/JSuryatenggara/ChIP-AP) and place it in the “chip_ap” folder.

    Also, download the pre-configured genome folders required for ChIP-AP from (https://www.dropbox.com/s/ioqd3hwdahh9xon/genomes.zip) and place in the same folder. Once everything is unzipped, make sure the “chip_ap” folder structure looks as follows:

  1. Next, you need to go up 1 folder

    Next, right mouse click on the “chip_ap” folder and the last item in the pop-up menu will be “New Terminal at Folder”

    This will bring up the terminal window we now need to complete the installation

  1. At the terminal, type the following command and press ENTER

  1. As part of the installation process, ChIP-AP will ask a couple of questions

    The first question asked is whether you want to install ChIP-AP in its own environment. This is so ChIP-AP will sit in its own contained “capsule” and won’t be affected by other installed programs and so this will ensure that all the dependencies of ChIP-AP will be correct and met all the time. So, we highly recommend this option

    If you answer “n”, then ChIP-AP will be installed in the base environment along with its dependencies.

    If you answer “y”, you will be asked to name the environment and then press ENTER. A confirmation statement will be printed for you to confirm with an additional ENTER press. If doing this, make sure to remember the name of the environment you entered as its very important!

  1. Once you press ENTER, you will be asked to enter your password for the next installation step. When you start typing your password NOTHING will appear. The text entry is still working but it wont show you any character entered for security reasons. So, make sure you type in your password correctly since you can’t see what you’re doing. When entered press ENTER to continue.

  1. You will be then asked to confirm all details with an ENTER press on the keyboard.

    The installation will now start and will take a while to run as a lot of packages will need to be installed, so this is highly dependent on your internet and cpu speeds as to how long it will take. Take note of the environment name you set. For now, go take a break but remember, no eating in the lab!!

  1. Once the installation completes close the terminal entirely and open up a new terminal window by searching for it in spotlight (a), and typing in “terminal” (b), and selecting it in the results window (c)

  1. Depending on your proficiency, there are 3 ways to use ChIP-AP. If you setup ChIP-AP in an environment in step 6, once you open the terminal, you will need to type the following command (below) where xxxx is the name of the environment as you defined in step 6 before running ChIP-AP EVERYTIME. Otherwise, this command isn’t necessary.

    • To use ChIP-AP using the command line, refer to the documentation on our github (xxx) for full details on how to setup a run with appropriate flags/parameters (For advanced/proficient users).

    • For most non-bioinformatician users of ChIP-AP, we recommend using the wizard. To use this, at the opened terminal command line type:

      ... and the first window of the wizard will appear (below). If running ChIP-AP for the first time, it may take 1-2 minutes for the first window to appear as the pipeline checks for any missing dependencies and installs them in the background, so be patient till everything appears. There will be a message printed to the command line if this is the case if you notice it, otherwise just wait for the initial check to complete. This delay will only be for the first time running either the dashboard or the wizard though.

      Once the wizard appears, the wizard will ask you questions sequentially to acquire all the data it needs for a successful run. Below also is a snapshot of the windows you will see throughout the wizard process.

    • For users who are more experienced with ChIP-AP, we recommend using the dashboard. At the command line, simply type:

      ... and the dashboard will appear (below) wherein you can fill in all required information.

      NOTE: For you to use the dashboard you need to have a minimum screen resolution of at least 1920x1080. If it is less than this, then all the dashboard elements will not appear on the screen and hence will be unusable. So either use an external monitor with a resolution of 1920x1080 or larger, or the wizard.

  1. Once the run is complete, please refer to our github wiki for the tutorial on navigating and interpreting the results.

Subsequent Running of ChIP-AP

OK so now that everything is set up to run ChIP-AP each time is relatively simple. Open a new terminal window...

If you setup ChIP-AP in its own environment then you need to write the following command first:

where xxxxx is the name of the environment you created in the installation.

The next command you need to write at the command line will start chipap depending on what mode you want:

NOTE: For you to use the dashboard you need to have a minimum screen resolution of at least 1920x1080. If it is less than this, then all the dashboard elements will not appear on the screen and hence will be unusable. So either use an external monitor with a resolution of 1920x1080 or larger, or the wizard.

Installation Troubleshooting

So MacOS seems to be picky with a number of things and this is getting worse with each new version of macOS released. Despite out best efforts to streamline the installation process, depending on your systems configuration and previous installations there may be issues. We will keep updating this list as we come across issues users are coming across.

  1. ChIP-AP fails to load with a “pandas not found” error or similar message.

    We have specifically told macOS to install this but for some reason it sometimes doesn’t register. So try re-running again and it should work. In our experiences if it complains, an immediate re-run will work fine.