[GUI Plugin] Action Chains

[capink]

Originally Posted by ownedbycats

Could it be used to, for instance, put the average rating of a category into a custom column for icon rules? (Not sure how it would handle multiple categories though.)

The formulas action already has a "mean" function that should be able to handle things like this. You can combine it with from_search() function to get the desired result. See the help on formulas action for more.

[chaley]

Originally Posted by ownedbycats

Could it be used to, for instance, put the average rating of a category into a custom column for icon rules? (Not sure how it would handle multiple categories though.)

Probably, depending on the details. One would select the category, then iterate through the selection adding the ratings for books in the category. The last step would be a single-field-edit to put the average into a custom column. This process could do multiple categories at the same time by using a tags-like column and for each category putting "category:rating" into the column.

A custom icon rule would extract the category of interest, separate out the rating, then choose the appropriate icon.

[chaley]

Originally Posted by capink

The formulas action already has a "mean" function that should be able to handle things like this. You can combine it with from_search() function to get the desired result. See the help on formulas action for more.

That is a good solution. "from_search" and "for" work together well in this case. Get the list of categories of interest, loop through them searching for books, compute the mean, then construct the result.

[capink]

@chaley: The chain variables action already has a column (the value column) that accepts templates as value. I am thinking about adding the new functionality to this action; by adding a third column with a checkbox. When checked, the template will iterate over all books. I will also make right clicking the value cell pop up the template dialog.

I think that way you can, if you choose, skip the set_globals part because the new value will be automatically re-assigned to the named variable (the name column). Any thoughts?

Edit: set_global would still be used if a user wants to set more than one variable, as in your previous example, but must be sure to choose a different identifier in the chains variable name column.

[capink]

Another thing, does it make sense to persist some variables beyond the lifetime of the current chain? Maybe with additional option, or a certain prefix!

[compurandom]

Is there a reason to clear all the variables every time? Why not just leave them there, and if a chain wants to zero out totals before starting, it should be able to set them all at the start of the chain.

Is that too messy?

[chaley]

Originally Posted by capink

@chaley: The chain variables action already has a column (the value column) that accepts templates as value. I am thinking about adding the new functionality to this action; by adding a third column with a checkbox. When checked, the template will iterate over all books. I will also make right clicking the value cell pop up the template dialog.

This will work well. I have made an example average_rating action using this idea. And yes, opening the template editor is a fine idea.

I think that way you can, if you choose, skip the set_globals part because the new value will be automatically re-assigned to the named variable (the name column). Any thoughts?

You are right. However, someone might want to use a Formula action to see the result before changing the library metadata.

Edit: set_global would still be used if a user wants to set more than one variable, as in your previous example, but must be sure to choose a different identifier in the chains variable name column.

You are right, but I suspect this won't be common. We will see.

[chaley]

This example action computes the average rating for 3 Genres and their children then stores those ratings in a tags-like custom column in the form 'genre name':average_rating.

Here is the complete chain:


It starts by selecting all the books in the library:


It then runs a template to compute the average ratings, saving that value in a chain variable (global):


The template in the chain variables action is:

program:
	genres = 'Comics, Mysteries, Science Fiction';
	res = '';
	for g in genres:
		ratings = from_search('rating', strcat('#genre:"=.', g, '"'));
		total = 0;
		cnt = 0;
		for r in ratings:
			if r != "None" then
				total = add(total, r);
				cnt = add(cnt, 1)
			fi
		rof;
		if cnt ># 0 then
			avg = divide(divide(total, 2), cnt)
		else
			avg = 0
		fi;
		res = list_union(res, strcat(g, ':', avg), ',')
	rof;
	res

I chose to ignore unrated books. If no books are rated then the average is set to zero. One could just as easily put nothing into the result.

@capink:I couldn't get the mean() function to work. How do I convert the result of "from_search()" to an "iterable"?

Next it saves the computed value to a tags-like column:


The template in the Single Field Edit is

program:
	globals(avg_ratings = '');

An example of the output is:

Comics:1.5, Mysteries:2.0, Science Fiction:3.0

Finally it clears the selection:

[chaley]

BTW: there is a bug in the "for" statement. It doesn't strip leading and trailing blanks from list items. The above template uses a fixed version. The bug can be worked around using re() to strip of leading and trailing blanks. Or

g = list_item(g, 0, ',').

[chaley]

Originally Posted by capink

Another thing, does it make sense to persist some variables beyond the lifetime of the current chain? Maybe with additional option, or a certain prefix!

My concern is "mysterious behavior" that depends on a sequence of choices. I am not convinced that action A should affect action B. If it does then there should be something that explicitly declares "action global" variables that persist. Or perhaps the notion of "super actions" that run named actions in a sequence using the same globals dict.

The next question is their lifetime. Do they live for the calibre invocation, while a library is open, while a VL is open, or something else?

[capink]

Originally Posted by chaley

This example action computes the average rating for 3 Genres and their children then stores those ratings in a tags-like custom column in the form 'genre name':average_rating.

Nice work.

Originally Posted by chaley

@capink:I couldn't get the mean() function to work. How do I convert the result of "from_search()" to an "iterable"?

I don't know what exactly is happening. But removing the spaces in the genres like below, makes it work. Will investigate this later:

This is working for me:

program:
	genres = 'Comics,Mysteries,Science Fiction';
	res = '';
	for g in genres:
		ratings = from_search('rating', strcat('#genre:"=.', g, '"'));
		avg = mean(ratings);
		res = list_union(res, strcat(g, ':', avg), ',')
	rof;
	res

Notice that mean discards any non numerical value. If someone wants None values to weigh on the average, modify as follows:

program:
	genres = 'Comics,Mysteries,Science Fiction';
	res = '';
	for g in genres:
		ratings = from_search('rating', strcat('#genre:"=.', g, '"'));
		ratings = re_non_numerical(ratings, 0);
		avg = mean(ratings);
		res = list_union(res, strcat(g, ':', avg), ',')
	rof;
	res

Also there is a bug with the mean function when it is fed an empty list or a list that contains no numerical values. Will fix this in the next release.

Originally Posted by chaley

My concern is "mysterious behavior" that depends on a sequence of choices. I am not convinced that action A should affect action B. If it does then there should be something that explicitly declares "action global" variables that persist. Or perhaps the notion of "super actions" that run named actions in a sequence using the same globals dict.

The next question is their lifetime. Do they live for the calibre invocation, while a library is open, while a VL is open, or something else?

That makes sense. Will leave it as it is for now. Maybe in the future will add a template function to let the user persist whatever he wants.

Edit1: No need to create a template function for that. If a user wants to persist data, he can create an empty book record and use the single field edit to persist data to it.

Edit2: from_search() and from_selection() always return an iterable (comma separated values).

[chaley]

Originally Posted by capink

This is working for me:

[...]

Note that in both cases you must divide the result of mean() by 2, either at the call or later in the list_union. For historical reasons calibre keeps ratings as numbers between 0 and 10. One star == 2, two stars == 4, etc.

The following template does that divide. I also changed the search to include only rated books so that the template can avoid writing xxx:0 if no books with that category are rated.

program:
	genres = 'Comics, Mysteries, Science Fiction';
	res = '';
	for g in genres:
		ratings = from_search('rating', strcat('rating:true and #genre:"=.', g, '"'));
		if ratings then
			avg = divide(mean(ratings), 2);
			res = list_union(res, strcat(g, ':', avg), ',')
		fi
	rof;
	res

Also there is a bug with the mean function when it is fed an empty list or a list that contains no numerical values. Will fix this in the next release.

This is what confused me. I was debugging both the consequences of the extra space in the for loop variable and mean() not working. The extra space meant that the search was empty, triggering the mean() problem you found.

BTW: this is fun, all of figuring out the details of how action chains works, the "logic problem" of how to chain the steps, and constructing templates that compute what is needed. I also am finding some template functions that I might add. One is[list_]count_matching(l, sep, pattern) that returns how many items in l match the pattern.

[chaley]

The fix to the for statement is now in master source.

[capink]

Originally Posted by compurandom

Is there a reason to clear all the variables every time? Why not just leave them there, and if a chain wants to zero out totals before starting, it should be able to set them all at the start of the chain.

Is that too messy?

The variables are not cleared. Every chain runs in a loop of its own, that is garbage collected as soon as the chain ends.

I think as chaley pointed out, it is better not to persist variables because you are going to run into scope problems.

However, the user has the option to persist some variables before exiting the chain. This can be done by creating and empty book and calling it something like 'persistent storage'. You can persist whatever data you want into this book, by using the selection modifier to select it, then the single field edit template option to persist.

[capink]

Originally Posted by chaley

Note that in both cases you must divide the result of mean() by 2, either at the call or later in the list_union. For historical reasons calibre keeps ratings as numbers between 0 and 10. One star == 2, two stars == 4, etc.

I forgot about that.

Originally Posted by chaley

I also changed the search to include only rated books so that the template can avoid writing xxx:0 if no books with that category are rated.

Excluding by search is definitely more elegant.

Originally Posted by chaley

BTW: this is fun, all of figuring out the details of how action chains works, the "logic problem" of how to chain the steps, and constructing templates that compute what is needed. I also am finding some template functions that I might add. One is[list_]count_matching(l, sep, pattern) that returns how many items in l match the pattern.

It is. Hopefully the pattern in the function you are proposing is going to be regex.

Originally Posted by chaley

The fix to the for statement is now in master source.

Good. I will wait a couple of days and go ahead with the changes.