Install and Use COMET
We are still fine-tuning this part. It might not work properly. Let us know if you have any issues
We have designed COMET to be easy to use and install for a wide range of students. If there’s one thing we know about teaching data and econometrics, it’s that everyone finds their own routine and tools that work best for them. We encourage you to explore and try different things - see what works best for you!
- For most students, we recommend using Jupyter Notebooks via a cloud server, called a JupyterHub which is the easiest to use, and the simplest to get started, since you don’t have to install anything. You can find this in Section 1
- If you consider yourself a more advanced user, if you like customization and alternative development environments, or if you have an unreliable internet connection, you may want to install Jupyter locally which can be found in Section 3
- You can also hook-up alternative IDEs, like Visual Studio Code to a local installation
- This is also essential if you want to use STATA in Jupyter notebooks
- If you have experience with R Studio in the past, you can check out our guide in Section 2
If you’re not sure, start with the cloud-based option, then get more sophisticated in the future.
Running via a JupyterHub
The easiest way to load and use these notebooks is via a JupyterHub. This cloud-based server hosts all of the computational resources needed to run the notebooks. Better still, since it runs in the cloud you don’t need to install anything on your computer, and the performance is not affected by your system resources.
- To launch in a cloud environment, select
launch COMET
from the top navigation bar, and then choose your hub. - For UBC students, we recommend JupyterOpen, which is a UBC-supported hub which we maintain, and has all of the necessary packages pre-installed and robust space and processor support. You must have a Campus-Wide Login (CWL) in order to access these resources.
- If JupyterOpen is not working, you can also use PIMS Syzygy (Siz-za-gee). There is a UBC-specific version of this server, and several others that use a Google account or other authentication method.
- Finally, if you are part of the Google ecosystem, you can launch them on Google Collab which has a slightly different appearance but it otherwise the same.
Syzygy and Google Collab are not officially supported UBC software, and may not be privacy-compliant. You should take responsibility for your own use of these resources if you choose to use them. If Google already has all your data, too bad!
Once you are on the server, use the file navigation on the left to find the notebook you are interested in: we recommend starting with intro_jupyter
which is under docs/econ_intro
. Open the folder and click on the .ipynb
file to start the notebook.
Installing Packages
You may at some points need to install some extra packages if you are not working on JupyterOpen. You can do this by opening the server, then clicking on the R Console in the launcher tab.
- Once the console opens, you should see a command line with
R version 4.2.1 (2022-06-23 ucrt)
or something similar. - In the bottom cell window, you should enter:
install.packages(c("tidyverse", "car", "stargazer", "estimatr", "sandwich"))
then hit ctrl-enter
to run the command. It should start installing, and may prompt you to select a CRAN mirror (choose any one near you). Be patient: this might take a while!
You should only have to do this once for each server you work with.
Using with RStudio
If you are using RStudio, you will want to ensure that you use the .Rmd
or .qmd
(R Markdown or Quarto) versions of the notebooks, not the .ipynb
versions. Currently, RStudio does not natively support the Python notebook format.
To install and use with RStudio, follow the steps on the RStudio website.
- Make sure to choose the version of R that matches your processor. You can check your processor as in Section 3.1
Once RStudio is installed, launch the software and then enter:
install.packages(c("tidyverse", "car", "stargazer", "estimatr", "sandwich"))
into the console prompt at the bottom to install the necessary packages.
- Alternatively, you can follow the steps in Section 3 and the choose the R installation which agrees with that version… but then why not use Jupyter? Or install RStudio in
conda
?!
Create a Project
Next, you’ll want to download the files. Select launch COMET
from the top navigation bar, and then click on “launch locally”. This will download a file (main.zip
) to you computer.
- Extract the
.zip
file to a folder on your computer that you can find easily and give it a name (e.g.comet-project
). - In RStudio, go to “File > New Project” then select “Existing Directory”. Browse and select the directory from the previous step.
You’re now ready to go! Use RStudio’s file navigation on the left to find the notebook you are interested in: we recommend starting with intro_jupyter
which is under docs/econ_intro
. Open the folder and click on the .Rmd
or .qmd
file to open the notebook.
Installing Jupyter on Your Own Computer
Some students prefer to run these notebooks locally, on their own computer. This has the advantage of not requiring an internet connection, and avoiding the problems associated with it. However, it has the disadvantage of requiring you to install (and run) the software on your own computer.
If you want to run it locally, you will also need to choose an IDE; we recommend JupyterLab which is easy to use and install.
We strongly recommend that students install the dependencies via an environment manager, but you can skip this step if you know what you’re doing.
Step 1: Install the Environment Manager
Download the most recent version of miniconda
for your computer operating system from:
https://docs.conda.io/en/latest/miniconda.html
The version selection is a little bit different for different operating systems, so click on the appropriate tab below.
It is important to pay attention to the version you download: different processors will require different versions.
- To check your processor, open the Start menu and search “Processor” then click “View Processor Info”
- Under “Device Specifications” look at System Type.
- if this says 64-bit operating system or something like x64-based processor choose the 64-bit version
- if this says 32-bit operating system choose the 32-bit version.
It is important to pay attention to the version you download: different processors will require different versions.
- To check your processor, click on the Apple logo in the top-left of your screen, and select “About This Mac”
- Look for the processor information.
- if this says something like 3.2 GHz Intel Core i5 or something like x64-based processor choose the macOS Intel x86 64-bit version
- if this says something like Apple M1 choose the macOS Apple M1 64-bit version
- We recommend choosing the
.pkg
version of the installer.
Once you have downloaded the installer, run the installer.
- Make sure you choose a sensible installation location; you can ignore any warnings about spaces in names.
- Check the following options, if available:
- Create shortcuts
- Add Miniconda3 to my PATH environment variable
- Register Miniconda3 as my default Python 3.10
- Clear the package cache upon completion.
- Run the installer, which can take a while.
Step 2: Install the Environment
Now that we have our environment manager installed, we need to add in the necessary packages.
This will take a while and requires a stable internet connection; make sure you’re plugged in and not on a bus or something!
To make this easier, we have create an environment file, which contains all of the necessary packages and installation files for miniconda
. Download this file and place it in a directory that you can easily find.
You can find this file here. Right-click, save-as, to download.
Right-click on comet-environment.yml
and write down the file path. You will need this in a moment. Next, launch your system’s command prompt:
- Open the Start Menu and type in
cmd
- Right-click on “Command Prompt” and/or select “Run as Administrator”
- Agree to the warning that pops up, if it does.
- Click the Launchpad icon in the Dock, type
Terminal
in the search field, then click “Terminal”.
If this doesn’t work, open the Finder, then open the /Applications/Utilities
folder, and finally double-click Terminal.
Once your command prompt is running, enter the following command:
-f "MYPATH/comet-environment.yml" conda env create
replacing "MYPATH/
with the file path you noted earlier. Hit enter to run it.
miniconda
will run, and install all of the files. This may take some time, so grab a sandwich, and don’t turn-off your computer.
Step 3: Configure the IRkernel
The last major step is to set up the kernel properly. Enter the following into the command prompt and hit enter:
conda activate comet
Then, type R
. Once R loads, enter the following two commands, hitting enter to run each one:
install.packages('IRkernel')
::installspec() IRkernel
They should complete, and you’re now ready to go. Close the command prompt.
Step 4: Download the Notebooks
Next, you’ll want to download the files. Select launch COMET
from the top navigation bar, and then click on “launch locally”. This will download a file (main.zip
) to you computer.
- Extract the
.zip
file to a folder on your computer that you can find easily and rename it frommain
tocomet-project
. Find the file path of the this directory, and copy it down.
Step 5: Using Jupyter and Creating a Short-Cut
Test your Jupyter installation by opening a new command prompt, then entering the following two commands:
cd FILEPATH
conda activate comet jupyter lab
where FILEPATH
is the directory from Step 4, above.
Your web-brower should launch, and Jupyter should load. You can now load or create a notebook. Use the file navigation on the left to find the notebook you are interested in: we recommend starting with intro_jupyter
which is under docs/econ_intro
. Open the folder and click on the .ipynb
file to start the notebook.
The command window will stay open, and report the server status. Don’t close this window until you’ve saved your work or your JupyterHub will die and you’ll have to re-do everything.
Whenever you want to launch JupyterLab, repeat the two steps above. This can be a little tedious: an alterative is to create a shortcut, which you can do below.
Creating a Shortcut
This is different for other operating systems, so choose the version.
Open notepad
from the Start Menu, and then enter:
-n comet --no-capture-output jupyter lab
@call conda run /K @CMD
Save this file as run_comet.bat
and place it in your comet-project
folder. When you double-click on it, it should immediately launch Jupyter Lab for you in the associated folder.
I haven’t tested this yet! Let me know if it’s busted.
Click the Launchpad icon in the Dock, type TextEdit
in the search field, then click “TextEdit”.
Launch the terminal, and type in nano
to launch the (very old-school) nano text editor. In the editor, enter:
#!/bin/zsh
-n comet --no-capture-output jupyter lab
conda run read
Then save the file by hitting CTRL
and X
on your keyboard together, and type in run_comet.sh
, then hit y
to save. The file should now be saved to your computer as run_comet.sh
. Make sure you place it in the comet-project
folder. There’s one last step: making it executable.
In your Terminal then enter:
cd FILEPATH
where FILEPATH
is the location of your run_comet.sh
script. Then, enter:
.sh chmod 755 run_comet
Finally, to make it run on your computer:
- find the file in your Finder, and right-click, and select “Open with…” and select “Other…”.
- toggle the dropdown to “All Applications” from “Recommended Applications”
- under “Utilities” select Terminal
- check the “always use this application” box, and hit OK.
You should now be able to double-click the shortcut to launch Jupyter on your computer!
All done! No more command line stuff, hopefully!
Installing for Development
So, you want to develop and submit new material to COMET? Awesome! There are a couple of extra things you will need to do in order to make this work.
- First, identify which IDE you want to use and install it. I recommend RStudio (for
.qmd
files) or VSCode (for.ipynb
and.qmd
), or JupyterLab (for.ipynb
)
- If you are using RStudio, follow the instructions in Section 2 up to the point of downloading the project. You will also need to install one of the other tools to develop
.ipynb
notebooks. - If you are using VSCode, you will need to install R (see Section 2) and then VSCode for your operating system
- If you are using Jupyterlab, follow the instructions in Section 3 up to Step 4. Come back and do Step 5 later, after your development environment is set up. You will also need to install one of the other tools to develop
.qmd
notebooks.
- Second, download and install Git for your operating system. If you are developing on the Github version, it’s also worthwhile to install GitHub Desktop for your operating system after you install Git
- Finally, install Quarto. Follow the steps to integrate with RStudio or VSCode.
Now, use Git or Github desktop to download the repository from our repository and get working.