Analysis Repositories

Each member of the MOAD group has an analysis repository. This section is about creating and using your personal analysis repository.

We each have an analysis repository so that we have a default place to store, version control, and share work, mostly in the form of Jupyter Notebooks. In time you will work in other repositories, and create your own repositories for papers, course work, etc., but having a default place to do work helps keep things organized, and helps other people find your work when you graduate and move on from MOAD to other adventures. Most of the links you see people sharing on the weekly meeting whiteboard are to notebooks in their analysis repositories that they have pushed to GitHub.

Our conventions are:

  1. Analysis repositories are called analysis-firstname; e.g. analysis-susan

  2. Analysis repositories are public so that other researchers in the group, and outside of it can see the code and visualizations that you are creating, and learn from them

Create Your Analysis Repository

The steps to create your own analysis repository are:

  1. Create an empty public repository on GitHub and clone it to your laptop or MOAD workstation

  2. Use the MOAD analysis repository cookiecutter to generate the directory structure and initial files for your repository

  3. Commit and push the initial files to GitHub

Create Your Analysis Repository on GitHub

  1. In your browser, go to the SalishSeaCast GitHub organization page, and use the green New button to start creating your analysis repository.

  2. Make sure the Owner selection box on the Create a new repository page shows the SalishSeaCast organization.

  3. Type analysis-yourfirstname into the the Repository name text box; for example analysis-casey.

  4. Ensure the button to make your new repository Public is set.

  5. Click the green Create repository button at the bottom of the page.

  6. Keep the browser tab open because you are going to need information from it shortly.

Clone Your Analysis Repository

Note

This section assumes that you have already followed that steps in the Secure Remote Access section to Generate ssh Keys, and to Copy Your Public ssh Key to GitHub.

  1. Create a top level directory for MOAD work. On your laptop do:

    $ mkdir -p $HOME/MOAD
    

    On a Waterhole workstation do:

    $ mkdir -p /ocean/$USER/MOAD
    

    The -p option tell mkdir to not show an error message if the directory already exists, and to create any necessary parent directories as needed.

    $HOME expands to your home directory.

    $USER expands to your user name.

  2. Go back to the browser tab in which you created your analysis repository on GitHub and find the section of the page near the top that says “Quick setup — if you’ve done this kind of thing before”. Below that there are 2 buttons that say HTTPS and SSH. Please ensure that the SSH button is enabled, and copy the repository URI string of text beside it that looks like:

    git@github.com:SalishSeaCast/analysis-casey.git
    
  3. Use that repository URI string to clone your analysis repository from GitHub. On your laptop do:

    $ cd $HOME/MOAD
    $ git clone git@github.com:SalishSeaCast/analysis-casey.git
    

    On a Waterhole workstation do:

    $ cd /ocean/$USER/MOAD
    $ git clone git@github.com:SalishSeaCast/analysis-casey.git
    

Populate Your Analysis Repository

Note

This section assumes that you have installed Miniconda or the Anaconda Python distribution on your laptop.

It also assumes that you have set up your Git Configuration.

  1. Create a conda environment with the latest version of Python and the cookiecutter tool installed in it with the command:

    $ conda create -n cookiecutter -c conda-forge python=3 cookiecutter
    

    That command will do some process and then show you a list of packages that will be downloaded and installed, and ask you if it is okay to proceed; hit y or Enter to go ahead.

    After some more processing you should see the messages:

    Preparing transaction: done
    Verifying transaction: done
    Executing transaction: done
    #
    # To activate this environment, use
    #
    #     $ conda activate cookiecutter
    #
    # To deactivate an active environment, use
    #
    #     $ conda deactivate
    
  2. Activate your cookiecutter environment, go to your MOAD/ directory, and populate your empty analysis repository clone with the commands:

    $ conda activate cookiecutter
    (cookiecutter)$ cd $HOME/MOAD/
    (cookiecutter)$ cookiecutter -f gh:UBC-MOAD/cookiecutter-analysis-repo
    

    This command uses our analysis repository cookiecutter template repository to create directories and files in the empyt analysis repository that you cloned earlier. The -f option lets the cookiecutter tool write directories and files into an already existing directory.

    cookiecutter will ask you for 3 pieces of input:

    researcher_name [Casey Lawrence]:
    Select github_org:
    1 - SalishSeaCast
    2 - UBC-MOAD
    3 - SS-Atlantis
    Choose from 1, 2, 3 [1]:
    

    Type your name in at the researcher_name prompt, and accept the defaults for the other two because they should match what you did earlier.

  3. Deactivate your cookiecutter environment with:

    (cookiecutter)$ conda deactivate
    
  4. Go into your new analysis repository, add and commit the files that cookiecutter created for you, and push them to GitHub:

    $ cd $HOME/MOAD/analysis-casey
    $ git add .gitignore LICENSE README.rst notebooks/
    $ git commit -m "Initialize repo from MOAD cookiecutter"
    $ git push