⏱ Habits and Summaries plugin

As NotePlan is such a flexible app, there are various ways people use it to track habits.

This Plugin command helps show progress for items you track (e.g. @work(9), @run(5.3), #prayed or + [x] vitamins) over various time periods. It does this by generating stats for the configured #hashtags or @mentions over the time interval you select, and displaying in several possible ways.

In more detail this plugin lets you:

• see Habit & Summary Charts: your progress update as bar charts, heatmaps and summary statistics in a special window (/chart progress summary)

  

• track habits: for example, show when this week I've managed to #closedmyrings or #tookMeds? This is written into, and shown in, a NP note.

  

• show your progress over the last 2 weeks against your goal of getting an average 8 hours @sleep

• show your total Calorie count from different mentions in your daily note

• count every time you've noted you've visited #family or watched #tv this month

• count the times you've met with staff member @alice this year so far

• sum the length of your @runs in the last quarter

• get a breakdown of how you're spending your week by tracking minutes across various areas (e.g. in a daily note - @email(30); @email(10); @coding(45); @writing(30) or #words/90)

• track completion of a reference checklist template

• show a heatmap chart of your @sleep stats

  

• show a heatmap chart of how many tasks you've completed recently

  

If you would like to support my late-night work extending NotePlan through writing these plugins, you can through:

How to use this

What do you need to do?

Add tags like #closedmyrings or @habit(number) in your daily notes. In my case a day might include:

@sleep(5.3) @activeCals(400) @steps(3800) @distance(2.7) @minHR(50) @maxHR(161) @restingHR(66) @fruitveg(4)
@work(10) #readbook
Remember: #visit to new CFL premises in Festival Place #prayer #win #filmvideo

You might find a simple 'Shortcut' for use on iOS/macOS helpful to make it quicker to add items like this to the daily note. Sean O'Kana has shared a shortcut to do this which you can add and customise.

You can also include these @mentions and #tags in the metadata in a note's 'frontmatter' if you wish.

What does the plugin do?

It provides commands, each described in more detail below, that read these tags and generates several different sorts of summaries and basic stats from your daily notes.

When to use the commands?

It's up to you! I run /progress update as part of my daily note (see Calling from a Template below), but you might want to do it at the end of a day/week/month in those notes. Or open /chart progress summary from the command bar or the sidebar at any time for a chart view of the same tracked items.

All these commands require some setup, so it knows what you want to summarise. Do this in the Plugin Preferences panel by clicking on the "Habits & Summaries" card, and then the "Settings" button. Each setting has an explanation (below), and they are grouped into relevant sections.

General notes about all commands

• All notes in the special folders (@Archive, @Templates and @Trash) are ignored. Others can be excluded too using the "Folders to exclude" setting.

• Use setting "Exclude today's entries?" to exclude today's entries in progress updates. Can be enabled if you tend to run the progress update as part of a start-of-day routine, and only add the updates later in the day.

• Numeric values can be decimals (e.g. @sleep(7.7)) or durations in H:MM form (e.g. @sleep(7:42), @bedtime(23:30)). Config entries can include or omit the leading @ or #; both styles match the same tags in your notes.

---

'chart progress summary' command (aliases: 'hsc', 'cps', 'habits')

This shows your configured items as lovely Habit & Summary Charts: bar charts, heatmaps and summary statistics in a window (also available from the NotePlan sidebar). It was prototyped by @grdn and integrated for v1.1.0.

It uses the same tag lists and the same "What time period should the Progress update cover?" setting as earlier command '/progress summary'. The period selector is shown at the top of the window; changing it updates that setting so Reload keeps your choice. There is also a "Custom range…" option at the top of the period list for an ad-hoc from/to date range.

For each configured item it can show:

• a grid for yes/no items
• total and average sections
• day-by-day bars, and counts/averages/totals in the chart header where relevant
• optional average lines on charts where an average is requested: none, 7-day moving average, or average of each successive weekly period (always Monday-Sunday; weeks with no data are omitted)

Time-based tags show sums and averages in HH:MM where relevant.

What progress items to summarize?

There are lots of different ways items can be summarised. They are set in the Plugin Preference pane (and are shared with "progress update" settings below):

• What time period should the Progress update cover? Pick one of the options: 'wtd' or 'userwtd' (two week-to-date options), 'last7d' (last 7 days), 'mtd' (month to date), 'last2w' (last 2 weeks), 'last4w' (last 4 weeks), 'qtd' (quarter to date), 'last3m' (last 3 months). Note: wtd and userwtd behave slightly differently to each other:
  • wtd is the week to date using ISO standard (Monday)
  • userwtd is week to date using whatever you've set the start of week to be in NotePlan's 'Calendars' Preferences pane.
• Yes/No items: Comma-separated list of #hashtags and/or @mentions to track by 'did I do it this day or not?'. e.g. '#closedrings, #prayed, #tookMeds'
• #hashtags to count: e.g. '#tv, #podcast' -- the simple count of all such tags is displayed
• #hashtags to average: e.g. '#fruitveg' -- these are counted and displayed as an average (to 2 significant figures)
• #hashtags to total: e.g. '#steps' -- these are counted and displayed as a total
• @mentions to count: e.g. '@work' -- the simple count of all such tags is displayed
• @mentions to average: e.g. '@sleep, @fruitveg' -- these are counted and displayed as an average (to 2 significant figures)
• @mentions to total: e.g. '@distance, @run' -- these are counted and displayed as a total
• Title of Reference note for checklist items: See Alternative 'Checklist completion' method below.

Chart Display settings

These are under "'/chart progress summary' display settings:

• Chart height: height for numeric-tag charts (in pixels)
• Colors for Charts: comma-separated colours, specified as CSS names, Tailwind names such as sky-500, or hex/rgb/hsl
• Non-zero Y-axis tags (JSON): optional per-tag { min, max } for the Y-axis
• Number of Significant figures to use in stats
• Chart average line: none, moving (7-day moving average), or weekly (average of each successive 7-day period)

---

'progress update' command (aliases: 'apu', 'appendProgressUpdate', 'habitTracker')

This older command generates stats for the configured #hashtags or @mentions over the time interval you select, and inserts it as a section into a note. If the progress update section already exists in the destination note -- if for example you have it set to insert in the weekly note -- it will be updated, rather than be repeated.

(This command was renamed from /appendProgressUpdate in v1.1.0; the old name still works as an alias.)

For example, it produces for me:

Note:

• The statistics shown vary whether you have selected count, average or total for that tag in the settings
• The leading @ or # is removed in the output, to avoid double-counting problems.

There are now 3 ways of running this: as the /progress update command; through templates, or by x-callback call. The various settings are common, but how they are applied differ depending which method is used to invoke it. The settings and their meaning are introduced next, and differences in how they're applied are described in the following sections.

Note: If you 'Refresh' an existing progress summary in an older note, from v1.0 it will attempt to work out what time interval it covers and update it for that time period.

Settings for progress update

Most are the same as for chart progress summary, above.

There's also:

• Where to write the progress update? The destination note is either the 'current'ly open note, or the current 'daily' or 'weekly' note.
• Progress heading: this is the heading to go before the output, to which is added the period that's covered. If it contains the string '{{PERIOD}}, then the covered period will be inserted in place of this string wherever you want in the heading.
• Heading Level: to use when inserting heading above the progress summary section.
• Include sparkline graphs?
• Yes/No characters: sets the pair of characters to use as Yes and No in output of "Yes/No items". The first is for Yes, the second for No (without a comma to separate them). Here are some you might like to use for Yes: ✓✔■⧫▉ and for No: ·◦✕✖◌□. (You can use emojis, such as ✅🟢❌👎🔴, but they are likely to mess up the horizontal spacing.)

Displaying the 'sparkline' charts

The command output can include little "sparkline" graphs, as a simple in-line visualisation of the recorded activity for each item you're tracking, where the time period is a month or less. A dot . indicates there's no data for that day; the height of the bar indicates the value of that day, relative to the maximum in that time period. The minimum is always 0, not the lowest value, and that is always shown as an empty space.

To display them requires your font to have the necessary characters (▁▂▃▄▅▆▇█). All of NotePlan's built-in themes have the characters, and I have tested with Menlo and Cascadia Code monospace fonts as well. See NotePlan help on how to set fonts in themes.

In particular it uses the code attribute of the theme (if set). Here's an example from one of my themes:

	"code": {
		"font": "Menlo-Regular",
		"color": "#3B3AB2",
        "backgroundColor": "#F4F4FB"
    },

Note: According to several sources the only monospace fonts on iPhone/iPad are forms of Courier (e.g. Courier-Bold) and Menlo (e.g. Menlo-Regular).

Alternative 'Checklist completion' method

There's another way to specify Yes/No items, by whether certain checklist items are completed in daily notes. To use this method you need to create a 'reference checklist' a separate note in the template folder:

Add the title of this template to settings:

Then in your daily note include the same checklist, and mark them as completed in the usual way. (If you want to use this template in another note it can be imported using <%- import("Daily tasks") -%>)

Then completion is shown using the '/progress update' command, for example:

Calling from a Template

This command can be used in any Template, but is particularly designed to be used from a "Daily Note Template" by including a 'progressUpdate(...)' command tag in a template such as:

<%- progressUpdate({period: 'wtd', progressHeading: 'Habits', showSparklines: true}) %>

or

<%- progressUpdate({period: '2022-02-15', excludeToday: true, progressHeading: 'Post-Birthday Habits', showSparklines: true}) %>

You can add many parameters, which if present override all the main settings described above. The simple settings are:

1. period (alias interval): time period to run report for, e.g. wtd or userwtd (week to date), mtd (month to date), qtd (quarter to date), last7d, last2w, last4w, last3m, or give a specific ISO8601 date to report since (e.g. 2022-10-25)
2. progressHeading: "string" to use before the results.
3. showSparklines: true (default) or false.
4. excludeToday: false (default) or true (applies when you set a date for period and you don't want to include today in the visualization -- e.g. if you use this template as part of your /dayStart routine and you haven't had time to do the habit yet!)

The more complex ones are the settings that take lists of hashtags or mentions: E.g. {... progressYesNo:"#read,#pray,#exercise", ...}. If any are of these are set, then only this list will be used. Each must be a key:"value" pair, with string values enclosed in double quotes, with following pairs separated by commas, and all enclosed in curly brackets (i.e. in JSON5 format). The possible 'key' names are:

• "progressYesNo": Yes/No items
• "progressHashtags": #hashtags to count
• "progressHashtagsAverage": #hashtags to average
• "progressHashtagsTotal": #hashtags to total
• "progressMentions": @mentions to count
• "progressMentionsAverage": @mentions to average
• "progressMentionsTotal": @mentions to total

Calling by x-callback

This is similar to the Template above: create a JSON5 version of "key":"value" pairs for parameters that are different from the normal saved settings, and then prefix with the string noteplan://x-callback-url/runPlugin?pluginID=jgclark.Summaries&command=progressUpdate&arg0=

For example:

noteplan://x-callback-url/runPlugin?pluginID=jgclark.Summaries&command=progressUpdate&arg0={"period": "2022-02-15", "excludeToday": true, "progressHeading": "Post-Birthday Habits", "showSparklines": true}

Notes:

• Any string-based value part must be enclosed in double quote marks to make it valid JSON5.
• Any arrays need to be enclosed in square brackets, e.g. "key":["one","two","three"] (not "key":"one,two,three" which will be treated as a single string)
• The JSON parts needs to be URL-encoded before it can be used. (For help with this, see the Get-X-Callback-URL command from the "Link Creator" Plugin. Select RUN a Plugin command > progressUpdate ...)

---

'today progress' command (alias: 'tp')

Sometimes you want to have a summary of progress on something within a day -- for example @calories(...) or @exercise(...). To summarise these from today's daily note use /today progress, which works in the same way as /progress update.

When run by the user directly, it adds the output onto the current note, and uses the following settings from the plugin pane:

• #hashtags and @mentions to total: a comma separated list of the terms to total from today's note
• Today Progress heading: optional heading to insert before the results.

Or you can run it from an x-callback using the form noteplan://x-callback-url/runPlugin?pluginID=jgclark.Summaries&command=todayProgress&arg0=?&arg1=? where

• arg0 is the comma separated list of items to summarise
• arg1 is the optional heading to use before the results

For example:

noteplan://x-callback-url/runPlugin?pluginID=jgclark.Summaries&command=todayProgress&arg0=@exercise,@calories&arg1=Post-Birthday%20Habits

You can also run it as part of a template; for example use in a "Daily Note Template" by including a line like the following: <%- todayProgressFromTemplate({todayProgressItems: '@calories, @exercise', todayProgressHeading: 'Progress Today'}) %>. (Note the slightly different 'command name', and that this time the parameters need to be given as a JSON5 object of key:'value' pairs.)

---

'period stats' command (aliases: 'pst', 'statsPeriod', 'stp', 'periodStats')

This command generates some simple counts and other statistics of #hashtags or @mentions that you specify, and saves them into notes in a special 'Summaries' folder. (Command renamed from /periodStats in v1.1.0; the old name still works as an alias.)

For example:

• count every time you've noted you've visited family this month -- i.e. counts the number of times #family is mentioned in calendar notes this month
• count the times you've met with staff member Alice this year so far -- i.e. counts the number of times @alice is mentioned in calendar notes this year
• sum and average the length of your runs last quarter -- i.e. stats on all the mentions of @run(N) mentions (where, for example, @run(7.5) means a run of 7.5km/miles)
• automatically add your progress this week against your goal of getting an average 8 hours @sleep(N) when you log that each day.

Here's an example of what it shows with sparklines:

and without:

# August 2022
**dayoff**: 4
**grounds**: 10
**friends**: 6
**family**: 6
**dogwalk**: 10
**closedrings**: 6
**distance**:  total 208.3 (from 29)
**fruitveg**:  avg 3.9 (from 21)
**run**:  total 24 (from 4)
**sleep**:  avg 6.8 (from 30)
**work**:  total 153.5, avg 7 (from 22)

It starts by asking for the time period you wish to operate over:

When the chosen period (week / month / quarter / year) extends beyond today, dates after today are excluded from the stats.

It asks where to save its output: to a specially-created note in the Summaries folder, or to the current note.

It also offers to write to the current Weekly / Monthly / Quarterly / Yearly notes if you have them enabled in the preferences.

It updates the previous note for that same time period, if it already exists.

The settings for this command are:

• Folders to exclude (in the common set): e.g. 'Summaries', 'TEST'
• Heading level (in the common set): e.g. 3
• Exclude today's entries?
• Folder to store summary notes in: e.g. 'Summaries'
• Stats heading: e.g. 'Period Stats'
• Include sparkline graphs?
• Show hashtag or mention as links?
• Yes/No items: Comma-separated list of #hashtags and/or @mentions to track by 'did I do it this day or not?'. e.g. '#closedrings, #prayed, #tookMeds'
• #hashtags to count: e.g. '#tv, #podcast'
• #hashtags to average: e.g. '#maxHeartRate' -- these are counted and displayed as an average
• #hashtags to total: e.g. '#distance' -- these are counted and displayed as a total
• @mentions to count: e.g. '@work' -- these are counted and displayed with count, total and average
• @mentions to average: e.g. '@sleep, @fruitveg' -- these are counted and displayed as an average
• @mentions to total: e.g. '@distance, @run' -- these are counted and displayed as a total

Why use @run(...) rather than #run(...)? Well, it just felt more right to use @run() as there are already @done(...) and @repeat(...) mentions in use in NotePlan that include a value in the brackets. And in NotePlan, hashtags that end with a decimal number ignore the fractional part (e.g. #run/5.3 ignores the .3) but they are not ignored inside for @run(5.3). However, you can use a #hashtag/value if you don't mind this limitation.

Note: sparklines won't show for periods of time greater than 31 days -- they just get too wide for most devices.

Calling by x-callback

You can run this from an x-callback using the form noteplan://x-callback-url/runPlugin?pluginID=jgclark.Summaries&command=periodStats&arg0=?&arg1=?&arg2=? where

• arg0 is the calendar period code (year, quarter, month, week, today, all (all calendar notes) or an YYYY-MM-DD date)",
• arg1 is the number within the calendar type (ignored for all, today, or YYYY-MM-DD)
• arg2 is the YYYY year number to use (ignored for all, today, or YYYY-MM-DD)
• arg3 (new in v1.0) if given overrides the saved settings with some or all of the following settings, given as a stringified JSON object within { ... }
  • "PSYesNo": ""
  • "PSHashtagsCount": ""
  • "PSHashtagsAverage": ""
  • "PSHashtagsTotal": ""
  • "PSMentionsCount": ""
  • "PSMentionsAverage": ""
  • "PSMentionsTotal": ""
  • "progressChecklistReferenceNote": "