d87ef2fb8472135b899fd1a89434033d5895217a
mspeir
  Thu Oct 1 15:31:26 2026 -0700
Add barChartReorder, a utility for changing the order of the bars in a barChart track, refs #37619

The bars of a barChart are drawn in the order their values appear in the
expScores field, and nothing re-sorts them when the track is drawn, so the
order is a property of the data file. Putting the bars in a different order
means rewriting that field in every row, which is awkward enough by hand that
we have twice done it for a data author instead of explaining it. This has
come up on #36998 and #37001.

barChartReorder takes the current bar order and the wanted order as two lists
of names, rewrites expScores in every row, optionally puts a .categories file
into the same order, and prints the barChartBars line for the track. It works
on any barChart BED whatever produced it, so unlike the --groupOrderFile
option of expMatrixToBarchartBed it does not assume the file was built here
from an expression matrix. A bigBarChart is handled by converting it with
bigBedToBed and rebuilding it afterwards, which the usage message spells out.

It refuses to write a half-correct file: the two orders must name the same
bars, every row must hold as many values as there are names, and a .categories
file must have a row for each bar.

Listed in USER_APP_SCRIPTS so it reaches hgdownload, and in the no-argument
branch of mkREADME.sh so the README picks up its usage message rather than the
argparse error that -verbose=2 would produce.

Its tests are also wired into the test target directly. testAll iterates
ALL_APPS, which does not include USER_APP_SCRIPTS, so none of these programs'
tests have ever been reachable from "make test" - that is why the suite sitting
next to expMatrixToBarchartBed never reported it was broken. The makefile
already keeps a short list of directories testAll cannot reach, and this adds
two more to it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

diff --git src/utils/userApps/mkREADME.sh src/utils/userApps/mkREADME.sh
index 85e4c1ef809..6cbdad3eaa7 100755
--- src/utils/userApps/mkREADME.sh
+++ src/utils/userApps/mkREADME.sh
@@ -1,62 +1,62 @@
 #!/bin/sh
 # script to create a FOOTER (or README) file from all usage messages
 #	of binaries found in specified directory
 #
 #========================================================================
 #	$Id: mkREADME.sh,v 1.3 2009/07/31 21:14:03 ann Exp $
 #========================================================================
 #
 usage() {
     echo "usage: mkREADME.sh DESTDIR/BINDIR FOOTER"
     echo "where DESTDIR/BINDIR is where all the binaries are"
     echo "and FOOTER is the name of the result file"
     exit 255
 }
 
 if [ "$#" -ne 2 ]; then
     usage
 fi
 
 DESTDIR=$1
 RESULT=$2
 
 if [ ! -d "${DESTDIR}" ]; then
     echo "ERROR: specified destination directory \"${DESTDIR}\""
     echo "	does not exist."
     usage
 fi
 
 cd "${DESTDIR}"
 
 echo "================================================================
 to download all of the files from one of these admin/exe/ directories,
   for example: admin/exe/linux.x86_64/
     using the rsync command to your current directory:
 
   rsync -aP rsync://hgdownload.soe.ucsc.edu/genome/admin/exe/linux.x86_64/ ./
 
 ================================================================" > "${RESULT}"
 
 # a few of the commands do not understand just a -verbose=2 argument
 # some of those could be fixed TBD
 
 find . -mindepth 1 -type f | grep -v -w hgsql | sed -e "s/^.\///; /mkREADME.sh/d" | sort | \
 while read F
 do
     if [ -x "${F}" ]; then
 	echo "========   ${F}   ===================================="
 	echo "================================================================"
         case "${F}" in
            ucscApiClient|trackDbIndexBb|chromToUcsc|tdbRename|tdbSort)
 	     ./${F} -h < /dev/null
              ;;
-           ameme|aveCols|catUncomment|fetchChromSizes|gmtime|localtime|hgsqldump|pslPairs|qaToQac|bedJoinTabOffset|expMatrixToBarchartBed|webSync|vai.pl|tabFmt)
+           ameme|aveCols|catUncomment|fetchChromSizes|gmtime|localtime|hgsqldump|pslPairs|qaToQac|bedJoinTabOffset|expMatrixToBarchartBed|barChartReorder|webSync|vai.pl|tabFmt)
 	     ./${F} < /dev/null
              ;;
            *)
 	     ./${F} -verbose=2 < /dev/null
         esac
 	echo "================================================================"
 	fi
 done 2>&1 | grep -v "^ERROR:" >> "${RESULT}"