Skip to content

Latest commit

 

History

History
73 lines (38 loc) · 4.53 KB

how-to-run.md

File metadata and controls

73 lines (38 loc) · 4.53 KB

How to run analysis

It is expected that you are familiar with Jupyter notebooks. (Expected knoweldge: What a cell is, how to see the output of your cell's execution)

If not, please read sections "Starting the Jupyter Notebook Server", "Creating a Notebook", "Naming", and "Running Cells" from this brief explanation, which can be found from the table of contents from the above linked external page.

  1. Open up a terminal window, and navigate to src/notebooks in a clone of this GCGC tool.

terminal window in correct directory

  1. Run the terminal command jupyter notebook under src/notebooks. This will begin a python3 kernel for the notebook. It will also open a web page in your default browser. The terminal output should be similar to this one below after a successful launch of the notebook kernel:

Opening notebook using terminal

  1. Open the GCGC.ipynb notebook in the web page that opened as a result of running the above command.

Warning: Changing any data within the notebook will require you to re-downloaded the original if you want to start fresh. It is suggested you make a copy of the original notebook locally.

Opening jupyter notebooks tree

  1. If this is your first time using the notebook, it is recommended you follow the remaining steps with the provided example files before using your own log files. Otherwise, set the following two variables in the first code cell, as seen below:

    • filepaths : a list of log files to be analyzed
    • labels : describe the log files listed above.
    • zero_times : If true, all logs analyzed will have the same start time. Otherwise, all times will be plotted exactly as they appear in the first time metric in the gc log file.

In the example below, you can see filepaths to sample data, with labels describing the log files.

Setting the state variables

Note: The notebook allows for using unix style wildcards to capture multiple log files in the same directory, that are all associated with a single run. Using this wildcard will group all captured files into 1 event log, and requires 1 label.

  1. Run all cells. In the web based Jupyter notebooks, press Cell from the top menu, and select Run All.

  1. After pressing run all, the GCGC notebook analysis will be generated. The plots will generate one by one starting from the top of the notebook. Each plot takes a few seconds to generate, and may take longer for larger source log files. While cells are running, your screen may jump first to the bottom of the notebook, or to the cell that is executing, or jump around seemingly randomly. This behavior is expected, and will not persist after analysis is complete.

After running notebook cells

Notice, your cell's output has automatically been plotted inline. Wait for the full notebook analysis to finish, then analyze your results.

Warning: An Error caused by a plot will prevent the following cells from executing. Here is an example of an error message. If you find an error, such as this one caused by failing to put the correct number of labels for the provided files, try to resolve the error by reading all output messages from the top of the file downwards first. For this particular example, you would have found a cell outputting the message "Error: Labels do not have same length as collected data" in a cell above the runtime error.

Example error message
  1. Wait for all cells to finish running.

Cell currently running

A cell that is running will have the term In [ * ] :

A cell that is finished running will have In [ n ] :, meaning that the cell was the n-th cell to be run.

  1. Now that the plots have been generated, scroll through the Jupyter to see the analysis. It is possible to download the notebook to be shared in different formats, as seen below:

download analysis

Feel free to change any parameter and re-run analysis as needed.