Make your code available…

If all else fails - I really am happy to help (and have taken a look at various issues for people this year)!

It helps if you can give me as much information as possible about

• what seems to be going wrong
• what you’re trying to achieve, and why
• what you’ve already tried

… and runnable!

Please either provide

• an environment.yml or requirements.txt (if you have made your own environment from scratch)
• or details of which of the HSMA environments you have used, and any packages you’ve added into those environments

If you are using branches, please make it clear which branch we need to be looking at!

Making your code super readable with docstrings

One of the best ways to make your code even easier for us to work with is to use docstrings.

Docstrings are like a super-comment that makes it easier to understand your functions, classes, and methods - wherever you are accessing them in the code.

When you start using a function from a package and it pops up with a load of extra useful details, that’s its docstring you are seeing.

Writing docstrings

Docstrings are put after you define a function name

A simple docstring might look like this:

def get_meaning_life_universe_everything():
    """Retrieves the answer to the ultimate question"""
    return 42

print(get_meaning_life_universe_everything())

42

Here’s an article with a great introduction to writing docstrings.

https://www.datacamp.com/tutorial/docstrings-python

Advanced Docstrings

For more advanced docstrings, we also specify details about the inputs and outputs using specific notation.

There are various formats that exist, like PyDoc and Google Docstrings - my personal favourite is numpydoc

def multiply_two_numbers(number_1, number_2):
    """
    Multiplies two numbers and prints the result.

    Parameters
    ----------
    number_1 : int or float
        The first number to be multiplied.
    number_2 : int or float
        The second number to be multiplied.

    Returns
    -------
    None
        This function prints the result but does not return it.
    """
    print(number_1 * number_2)

Our advanced docstring in action

Bookable slots

However, I recognise that sometimes only a chat will do!

I will be opening up some more bookable slots soon and sharing a link!

What can we use issues for?

The great thing about your repo… is that it’s your repo!

Established projects may have more rules about what can be an issue and how it’s formatted, but you can set the rules on your project.

So you could use issues for

Examples of projects using issues - vidigi

In the vidigi issues, I’m primarily talking to myself and using it as a big to-do list.

Examples of projects using issues

In another project, we have used it for three of us to be able to communicate asynchronously about the project

Examples of projects using issues - Helena’s DES

Helena has been using these very effectively in her project

https://github.com/Countess-of-Chester-Hospital-NHS-FT/Non-Elective-Flow-Simulation/issues?q=is%3Aissue%20

Communication via Issues - a sneak peak

Including to summon me! (more on this later)

The Issues Tab

In your repositories, whether they are public or private, you should see an ‘Issues’ tab.

Our First Issue

When we first load this up, there’s nothing here… so let’s change that!

We’ll click the ‘New Issue’ button

Populating our first issue

The minimum we need to provide is a title (though it’s a good idea to put in some description too)

Viewing our first issue

This will take us to a view where we can add comments to the issue.

• We can edit the title with the ‘edit’ button
• We can edit the description with the three dots
• We can close the issue when we’ve resolved it

Viewing our issue list

Heading back to our ‘issues’ page we can now see this in our list of issues.

Labels

Adding our own labels

… we are taken to a page where we can create any label we fancy

Filtering by Labels

On our issues page, we can then click on the ‘labels’ dropdown to only find certain kinds of issue.

Mentioning issues elsewhere

It can be really helpful to mention issues on other issues, or in pull requests!

Typing a # symbol brings up a list of recent issues, and by starting to type you can filter it down by number…

Mentioning issues elsewhere (contd.)

… or by name

How mentioned issues display

Mentioned issues will turn into a link when you save the description or comment

And they’ll show up in the linked issues and pull requests too

Tagging People in issues

If you mention someone by their GitHub username - prefacing it with an @ symbol - then they will get a notification.

On a public repo - or one where you’ve added me as a collaborator - you could summon me like that!

Closing Issues

When you are done with an issue, we can write a comment (optional, but recommended!) and close it down.

Fancy issue closing

In pull requests, if we mention an issue by ID with the # notation, it will

• expand the issue ID into the issue name
• automatically close the issue when the pull request is merged in if you use certain keywords like ‘resolves’

Milestones

In your projects, you may have different milestones you are working towards.

You might want to keep track of the issues you are aiming to achieve by different stages of the project - and then track your progress towards that.

In vidigi, I just use it to track issues I’m planning to fix in each minor version

Milestones - another approach

In another project, we’ve tied it in more detail to due dates and goals.

Creating a milestone

From the issue page, click ‘milestones’.

Then ‘new milestone’

Populating milestone details

From this, you can then enter a title of your choice, an optional due date, and any details to flesh out things like key goals or requirements.

Adding issues to a milestone via the milestones page

Now, when we click on the milestone header, we are given the option to add any issue to our new milestone.

Creating a new project

We’ll click ‘new project’

Choosing aa project template

We’ll be provided with a list of possible project layouts.

My favourite is Kanban - but feel free to experiment!

Setting the project name

Give your project a name.

Our project

Initially we’re presented with a list of empty columns.

We then click on ‘add item’

Adding issues to columns

If we click ‘add items from repository’ we can access our current repo’s issues - or issues from other repos!

Managing your project

Once this is done, we have an issue in the column.

Moving issues between columns

We can move this around as we progress.

Moving it to done automatically closes it (though it might take 10-15 seconds to do so)!

Managing columns

An Introduction to Project Documentation and its role in Model Validation

Why do I bang on so much about documentation?

Quarto

Automated documentation with Sphinx and Quartodoc

I’ve recently being diving into quartodoc too - this is a really cool addon for quarto that allows you to generate documentation for various functions in your project as well and weave that into a quarto book

It’s a bit more tricky to get started with than pure quarto (and is something you could look to incorporate at a later stage in an already established quarto book)

https://github.com/machow/quartodoc

Another more established and popular alternative is sphinx, though I haven’t used it myself.

Quartodoc example - function page

Function overview page

Getting started with quartodoc

There’s a good introduction to quartodoc in their documentation: https://machow.github.io/quartodoc/get-started/overview.html

Note that you can also set it up without turning your project into a package: https://machow.github.io/quartodoc/get-started/basic-content.html#documenting-source-files-that-are-not-a-package

The _quarto.yml for vidigi would also be a good starting point if combining traditional quarto with quartodoc is something you want to do: https://github.com/Bergam0t/vidigi/blob/main/_quarto.yml

STRESS-DES: Data

STRESS-DES: Data (contd.)

STRESS-DES: Implementation

STRESS-DES: Code access

STARS Components

Overview of the STARS Framework from Monks et al. (2024) (CC BY 4.0).

Key useful things in 1.43.0

Read the full release notes here

Key useful things in 1.42.0

Read the full release notes here

Key useful things in 1.39.0

Read the full release notes here

Upgrading Streamlit

Make sure you update version numbers in your requirements.txt or environment.yml file!

Code and output

def iconMetricContainer(key,icon_unicode,css_style=None,icon_color='grey', family="filled", type="icons"):
    """Function that returns a CSS styled container for adding a Material Icon to a Streamlit st.metric value

    CREDIT for starter version of this code: https://discuss.streamlit.io/t/adding-an-icon-to-a-st-metric-easily/59140?u=sammi1

    Args:
        key (str): Unique key for the component
        iconUnicode (str): Code point for a Material Icon, you can find them here https://fonts.google.com/icons. Sample \e8b6
        css_style(str, optional): Additional CSS to apply
        icon_color (str, optional): HTML Hex color value for the icon. Defaults to 'grey'.
        family(str, optional): "filled" or "outline". Only works with type = "icons"
        type(str, optional): "icons" or "symbols"

    Returns:
        DeltaGenerator: A container object. Elements can be added to this container using either the 'with'
        notation or by calling methods directly on the returned object.
    """

    if (family == "filled") and (type=="icons"):
        font_family = "Material Icons"
    elif (family == "outline") and (type=="icons"):
        font_family = "Material Icons Outlined"
    # elif (family == "filled") and (type=="symbols"):
    #     font_family = "Material Symbols"
    elif type=="symbols":
        font_family = "Material Symbols Outlined"
    else:
        print("ERROR - Check Params for iconMetricContainer")
        font_family = "Material Icons"

    css_style_icon=f'''
                    div[data-testid="stMetricValue"]>div::before
                    {{
                        font-family: {font_family};
                        content: "\{icon_unicode}";
                        vertical-align: -20%;
                        color: {icon_color};
                    }}
                    '''

    if css_style is not None:
        css_style_icon += """

        """

        css_style_icon += css_style

    iconMetric=stylable_container(
                key=key,
                css_styles=css_style_icon
            )
    return iconMetric

## EXAMPLE USAGE
my_formatted_value_for_metric="6.3%"

with iconMetricContainer(key="nonattend_metric", icon_unicode="e61f", family="outline"):
    st.metric("Average Number of Calls Resource Couldn't Attend",
            my_formatted_value_for_metric,
            border=True)

Opening the ‘Configure Snippets’ Menu

Choosing the snippet language

Writing our snippet - Quarto

{
    // Place your snippets for markdown here. Each snippet is defined under a snippet name and has a prefix, body and
    // description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
    // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the
    // same ids are connected.
    // Example:
    // "Print to console": {
    //  "prefix": "log",
    //  "body": [
    //      "console.log('$1');",
    //      "$2"
    //  ],
    //  "description": "Log output to console"
    // }

    "Make a two-column layout": {
        "prefix": "col2",
        "body": [
            ":::: {.columns}",
            "",
            "::: {.column width='50%'}",
            "",
            ":::",
            "",
            "::: {.column width='50%'}",
            "",
            ":::",
            "",
            "::::"
        ],
        "description": "Create a column layout in quarto with two columns of equal width"
    },

    "Make a fragment": {
        "prefix": "frag",
        "body": [
            "::: {.fragment}",
            "",
            ":::"

        ],
        "description": "Create a quarto fragment for incremental revealing of content"
    },

    "Make an incremental list": {
        "prefix": "inc",
        "body": [
            "::: {.incremental}",
            "",
            ":::"

        ],
        "description": "Create a quarto incremental list container for revealing one bullet point at a time"
    }
}

Using our Quarto snippet

Writing and using our snippet - Python

Python snippets are similar!

Here we’ve defined a snippet called ‘condlist’ for generating a conditional list comprehension.

{
    // Place your snippets for python here. Each snippet is defined under a snippet name and has a prefix, body and
    // description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
    // $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the
    // same ids are connected.
    // Example:
    // "Print to console": {
    //  "prefix": "log",
    //  "body": [
    //      "console.log('$1');",
    //      "$2"
    //  ],
    //  "description": "Log output to console"
    // }

    "Conditional list comprehension": {
        "prefix": "condlist",
        "body": [
            "['Even' if n % 2 == 0 else 'Odd' for n in a]"
        ],
        "description": "Provide an adaptable template for conditional logic in a list comprehension"
    }

}

To find out more on snippets, click here