docs: def filter_to(word):
      """
      Decorator to create an output filename from an input filename by
      adding a word onto the stem. in_file is filtered by the function
      and the results are written to out_file. You would want to use
      this over transform_to if you don't know the extension of the file
      going in. This also memoizes the output file.
  
      Takes functions like this to decorate:
      f(in_file, out_dir=None, out_file=None) or,
      f(in_file=in_file, out_dir=None, out_file=None)
  
      examples:
      @filter_to(".foo")
      f("the/input/path/file.sam") ->
          f("the/input/path/file.sam", out_file="the/input/path/file.foo.bam")
  
      @filter_to(".foo")
      f("the/input/path/file.sam", out_dir="results") ->
          f("the/input/path/file.sam", out_file="results/file.foo.bam")
  
      """
  
      def decor(f):
          @functools.wraps(f)
          def wrapper(*args, **kwargs):
              out_file = kwargs.get("out_file", None)
              if not out_file:
                  in_path = kwargs.get("in_file", args[0])
                  out_dir = kwargs.get("out_dir", os.path.dirname(in_path))
                  safe_mkdir(out_dir)
                  out_name = append_stem(os.path.basename(in_path), word)
                  out_file = os.path.join(out_dir, out_name)
              kwargs["out_file"] = out_file
              if not file_exists(out_file):
                  out_file = f(*args, **kwargs)
              return out_file
          return wrapper
      return decor