AFNI program: apsearch

Output of -help


A program to perform simple approximate string searching. It's primary
purpose is to test string matching for atlas area locations.

  apsearch <-word WORD> <[-file FILE] | [-text TEXT] | [-phelp PROG]> 
           [OPTIONS]

Parameters:
===========
  -word WORD: WORD being sought
  -w WORD: Abbreviated version of -word WORD
  -file FILE: Search for WORD in text file FILE
  -files FILE1 FILE2 ...: Search for WORD in text files FILE1 FILE2 ...
  -text TEXT: Search for WORD in string TEXT
  -stdin: Search for WORD in text from stdin
  -: Same as -stdin
  -phelp PROG: Search for WORD in output of command PROG -help
  -popt PROG: Search for possible options of PROG that match WORD
              Make sure you add the '-' to WORD if you are looking
              for an actual option.
  -raw_phelp PROG: Spit out the help string for PROG without modification.
  -txt_phelp PROG: Format the output of PROG -help for simple text.
  -sphinx_phelp PROG: Format the output of PROG -help in a sphinxized way.
  -asphinx_phelp PROG: Format the output of PROG -help in an auto sphinxized
                       way.
  -doc_2_txt: Format AFNI markups from  -file/-files/-stdin content for text
              output.
  -doc_2_spx: Format AFNI markups from  -file/-files/-stdin content for
              Sphinx output.
  -hdoc_2_txt PNAME: Format program help output in  -file/-files/-stdin 
              content for text output. PNAME is needed wherever the program
              name is needed in the output.
  -hdoc_2_spx PNAME: Format program help output in  -file/-files/-stdin 
              content for Sphinx output. PNAME is needed wherever the program
              name is needed in the output.
  -hdoc_2_aspx PNAME: Format program help output in  -file/-files/-stdin  
              content for Sphinx output with autoformatting of options.
              PNAME is needed wherever the program name is needed in the 
              output.
              Now, why use such an option as opposed to -asphinx_phelp ?
              That's because the -help option in some programs cannot handle
              any special markup within it so we write out that string as is
              to standard out and pipe it to apsearch with:
              3dinfo -h_raw | apsearch -hdoc_2_aspx 3dinfo -

  -race_check PNAME RMAX: Debugging option to test for race conditions where
              apsearch calls a program which for some reason ends up calling
              it back until you chew up all allowed processes -- not fun --!
              This program will now check for such recursive craziness using
              Rick Reynold's afni_util.py program. To see it in action, 
              create the following script and call it @rory:
                 #!/bin/tcsh -f
                 echo "Called! `date`"
                 apsearch -DSUMA_CountProcs_Verb=YES -race_check `basename $0`

              @rory should be executable and in your path.
              Now run @rory and watch it go.

  -doc_markup_sample: Shown an example of the types of markups available for
                      the documentation.
  -all_afni_help: Search for WORD in all afni help files.
                  This option is not all that clever at the moment.
  -all_popts PROG: TRY to guess at all the options for PROG
                  The list of options is not guaranteed to be full
                  or accurate. It is created by parsing the program's
                  -help output for likely candidates. 
                  It is meant to act as an aid in locating
                  certain options.
  -list_popts PROG: Like -all_popts, but preserve unique set of options
                    only, no chunks of help output are preserved.
  -popts_complete_command PROG: Generate a csh command that can be sourced
                                to allow option autocompletion for program
                                PROG.
                          See also option -bash and -update_all_afni_help
                          See also option -zsh and -update_all_afni_help
  -bash: Use bash format for the complete command. Default is csh/tcsh
         This option MUST PRECEDE option -popts_complete_command
  -zsh: Use zsh format for the complete command. Default is csh/tcsh
         This option MUST PRECEDE option -popts_complete_command
  -ci: Case insensitive search (default)
  -cs: Case sensitive search
  -global_help: Show help for global options.
  -gopts_help:  Show help for global options.
  -max_hits MH: Return best MH hits only. Default MH = 3.
                Use -1 to get all results back.
  -m MH: Abbreviated version of -max_hits MH.
  -min_different_hits mDH: Keep outputting hits until you have dDH
                           dissimilar matches. 
                           Default is -1 (no minimum).
  -unique_hits_only: Restrict output to novel hits only.
  -show_score: Show matching word's distance.
  -show_score_detail: That's right.
  -list_all_afni_progs: List all executables in AFNI's bin directory
  -list_all_afni_P_progs: Same as -list_all_afni_progs but with path
  -list_all_afni_readmes: List all README files in AFNI's bin directory
  -list_all_afni_P_readmes: Same as -list_all_afni_readmes but with path
  -list_all_afni_dsets: List all datasets in AFNI's bin directory
  -list_all_afni_P_dsets: Same as -list_all_afni_dsets but with path
  -update_all_afni_help: Build/update -help output under directory:
                     /home/afniHQ/.afni/help
                  If older help files differ by little they are deleted
                  Little differences would be the compile date or the
                  version number. See @clean_help_dir code for details.
                  This option also creates autocompletion code for 
                  csh/tcsh, bash and zsh shells.
  -recreate_all_afni_help: Like -update_all_afni_help but force receration
                           even if nothing changed in the help
  -afni_help_dir: Print afni help directory location and quit.
  -afni_data_dir: Print afni data directory location and quit.
  -afni_bin_dir: Print afni's binaries directory location and quit.
  -afni_home_dir: Print afni's home directory and quit.
  -afni_rc_file: Pathname to .afnirc. You'll get one even if none exists.
  -afni_custom_atlas_dir: Print your afni's custom atlas directory 
                          and quit.
  -afni_custom_atlas_file: Print your afni's custom atlas file (if any)
                          and quit.
  -afni_text_editor: Print the name of the GUI editor. Priority goes to 
                     env. variable AFNI_GUI_EDITOR, otherwise afni
                     will try to find something suitable.
  -afni_web_browser: Print the name of the browser used by AFNI. 
                     Priority goes to env. variable AFNI_WEB_BROWSER, 
                     otherwise afni will try to find something suitable.
  -afni_web_downloader: Print the name of the downloader used by AFNI. 
                     Priority goes to env. variable AFNI_WEB_DOWNLOADER, 
                     otherwise afni will try to find something suitable.
  -view_text_file FILE: Open FILE with editor of -afni_text_editor
  -view_readme SOMETHING: Find a readme.SOMETHINGISH and open it
  -apsearch_log_file: Print the name of the logfile that is used to save
                      some results of apsearch's functions. This option
                      is for debugging purposes and is only activated if
                      the environment variable AFNI_LOG_BEST_PROG_OPTION
                      is set to YES.
  -view_prog_help PROG: Open the help file for PROG in a GUI editor.
                        This is like the option -hview in C programs.
  -web_prog_help PROG: Open the help file for PROG in a web browser.
                       This is like the option -hweb in C programs.
              Use ALL to view the page containing help for all programs.
  -web_class_docs: Open the webpage with latest class pdfs.

  NOTE: The maximum number of results depends on the combination of
        -max_hits, -min_different_hits, and -unique_hits_only. 
        Without -unique_hits_only, the output will continue 
        while neither -max_hits or -min_different_hits conditions 
        are met.

  -func_test: Run sample function testing and quit. Debugging only.

Wildcard expansion tools:
=========================
-wild_files 'PAT1 PAT2 ...' : Find files matching PAT1, or PAT2, etc.
                              Should include PAT1, etc. between quotes or 
                              the shell will do the expansion for you.
                              Note that in addition to wildcard expansion, 
                              the function also sorts the output so the order
                              is alphabetical. It also dumps duplicate names
                              which can happen when you start to remove 
                              extensions known to AFNI. See -wild* options
                              below.
        Example: -wild_files '*.do *.HEAD'
-wild_files_noAext: After compiling list, remove all known AFNI extensions 
                    and preserve unique set of resultant names
-wild_files_noAext_noAview: After compiling list, remove all known AFNI
                    extensions and any view such as +tlrc, +orig, +acpc, 
                    and preserve unique set of resultant names
-wild_files_orig_name: Output unique list using original (full) filename, 
                       rather than the names after extensions or views were
                       removed. This option makes a difference when using
                       one of -wild_files_noAext* options.
-wild_all_files: Show all files from wildcard expansion. Do not sort, do not
                 trim names, etc.
-wild_files_debug: Output results in debugging mode.
-wild_files_ci: When searching for unique set, use case insensitive matching
-test_unique_str: Run debugging tests for function unique_str().

For hard coders only:
=====================
-C_all_prog_opt_array : Output all program options as an array of C structs.
                        Debugging is output to stderr, the beef is in stdout.
                        Executables not found in the afni binaries directory 
                        (now /home/afniHQ/afni.build/pub.dist/bin/linux_ubuntu_24_64/) will be ignored.
-C_all_append_prog_opt_array: Keep programs already in C struct but no longer
                        in the new list of executables.
-C_prog_opt_array PROG: Insert/update PROG's options in an array of C 
                        and output the results to stdout as for
                        option -C_all_prog_opt_array

            Example:    apsearch -C_prog_opt_array 3dToyProg > prog_opts.c

Examples:
=========
 1- Search help output of program whereami_afni for the word '-atlas'
        apsearch -ci -phelp whereami_afni -word -atlas
 2- Search all atlas area names for some name (mistakes on purpose)
        whereami_afni -show_atlas_code > all_atlas_area_names.txt
        apsearch -file all_atlas_area_names.txt -word hepp
        apsearch -file all_atlas_area_names.txt -word zipp \
                  -min_different_hits 5 -unique_hits_only 
        apsearch -file all_atlas_area_names.txt -word hipp \
                  -min_different_hits 5 -unique_hits_only 
 3- Debug stupid string matcher:
        apsearch -text 'u:Hippocampus' -word hipp -show_score_detail
        apsearch -text 'u:IPC' -word hipp -show_score_detail
 4- Search help of AFNI programs:
        apsearch -phelp afni -word port
        apsearch -phelp 3dSkullStrip -word hull
        apsearch -phelp afni  -word xt
 5- Suggest a valid option from a program:
        apsearch -popt afni -word xt
        apsearch -popt @ROI_Corr_Mat -word sel
        apsearch -popt @ROI_Corr_Mat -word -sel
 6- Show all(*) options for a program:
        apsearch -all_popts 3dSkullStrip
    (*) see -all_popts in help section
 7- Look for some area named something or other in some atlas:
        whereami_afni -show_atlas_code -atlas DKD_Desai_MPM |\
                                apsearch -stdin -word insola
    If you really screw up the spelling, you should help the search
    program a little as in:
        whereami_afni -show_atlas_code -atlas DKD_Desai_MPM |\
                                sed 's/[-_]/ /g' |\
                                apsearch -stdin -word insolent
 8- Find 10 afni programs with something like 'Surface' in their names:
        apsearch -list_all_afni_progs | \
             apsearch -stdin -word surface -max_hits 10
 9- Open the readme for driving AFNI:
        apsearch -view_readme driv
 10- Wildcard expansion and sorting:
        apsearch -wild_files '*.1D*' '*.HEAD *.BRIK*' \
                 -wild_all_files 
        apsearch -wild_files '*.1D*' '*.HEAD *.BRIK*' \
                 -wild_files_noAext_noAview 
        apsearch -wild_files '*.1D*' '*.HEAD *.BRIK*' \
                 -wild_files_noAext_noAview -wild_files_orig_name 

Global Options:
===============


++ Compile date = Oct 31 2024 {AFNI_24.3.06:linux_ubuntu_24_64}
This page auto-generated on Thu Oct 31 09:43:16 PM EDT 2024