docs: def upload_freesurfer_archive(self, filename, object_identifier=None, read_only=False):
          """Create an anatomy object on local disk from a Freesurfer anatomy
          tar file. If the given file is a Freesurfer file it will be copied to
          the created subject's upload directory.
  
          Parameters
          ----------
          filename : string
              Name of the (uploaded) file
          object_identifier : string
              Unique object identifier, optional
          read_only : boolean, optional
              Optional value for the read-only property
  
          Returns
          -------
          SubjectHandle
              Handle for created subject in database
          """
          # At this point we expect the file to be a (compressed) tar archive.
          # Extract the archive contents into a new temporary directory
          temp_dir = tempfile.mkdtemp()
          try:
              tf = tarfile.open(name=filename, mode='r')
              tf.extractall(path=temp_dir)
          except (tarfile.ReadError, IOError) as err:
              # Clean up in case there is an error during extraction
              shutil.rmtree(temp_dir)
              raise ValueError(str(err))
          # Find a folder that contains sub-folders 'surf' and 'mri'. These
          # are the only folders we keep in the new anatomy folder. Raise an
          # error if no such folder esists
          freesurf_dir = get_freesurfer_dir(temp_dir)
          if not freesurf_dir:
              # Remove anatomy directory and extracted files
              shutil.rmtree(temp_dir)
              raise ValueError('not a valid subject directory')
          # Create a new identifier. This identifier will be used as the
          # directory name.
          if object_identifier is None:
              identifier = str(uuid.uuid4()).replace('-', '')
          else:
              identifier = object_identifier
          subject_dir = os.path.join(self.directory, identifier)
          # Create the initial set of properties for the new anatomy object. The
          # name is derived from the filename minus any known extensions
          prop_filename = os.path.basename(os.path.normpath(filename))
          prop_name = prop_filename
          # Based on the valid list of suffixes the file is either a tar-file
          # or a zipped tar-file.
          prop_mime = 'application/x-tar' if filename.endswith('.tar') else 'application/x-gzip'
          for suffix in ['.tar', '.tgz', '.tar.gz']:
              if prop_name.endswith(suffix):
                  prop_name = prop_name[:-len(suffix)]
                  break
          properties = {
              datastore.PROPERTY_FILENAME : prop_filename,
              datastore.PROPERTY_FILESIZE : os.path.getsize(filename),
              datastore.PROPERTY_FILETYPE : FILE_TYPE_FREESURFER_DIRECTORY,
              datastore.PROPERTY_MIMETYPE : prop_mime,
              datastore.PROPERTY_NAME : prop_name
          }
          if read_only:
              properties[datastore.PROPERTY_READONLY] = True
          # Create the directory for the anatomy object, the unpacked data files
          # and the original uploaded file (for download).
          os.mkdir(subject_dir)
          data_dir = os.path.join(subject_dir, DATA_DIRECTORY)
          os.mkdir(data_dir)
          upload_dir = os.path.join(subject_dir, UPLOAD_DIRECTORY)
          os.mkdir(upload_dir)
          # Move all sub-folders from the Freesurfer directory to the new anatomy
          # data directory
          for f in os.listdir(freesurf_dir):
              sub_folder = os.path.join(freesurf_dir, f)
              if os.path.isdir(sub_folder):
                  shutil.move(sub_folder, data_dir)
          # Move original upload file to upload directory
          shutil.copyfile(filename, os.path.join(upload_dir, prop_filename))
          # Remove the temp directory
          shutil.rmtree(temp_dir)
          # Use current time in UTC as the object's timestamp
          obj = SubjectHandle(
              identifier,
              properties,
              subject_dir
          )
          self.insert_object(obj)
          return obj