I’m Blake. I write about probability, stochastic processes, Python tooling, and the practical side of building things with code. More about me →

  • Finding Git branches faster with FZF

    One of my favourite CLI tools is FZF by junegunn. When you pipe a list of entries to it, it brings up a TUI that allows you to fuzzy match entries from that list

    I only need to type a few characters to select an element from a large list!

    One common problem I encounter is sorting through all of my branches on a git repository. Especially in repositories where your branches need to conform to a long template.

    For example, checking out the repository Marimo, there’s many branches:

    git branch --all | wc -l
    # 162

    So I’ve add this alias to my ~/.gitconfig:

    [alias]
        co = "!git checkout $(git branch --format '%(refname:short)' | fzf)"

    So when I execute git co, fzf allows me to select a branch with a fuzzy match, then the alias will check it out!

    To install FZF, you can use Homebrew:

    brew install fzf

    Check out their Readme for more details for configuration, adding shell shortcuts, the syntax for different types of searches.

  • A Practical MacOS Terminal Setup for Data Scientists

    I spend most of my time in the terminal these days, but it wasn’t always that way. I first got comfortable with the command line while working with Ubuntu during my Master’s degree. Later, during an internship at Exeter, I noticed my supervisor did nearly everything in the terminal — navigating files, mounting and unmounting USB drives, monitoring resources, managing environments, running scripts. It seemed like a good idea to pick it up, since the command line is everywhere and gives you far more control and flexibility than clicking through menus. I was slow to start — but that turned out to be an advantage. The command line grows with you, and there’s always a next step when you’re ready.

    These days, whether I’m managing Python environments, installing tools, or automating tasks, I do it in the terminal — and that’s what this guide is here to help with.

    However, the terminal is not without its sharp edges — it can be pretty unintuitive at first. So here’s a collection of notes I’ve collected recently about setting up a good terminal environment on MacOS so that it’s a more pleasant experience so getting the practice you need is easier

    This guide is for data scientists and Python programmers using macOS 14 or later. I’m assuming you’re already comfortable with coding in VSCode, and that you’re curious about making the terminal a more productive space — no Vim rants here (this time).

    Shell startup

    When you open a new terminal session and initiate a new shell session such as zsh, the file ~/.zshrc automatically executes before giving you control of an interactive shell so that you can start each session with a set of user-defined defaults. All of our shell configuration will go in here.

    There is also ~/.zprofile, which automatically executes for “login shells” (like when you login to the shell from another machine). We wont worry about the details much here, we’ll stay focussed on ~/.zshrc for this article

    Understanding and Updating Your PATH for adding commands

    The PATH environment variable tells your Mac where to look for programs when you type a command in the terminal. It’s a list of folders, separated by colons, that the system searches in order. For example, when you type python, MacOS checks each folder in PATH to find the python executable. Why does it matter?

    If you install a tool (like Python, Node, or a custom script) and its command isn’t found, it’s likely because its folder isn’t in your PATH. Updating PATH tells your system where to find it.

    You can inspect your path with this command:

    echo $PATH | tr ':' '\n'

    To update your PATH, you usually add a line to your shell configuration file (~/.zshrc for most Mac users):

    export PATH="/your/new/path:$PATH"

    This adds /your/new/path to the front of the list, so it takes priority. After editing the file restart your terminal to apply the change.

    It’s good proactive to place your executable files into ~/.local/bin, so let’s add this line to ~/.zshrc:

    export PATH="$HOME/.local/bin:$PATH"

    Checking executables

    Not sure if you’re using the right version of a <program>?

    Use which to print the path of the program that’s resolved from PATH:

    which python3
    # /usr/bin/python3

    Use which -a to list all of the versions and the order in which they’re resolved

    which -a pwd
    # pwd is a shell builtin
    # pwd is /bin/pwd

    Keyboard shortcuts when typing (in the terminal and elsewhere)

    The readline keybindings are surprisingly ubiquitous across most programs and systems. Learning these keybinds will instantly increase your speed in the terminal and elsewhere.

    Here’s a quick cheat-sheet for the ones I use most frequently in the terminal:

    Ctrl-a
        Move cursor to the start of the line
    Ctrl-e
        Move cursor to the end of the line
    
    Ctrl-k
        Delete text after the cursor to the end of the line.
    Ctrl-u
        Delete text before the cursor to the start of the line.
    
    Ctrl-w
        Delete word before cursor
    
    Alt-f
        Move cursor forward by one word
    Alt-b
        Move cursor backward by one word

    And some other keybinds that are also useful for the terminal:

    Ctrl-l
        Clear the screen
    
    Ctrl-r
        Search your command history
    
    Ctrl-d
        Exit the currently running command
    Ctrl-c
        Cancel the currently running command
    
    Ctrl-z
        Suspend the currently running command (run `fg` to return to it)

    Package management with Brew

    brew is an unofficial package manager for MacOS and Linux

    Install it with

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    Make sure that this line is present in ~/.zshrc:

    eval "$(/opt/homebrew/bin/brew shellenv)"

    Restart your terminal, and you should be able to install tools

    brew install wget    # Add a package
    brew uninstall wget  # Remove a package

    Unix has a wide array of powerful command line tools such as grep. MacOS comes with these tools too, but they behave differently than they do on Linux. It’s worth the effort to learn these tools when working with remote compute instances, and the best place to learn is locally

    Installing the Linux versions of these tools give you predictable behavior that matches tutorials or StackOverflow answers written for Linux.

    To replace these tools, install them from brew:

    brew install coreutils findutils grep

    And add them to your PATH in ~/.zshrc:

    export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"
    export PATH="/opt/homebrew/opt/findutils/libexec/gnubin:$PATH"
    export PATH="/opt/homebrew/opt/grep/libexec/gnubin:$PATH"

    There’s also some other core utilities that are worth updating too:

    brew install awk gnu-sed nano git less diffutils

    Getting help with commands

    Remembering the command syntax for different tools is hard. I constantly forget it, but thankfully there’s excellent documentation at hand!

    Most commands have a --help flag that will print a quick summary of how to use the command.

    There’s also the man pages for commands. If you need to view the full documentation of a command, run man <command> and it will show you the documentation in the terminal with the command less, which lets you page through a long document.

    Navigating less seems a bit awkward, but there’s a few keybinds that will make this much easier:

    /
        Start a serach for a particular keyword
    n
        Jump to next search result
    N
        Jump to previous search result
    
    Ctrl-d
        Scroll a half-page down
    Ctrl-u
        Scroll a half-page up
    
    j
        Scroll one line down
    k
        Scroll one line up

    You can always display output of a command in less by using a pipe:

    <command> --help | less

    One of the best tools I’ve come across for quick help is tldr. You can install it with using

    brew install tldr

    This command will print a short cheat sheet for most commands when you run tldr <command>.

    UV For Python environment management and tool installation

    UV is a much much faster alternative to pip and poetry, install it with

    curl -LsSf https://astral.sh/uv/install.sh | sh

    Start a project with

    uv init <name>

    Manage dependencies with

    uv add <dep>
    uv remove <dep>

    Update the lockfile and install deps

    uv sync

    Run commands in the virtual environment

    uv run <cmd>

    Installing pre-commit and other python tools with UV

    One of the best features about UV is uv tool install. Many tools out there are written in Python, but installing them with your system python environment is fragile because of the awful dependency management that has plagued Python for decades.

    I used to use pipx, which would automatically create an isolated python environment for each tool so dependencies of one tool would not break another. It also managed creating the commands for me as well. Amazingly, uv also has this capability!

    For example, pre-commit is a useful tool to have when working on projects with pre-commit hooks. I’ll write about this in more depth, but for now let’s just focus on installing it with uv:

    uv tool install pre-commit

    Now this tool is installed on your system:

    which pre-commit
    # /home/blake/.local/bin/pre-commit

    If you’d like to try it out, go to a git repo that uses pre-commit and install its hooks with

    pre-commit install

    Git config and aliases

    The file ~/.gitconfig contains your git configuration. Here’s a couple of highlights from mine

    # A couple of shortened commands with shorter output
    # * `git st`: Shorter git status
    # * `git lg`: Shorter git log
    # * `git forget`: Just discard all of my changes and bring me back to the last commit
    [alias]
        st = "!git status -sb"
        lg = "!git log --oneline"
        forget = "!git reset --hard HEAD"
    
    # Better output for `git diff`
    # * Better diff algorithm
    # * Colors blobs of moved code differently
    # * Indicates when a file is renamed without changes
    [diff]
        algorithm = histogram
        colorMoved = plain
        renames = true
    
    # Always merge when pulling changes
    # (A philosophical choice, but I think this preserves git history a bit better)
    [pull]
        rebase = false
    
    # Better `git push`
    # * Automatically create new branches on remote when pushing new branches
    # * Automaitcally set the upstream branch
    [push]
        default = simple
        autoSetupRemote = true
    
    # Make `git fetch` automatically prune branches that aren't on remote
    [fetch]
        prune = true
        all = true
    
    # Typo in your git command? Git will suggest what you probably meant
    [help]
        autocorrect = prompt

    Check out this article by Scott Chacon for more inspiration

    Making the Terminal Comfortable (iTerm2, Fonts, Hotkeys)

    ITerm2 provides a much better alternative to the default Terminal on MacOS with sane defaults out of the box

    VSCode has its own in-built terminal, but it’s good to have a dedicated terminal on hand in case you need to run something quick. The only way to get good at using the terminal is to use it more often, so you might as well use a nice one!

    I like to use a nice font for my terminal, my preference is JetBrains mono

    To install this on MacOS:

    brew install --cask font-jetbrains-mono-nerd-font

    Then in iTerm2, go to Preferences > Profiles > Text > Font and select “JetBrains Mono Nerd Font”, and switch on anti-aliasing.

    You might also want to turn on Ligatures, which render sequences of symbols in a nice way (for example => displays as “⇒”)

    For colourschemes, check out the collection from mbadolato. Pick a colourscheme you like (I personally recommend Gruvbox Dark Hard, Atom One Dark, or GitHub Dark). It looks like they also have instructions for using them in VSCode for a more cohesive experience

    Changing your shell prompt is also not strictly necessary. I think this is a nice aesthetic change that adds some extra context and flair to the command line (such as the current python version or AWS region)

    Starship offers a fantastic prompt, install it with

    brew install starship

    And then add this snippet to your ~/.zshrc

    eval "$(starship init zsh)"

    Personally I’m relatively new to this tool, but its default configuration tidies the prompt really well. But it also looks like there is a lot of customisation options available


    By the end of these steps, we should have the following commands in our ~/.zshrc:

    # Brew package manager
    eval "$(/opt/homebrew/bin/brew shellenv)"
    
    # Starship prompt
    eval "$(starship init zsh)"
    
    # Replace MacOS standard tools with Unix standard tools
    export PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"
    export PATH="/opt/homebrew/opt/findutils/libexec/gnubin:$PATH"
    export PATH="/opt/homebrew/opt/grep/libexec/gnubin:$PATH"
    
    # Add local executable commands
    export PATH="$HOME/.local/bin:$PATH"
  • AI and the Mythical Man-Month: Productivity or Paradox?

    The Mythical Man-Month by Fred Brooks is widely regarded as one of the foundational books on software engineering. Among its many insights, one has stood the test of time:

    Adding more people to a late software project only makes it later.

    Software development is not trivially parallelizable — communication and coordination overheads dominate. Even though the original text was written in 1975, it’s proven remarkably durable over the decades since its publication. This key insight is a common thread across many domains involving long-term projects, and it’s no surprise that this text is also well regarded outside of software engineering. Precisely because complexity scales non-linearly with team size in long-term collaborative efforts.

    But what about AI?

    I doubt Fred Brooks would have envisioned this reality we now find ourselves in, but I would argue that many of his core principles still hold true today, and perhaps more than they ever did.

    There has been no shortage of hype around AI-driven productivity in software. Demos abound showing LLMs rapidly producing code from vague instructions. Agentic workflows promise to go even further, stringing together sequences of actions to build, deploy, and even monitor systems. Many developers claim substantial boosts in productivity.

    We’re still in the “wild west” stage of this technology — and there is a shocking amount of snake oil in circulation. It’s challenging weighing up these anecdotes and curated demonstrations and extrapolating their impact across the general domain.

    Revisiting “The Mythical Man-Month” helped me clarify my skepticism:

    • System design remains non-parallelizable: architectural choices still require shared understanding and intentional decision-making
    • Communication overhead persists: even when agents are machines, coordination isn’t free
    • Integration is still a bottleneck: while agentic workflows can impressively handle debugging and testing up to a point, integrating into the larger picture is not something AI automates well

    Yes, AI accelerates the code writing process dramatically, but writing code was never the bottleneck — reading the code is. The harder problems live upstream (design) and downstream (integration, maintenance). AI doesn’t solve these, and sometimes it makes them worse:

    • Prompt engineering, managing hallucinations, and additional oversight incur new costs to productivity,
    • AI-generated code can shift complexity downstream (e.g., into ops, observability, or maintenance).
    • Overproduction risk: faster code generation doesn’t mean better outcomes. Just more things to verify, debug, or discard.

    All of that code still needs to be reviewed, tested, and ultimately approved by someone who takes responsibility. In many workflows, this slows things down. The coordination costs don’t vanish: they shift. In some cases, delivery may actually take longer if not used carefully.

    To be clear: the progress made in this space in a very short span has been astonishing — and it shows no signs of slowing down. Don’t forget: this is the worst it will ever be. It’ll either plateau, or it will continue to improve.

    There is a strong case for agentic workflows: they let you offload smaller implementations details while you can focus on the harder upstream problems. In practice however, I often find the cognitive friction of context-switching (from deep thinking to debugging hallucinated output) makes it harder to stay focused. Once again, the system stalls at the point of coordination, even if the “other party” is just an AI.

    What I’ve found more helpful is using AI to overcome the hurdles that occur when starting something new. The inclusion of a rubber duck that responds with good ideas ironically prompts me to overcome challenges much easier. But importantly I’m still at the wheel, and I can still weave the larger picture throughout all the small details. The consequences of these decisions accumulates, and this can make or break a large codebase if not done carefully.

    The rise of multiprocessing gave us powerful new tools, and new ways to shoot ourselves in the foot. Over time, we developed safer paradigms for concurrency, but thinking in parallel is still hard for humans. I suspect agentic workflows will follow a similar path.

    What that looks like in practice — and whether it delivers on the promises being made today — remains to be seen.

  • Fundamentals of machine learning and training neural networks

    It’s an exciting time for machine learning and AI. Models such as ChatGPT and it’s ilk appear nothing short of magical. The natural question arises — how is any of this possible?

    The answer essentially boils down to two things:

    1. Iterative mathematical methods to “follow” a function’s slope towards (essentially Newton’s method for solving functions)
    2. A LOT of computational power

    ChatGPT is essentially a very complicated mathematical function that takes a text input, and tries to predict to next blob of text in the sequence.

    I’ve had so many wonderful discussions with people who want to learn, but a common thread that comes up is the intimidation of the maths required to understand it.

    I’m here to say that the good news is: you don’t need that much maths to get into it! Honestly, the main thing you need is a solid grasp of the concepts, rather than the inner calculations.

    But how do we arrive to that conceptual understanding? I want to help people make that connection and de-mystify the calculus that happens under the hood, and show ho to do machine learning (with the widely used pytorch library).

    I’ve written a tutorial on basic pytorch before, but today I want to take a step back and focus more on connecting the code with the underlying theory and concepts.

    In a previous job, I worked with David Norrish, who was kind enough to assemble a series of notebooks explaining convolutional neural networks from first principles. I’ll be drawing on his work for this explanation, as well as the following Pytorch tutorials:

    When training a model, we want it to get better at its task over time. In PyTorch, this is done by:

    1. Measuring how wrong the model is (with a loss function), and

    2. Adjusting the model’s weights (with an optimizer) to reduce that error.

    Today we will

    • Get a brief overview of the ideas from calculus we’ll need
    • Establish a simple problem of fitting a line through a set of points on a 2d plane
    • Define how to measure how wrong the model is
    • Connect the concepts with the code used to fit this model

    Demystifying the calculus

    At the heart of training a neural network is calculus — specifically, gradients, and how they tell us which direction to move the models weights to make better predictions.

    The core idea is this:

    A gradient measures how much a change in one variable (like a weight in your model) will affect the output (like the loss).

    We want to minimize the loss, so we compute the gradient of the loss with respect to each parameter. This tells us how to change each parameter to decrease the loss.

    To compute these gradients, we use the chain rule from calculus. The chain rule says:

    the gradient of z relative to y and that of y relative to x allows one to calculate the gradient of z relative to x as the product of the two gradients. Wikipedia

    Neural networks are just composed functions — data flows through layers of computation. So when we compute the gradient of the loss with respect to a weight deep in the model, we’re chaining together many of these derivative computations.

    Doing this by hand is painful. Fortunately the autograd engine in PyTorch automatically tracks operations on tensors, builds a “computation graph”, and applies the chain rule backward through that graph when you call the backward() method on a tensor.

    This method will fill in the grad attribute on each parameter with the right derivative.

    Great, so we have the gradients… What do we do with them?

    There’s a variety of optimization methods out there, but we won’t go into detail with any of them today — we’ll just use the helpful abstractions in PyTorch.

    Step 0: Establish the problem

    Let’s say that we have a dataset of a collection of points on the 2d plane, represented by {(x_0, y_0), (x_1, y_1), (x_2, y_2), ..., (x_N, y_N)}. We want to find a model, given by a function of x that outputs y, that best matches this dataset. Keeping with the ChatGPT analogy, let’s pre=tend that x represents some blob of text, and y is the next blob of text.

    The simplest neural network we can use for this problem is a linear regression f(x) = W * x + b, where

    • f(x) is our model (“neural network”)
    • x is the input to the model
    • W is a 1 x 1 matrix (1 parameters)
    • b is a 1-dimensional vector (1 parameters)

    So we have a dataset, and we have a model — and we want to find the “best” values for W and b such that f(x) has the best “fit” to this dataset.

    What does “fit” mean in this context?

    We can measure how good of a fit we have by calculating the distance between our model and the points {x_0, x_1, ...}, squaring the distances, then adding them all together: called the mean squared error loss (mse)

    L = sum([(x_i - f(x_i)) ^ 2 for x_i in x])

    The lower this value L is, the better our model is.

    So how do we find the best f that gets the lowest possible L?

    1. “guess” what the parameters of f should be
    2. calculate L,
    3. compute the gradients with respect to the parameter values,
      • That it, we’ll calculate the gradient of L with respect to W and the gradient of L with respect to b
    4. adjust the parameters to follow the gradients of L down, so that we can pick new values of W and b that achieve a lower value of L
    5. repeat!

    After several iterations of this, our model f will improve, and “learn”.

    Conceptually, that’s all there is to the fundamentals of machine learning.

    Step 1: Track Gradients with autograd

    PyTorch automatically keeps track of operations on tensors that require gradients. This means if you define a model weight with requires_grad=True, PyTorch will remember how it was used and compute its gradient when you call the backward() method on the output of the calculations.

    import torch
    
    # Some example inputs and model weights
    x = torch.randn(5)  # Input vector
    y = torch.randn(5)  # Target output
    
    w = torch.randn(1, requires_grad=True)  # Model weights
    b = torch.randn(1, requires_grad=True)  # Bias term
    
    # Model output
    z = x * w + b  # Linear layer
    
    # Loss: mean squared error
    loss = torch.nn.functional.mse_loss(z, y)
    
    # Compute gradients
    loss.backward()
    
    # Now w.grad and b.grad contain the gradients

    Step 2: Update Weights with an Optimizer

    After computing gradients, we use an optimizer to update the model’s weights. The Adam optimizer is commonly used because it adjusts learning rates automatically for each parameter and generally works well out of the box.

    We’ll pick a learning rate (lr) of 0.001 to adjust the magnitude of these steps. There’s not really a hard science for choosing a good learning rate aside from experimentation, but we want to err on the side of “small, but not too small”.

    # Create the optimizer
    optimizer = torch.optim.Adam([w, b], lr=0.001)
    
    # Apply the gradient update
    optimizer.step()
    
    # Reset the tracked gradients
    optimizer.zero_grad()

    Important: Before calling the backward() method each time, we shouldn’t forget to reset the gradients with optimizer.zero_grad().

    Otherwise, PyTorch will accumulate gradients across steps, and the model won’t fit correctly!

    Putting It Together

    A basic training step looks like this:

    # Forward pass
    z = x * w + b
    loss = torch.nn.functional.mse_loss(z, y)
    
    # Backward pass
    loss.backward()  # Compute new gradients
    optimizer.step()  # Update weights
    optimizer.zero_grad()  # Clear old gradients

    And that’s all there is to it! We can then put this into a for loop for a fixed number of iterations, and we’ll end up with a pretty good model for our dataset.

    There’s many more techniques and tricks used in the machine learning practice, but it all comes back to these fundamentals. With this understanding, we can swap f(x) = W * x + b for more complicated models, and the same recipe will give us a good fit for our data.

    As I’ve show, the maths is not the hard part of machine learning. The hard parts are more often:

    • Working with messy real world data
    • Selecting an appropriate model (not too big, not too small)
    • Selecting hyperparameters such as the learning rate

    As we get more comfortable with these concepts, we’ll come back to this topic and expand on these difficulties in future posts.