This minor (but critical!) release fixes a bug I recently introduced into NarraFirma’s WordPress PHP code. When you installed NarraFirma and clicked on the “NarraFirma” line on your WordPress dashboard, you might have seen a blank screen, and you might have seen the error “Call to undefined function.” This bug is now fixed. I extend my apologies to anyone who got stuck on it and my thanks to the NF user who reported it.

As always, if you find any bugs, please report them on the GitHub issues page.

This minor release fixes a small bug I noticed while looking back over the blog post from version 1.5.0.

Did you notice it? Go back and look. In the unlumped graph, the two bar counts are 7 and 8. In the lumped graph, the combined count is 17. It should be 15. I can’t believe I didn’t notice that before.

When a person clicks on an answer, creating a dictionary entry, and then clicks the checkbox off again, the dictionary entry is not removed; it’s just set to false. In my new lumping code I accidentally tested whether the dictionary entry existed for the answer, not whether the value both existed and was true. The result was some slightly-off lumped counts, like in the 15-17 example. Sorry. It’s fixed now.

As always, if you find any bugs, please report them on the GitHub issues page.

This minor release adds the option to specify the height (as well as width) of catalysis graphs (onscreen and in the printed report). It is for users who need custom graph sizes in both dimensions.

As always, if you find any bugs, please report them on the GitHub issues page.

This minor release improves NarraFirma’s clustering interface, which is used in planning and catalysis.

1. I removed the row of buttons under the clustering space and replaced it with a things you can do box and a “Do it” button (the same as on the “Explore Patterns” page).

I like making these drop-down boxes because (a) rows of buttons tend to blur together and (b) it’s hard to explain complex tasks in the few words that fit onto buttons.

2. I shrunk the cluster-name bubbles so that they no longer look like containers into which you should place the things you are clustering. That was a mistake on my part. Making those bubbles so big made it seem as if you had to push all of the items in each cluster inside its bubble. But actually, NarraFirma’s clustering algorithm works by connecting each item to the closest cluster name.

So I changed the interface to show connecting lines between items and clusters. Now when you click on an item, NF shows you the closest cluster name with a dashed line, like this.

As you drag the item around, its connecting line will “walk” across the screen, from one cluster name to the next, until you let it go.

When you click on a cluster name, NF will show you which items are connected to it, like this.

So now, as you click and drag items and clusters, you can see how they connect to each other. This should help to speed up the clustering process.

2. You can now reorder the clusters (headings) in your catalysis report using a popup dialog with a list and arrow buttons, instead of by laboriously typing in each order number yourself. That was pretty annoying.

Finally, I found and fixed a few bugs in this release.

Most importantly, NarraFirma will now display any HTML error message it receives in response to an HTTP request. Previously it simply failed to load when it got an HTML response, because it was expecting to receive a JSON response. Now it will show you the HTML error message, and you can post a screenshot. (You could have seen the error message in the debugger before, but now it will be easier to see.)

As always, if you find any bugs, please report them on the GitHub issues page.

This minor release fixes a tiny but important bug in the code that prints catalysis reports. It was causing graphs not to print. Sorry!

This major release adds many improvements to NarraFirma’s capability and usability. Changes in this release are as follows.

Survey improvements

Write-in answer fields

You can now specify a write-in text box to appear after every type of survey question. Using this option you can create an “other” write-in answer after a list of fixed answers, like this.

You can also use the write-in option to add a follow-up question, like this.

Follow-up questions are particularly useful in pilot projects, where you want to find out whether your questions are clear.

Texts entered into write-in fields appear during catalysis in the same way as text questions.

You can also see — and change — write-in answers on the “Review incoming stories” page.

Story collection date

The date on which each story was collected is now automatically added during survey collection. You can also import story collection dates in your CSV file. Based on this, a new generated question, “Collection date,” is available for graphing and statistics. You can group dates by day, month, or year. (To lump dates by week or by any other grouping, use the new display-lumping facility; see below.)

Multiple survey languages

You can now translate your survey into multiple languages. Users will see a list of languages at the top of the survey, and they can choose any language they want to read the survey in.

You can enter translations for each text in your story form using NarraFirma, like this:

Alternatively, you can import a CSV translations file.

The language chosen by each participant is stored in a Language question you can graph and use in statistical tests.

Introductory video

You can now specify an introductory video to be shown at the start of your survey, and you can specify introductory texts to be shown before and after the video.

Image choice answers

You can now specify links to choice images to display under the texts of choices. This applies to questions of the types “radiobuttons” and “checkboxes.”

(Please excuse my testing images; these were just some URLs I had handy…)

Smaller survey improvements

These are some smaller improvements to the surveying capability of NarraFirma:

• For “select” questions, you can now show a full list box instead of a drop-down list.
• For “text” questions, you can now specify the width of the text box (in percentage units).
• You can now say what a drop-down list that has no current selection should say. Formerly it was hard-coded to “– select –“.
• You can now set your own texts for the yes and no options in boolean questions.

Catalysis improvements

Display lumping

Lumping together choice answers is one of the most annoying parts of doing catalysis. (If “catalysis” is a strange word to you: it’s just analysis but without the authoritative conclusions.) In every survey, some of the answers in your fixed lists will be chosen less often than you thought they would be. This is very important in projects with fewer stories, since all of the statistical tests in NarraFirma have minimal data counts on which they will work. The chi-squared test, for example, which looks for significant differences between cell counts in contingency tables, will not run if any of the cell counts are less than five. Hence, lumping together similar answers to create large-enough groups of stories to compare is a requirement in many projects.

In the past, the only way to lump answers together was to export your project data to a CSV file, specify a lumping protocol in your story-form CSV file, and re-import the data. That worked, but it was tedious, and sometimes you had to re-import your data several times before you got the lumping right.

I was upset about this messy solution for a long time. Then, one day, I realized that all of the graphs and statistical tests in NarraFirma ran their data through a single bottleneck where the data was collected from each story and passed on to the testing and graphing functions. I realized that if I was to insert a data lumping manipulation into that bottleneck code, I could lump the data on its way to being used in graphs and tests — without lumping it in its stored form. I tried it; it worked; it’s wonderful.

Display lumping works pretty much like story filtering. You specify your lumping commands on the “Configure catalysis report” page, and your graphs — all of your graphs, and your statistical tests — display the data as specified. For example, this lumping command:

Produces this graph:

You can turn off display lumping on particular graphs (as you can turn off “No answer” answers), in case you want to show people what the answer counts look like with and without lumping.

NOTE: Do you see the bug in these two pictures? 8 and 7 don’t make 17. I didn’t notice it for months. I fixed the bug in version 1.5.4. See that blog post for details.

Improved annotation

I have long been disappointed with the qualitative analysis aspects of NarraFirma. We threw in the annotation facility at the last minute, when we were almost out of time, and I didn’t like how it worked. I never used it. When I needed to add researcher-answered questions to my data, I used a spreadsheet. In this pulse of work on NarraFirma, I finally decided to improve this aspect of the software.

First, I moved annotation from Collection to Catalysis, where it makes more sense. More importantly, I changed annotation so that NF now works more like most qualitative analysis packages. You can now create annotation questions that have no answers to start with, and you can allow the answers to emerge as you read through your stories.

For example, here I am changing one of the answers for an annotation question. When I click “Confirm” to change the answer “Individual” to “One person,” I am changing it in the question and in all of the stories marked with that answer.

This is important, because way back when we first designed NarraFirma, we made a critical mistake. In the data that makes up each story,  answers to choice questions are saved as the actual text of the answer. We should have saved a unique ID for each answer instead. That would have made it easy to rename answers without changing story data. However, we didn’t think of that at the time, and now there is lots of legacy data with answers in place. In a future version of NarraFirma, we may write a converter to transition legacy data to a new UUID-based answer format. But for the time being, this brute-force method of changing answers works. (You may want to back up your data before using it, though.)

I also improved the page on which you annotate stories, thus.

Notice that the annotation questions now appear above the story (and above the answers to other questions). Also, the annotation page now uses a special “mass editing mode” whereby you can move from one story to the next without closing the “item panel” that holds the story. Finally, notice how you can add new answers while you are annotating stories.

I also added some templates for annotation questions, based on what I’ve learned in projects I’ve worked on.

Usability improvements

I’ve been tidying up pages here and there, especially the pages you use to create questions and story forms. For example:

Advanced and import options are now hidden by default.

The panel where you choose what kind of question to ask now has little pictures to show you what the questions will look like.

There are no more fields that ask you to think about what kind of question you are answering (“if this is a slider…”). I figured out how to do that myself, so now NarraFirma only shows you fields that apply to the type of question you have chosen.

On the story-form page, choosing and rearranging questions uses a new “chooser” type interface.

The story-form page also has a clearer distinction between creating, generating, and importing forms, and it has more headers for different parts of the form (“Starting out,” etc).

You can now set a project nickname, which will display on all within-project pages and printed reports.

Finally, the WordPress startup/options page is better looking than it was.

Bug fixes

This release fixes some bugs: one big one, plus several smaller ones.

Better WordPress project archiving

At some point (I cannot remember which release this was in; it may have been within this release cycle), I added a “Delete” button for WordPress projects. It didn’t hide projects as well as I thought it would. (I never meant it to actually delete projects, but I did mean it to hide them well.)

So I went back over the code, fixed the bug, and improved the way it works. Now there is an “Archive” button for each project, which sets an “archived” flag in the project definition. If you check “Edit project permissions directly as JSON,” you can now archive and un-archive projects by changing the value of the “archived” flag. (You can also get back archived projects by creating a new project with exactly the same name.)

I thought long and hard about whether to have a real Delete button, one that would destroy a NarraFirma project in a second. I decided not to do it. In most NarraFirma use cases, projects don’t take up much space on the server. It is only with massive projects that a space-clearing capability is needed. Preserving project data against accidental deletion is a more important requirement for most NF users.

So, to actually delete a WordPress NarraFirma project, you must (a) archive it, (b) entirely remove its definition from the JSON configuration list of project definitions, then (c) use a WordPress plugin to delete the database table associated with the project. There are several such plugins, and they are easy to install and use. For example, “WP Data Access” shows you all of your tables and allows you to “DROP” (delete) them from the WordPress database.

Having to delete the actual database table outside of NarraFirma makes destroying a project just a little bit harder, which reduces the likelihood that people will do it accidentally. (But it’s still pretty easy.)

Smaller bugs

Here are some smaller bugs I fixed in this release.

• The “custom graph size” parameter (added in version 1.4.2), if left empty, could have caused you to see some empty graphs in your printed catalysis report. That is now fixed.
• No-answer answers (where the respondent did not answer the question) were being graphed as “no” for boolean questions and “false” for checkbox questions. I don’t know how long this has been happening, but it’s fixed now.
• Story filters did not work in combination (using &&) on the “Print story cards” page. Now they do. Thanks to a user for pointing out that mistake. (I literally forgot to do it.) Also, while printing story cards, the “Eliciting question” question was showing up if you checked and then unchecked the box. That is now fixed.
• I fixed the problem on the NarraFirma home page where the “Project administration” and other links could sometimes wrap around to the left side of the screen if you had a lot of information showing on the right. (If you have only two story collections, you would never see this problem, but I often have ten or more test collections, and it was annoying.)
• I finally changed every single “var” variable declaration in the code to either a “const” or a “let” declaration. That should firm things up and reduce the probability of scoping errors.
• Somebody mentioned (thank you!) that our code for the Mann-Whitney U test was missing some bug fixes in the scipy version we translated it from. I fixed that. You might see a small difference in calculated U and p values, but it should have a small impact, and it is more correct this way. (For more information, see the code change.)
• In the WordPress version of NarraFirma, the “Reset” project feature set a backup table name longer than WordPress allows. This could have caused you to see some errors when you reset a project. I changed it so that the backup table name replaces the “j” in the usual table name with a “b” instead of what it had been doing (adding the backup date to the end of the table name, which is okay in Node.js but not in WordPress).

Please send bug reports!

I always test as I code, but it is possible that some small bugs are hidden among these new features. Please tell me if you find any. You can submit bug reports and feature requests via the GitHub issues page.

And if you are using NarraFirma, feel free to reach out and tell me (cfkurtz@cfkurtz.com) what you have been doing with it and what you would like to see happen next.

This minor release begins our next pulse of work on NarraFirma, after almost two years away. Hooray! Please see my blog post about the next pulse of work to find out what we plan to do next.

I would have put more changes into this release, but I wanted to release a WordPress version that updated the “tested up to” WordPress version. NarraFirma is not much affected by WordPress update changes, since it only uses the platform as a database back-end. However, I wanted to show WordPress users that NF should still work well for them.

The changes in this release are as follows.

Multi-choice answer limitation

You can now specify a maximum number of answers participants can choose on multi-choice (checkboxes) survey questions.

When a survey-taker checks the maximum number of boxes (two in this example), the other checkboxes become disabled. If they uncheck a checkbox, the other checkboxes become enabled again. I implemented this feature in this low-key way because I hate it when surveys scold me (by popping up a message or turning everything red) for not knowing that I am checking too many options.

To avoid people becoming confused when checkboxes gray out, there is a new story-form field where you can specify what the survey should say on a question with a max-answers limit. By default (if you specify nothing), the story form will say “(Please choose up to # answers.)” after the question text.

Graph changes

I moved the labels on the contingency table graph to the upper right-hand corner. They look better there, and they take up less space.

I also removed the X axis label from bar graphs. It was redundant, since it was the same as the name above the graph, and it also took up space.

Survey improvements

I took a quick look at accessibility in the NarraFirma survey form and made these changes to improve it.

1. I tweaked the default survey colors a little to improve the contrast.
2. I added a set of CSS variables that should make it easier to customize your survey colors using the “custom CSS” field (see the help system on the “Design story forms” page).
3. I improved the responsiveness and spacing of the elements of survey sliders.
4. To the right of each survey slider, there is a little number that shows the value (from zero to 100) the user has set on the slider. If you click on that little number with a mouse, a dialog box pops up in which you can type a new number. Previously there was no way to access that box without a mouse. Now you can Tab to that little number and hit Enter, and the same dialog box will pop up.

Bug fixes

This release also fixes a few bugs:

1. The “Print story cards” button was hidden when advanced options were turned off.
2. The right arrow on the survey slider could get separated from its text.
3. Resizable text boxes could extend beyond the window if it was resized; now they resize only in the vertical dimension.

As always, you can submit bug reports and feature requests via the GitHub issues page. And if you are using NarraFirma, feel free to reach out and tell me (cfkurtz@cfkurtz.com) what you have been doing with it and what you would like to see happen in this next development pulse.

This minor release fixes a small but longstanding bug in the drawing of contingency tables. The expected count for a cell should be its row total times its column total divided by the total of all column totals (or row totals; they are the same number). However, somebody mistakenly divided by the number of stories in the data set. We never noticed the error before because the answer count for most questions is not far below the number of stories. But when one or both of the graphed questions had few answers, the red expected-count circles were drawn smaller than they should have been. This error is now fixed. Note that this was only a graphing error; it did not affect statistical results.

This release improves the catalysis part of NarraFirma even more, both in practical support and in output.

Correlation maps

The new “correlation map” diagram shows relationships among all scale questions in a project, overall or in subsets of stories with particular answers to a choice question. You can hover over nodes to see histogram popups and over links to see scatterplots.

Negative correlations are shown on the left side of the diagram. You can also look at correlation maps for subsets of stories about which people answered questions in different ways.

You can also see the same relationships with straight lines between the questions in a circle, thus:

 

In this case, negative correlations are shown as dashed lines.

CSV graph output

You can now save a CSV version of the data in any graph while looking at it on the “Explore patterns” page (it’s in the “things you can do” list). You can also save CSV data from all the graphs in your catalysis report (choose the “observation graph data as csv” report option).

This should make it easy to reproduce most of the graphs in NarraFirma in your preferred spreadsheet or graphing program. Some of the graphs NarraFirma draws are hard to create in other places, but you can usually graph something useful when you have the numbers in a file.

Remarkable pattern marking

When you do narrative catalysis, it works best to mark all of the patterns you want to consider before you write about them. If you don’t do that, you’ll waste a lot of time writing observations that look stupid after you’ve seen the rest of the patterns. I have been doing this by writing fake observations with texts like “!” and “?” and “x” and so on. However, after several people asked me how they could streamline their catalysis process, I decided that the software should offer a solution to its users. I was wary of making the “Explore patterns” page even more busy, but… this system should make marking observations easier. Now when you are looking at a pattern (graph or series of graphs) you will see this under the graph:

If you think the pattern is remarkable (interesting, worth considering), you can click:

• “yes” to mark the pattern as one you definitely want to write an observation for;
• “maybe” to mark the pattern as one you want to come back to and review later;
• “no” to mark the pattern as one you definitely don’t want to write an observation for;
• “redundant” to mark the pattern as one that does show something important, but is similar to another pattern you have written about;
• or you can just leave the pattern unmarked (for times when you have decided to ignore all patterns related to a particular question or graph type).

This is what it looks like after you click the “yes” button (you can now add observations).

After you have done this for a while, when you look in the list of patterns at the top of the page, you will be able to sort by your markings, thus:

This should help make the catalysis workflow smoother, especially when two or more people are sharing the task. Note that this marking system has no effect whatsoever on the catalysis report. All observations and interpretations that have names and/or descriptions will go into the report, no matter how you have marked them. The marking is only for your own reference.

More pattern display options

That patterns table was getting wider and wider, so I finally made an interface panel where you can choose which columns to show in the table. Only the “Index” (used to be “ID”) column can’t be taken out. Everything else can be made visible or invisible.

I also added a “Notes” column/field to the observation for remembering things you don’t want printed in the report. This will be especially useful if you are working in a group (or forgetful, or both).

Project options page

There is a new “Project options” page under “Project administration,” where we can put project-wide options. At the moment there is only one option in it: the cell delimiter to use in CSV file import and export.

If your spreadsheet insists on saving CSV files with a semicolon or tab delimiter, set this option and NarraFirma will expect it in files it imports and write it out in files it exports. Be careful, though: don’t export in one format and import in another! (If you do, you can use LibreOffice to re-export with a different delimiter.)

Prettier graph types chooser

The graph-types chooser on the “Configure catalysis report” page is now nicer to look at (and hopefully less confusing), with little thumbnail icons you can click on.

I also added a section to the help system (for the “Explore patterns” page) explaining more details about each type of graph.

And that’s the list of changes in this release, aside from little bug fixes and tweaks.

As with previous revisions, this work was funded in part by development commissions. If you would like to help us improve NarraFirma, why not have a look at our NarraFirma commissions list for some ideas?