CHANGELOG.rst

This document contains the fslpy release history in reverse chronological order.

3.14.0 (Under development)

Changed

• The sform/qform fields of a .DeformationField instance are automatically set from the reference image if they are not already set (!402).
• Replaced setup.py-based build system with pyproject.toml (!402).
• Tests have been moved into the fsl/tests/ package (!402).

3.13.3 (Monday 17th July 2023)

Changed

• Callback functions registered with .Notifier instances no longer need to accept three arguments (!400).

3.13.2 (Monday 3rd July 2023)

Added

• New scaleAtOrigin option to the .affine.compose function, which allows the origin to be preserved by scaling parameters (!398).

3.13.1 (Tuesday 13th June 2023)

Fixed

• Fixed some minor issues with API documentation (!396).

3.13.0 (Monday 12th June 2023)

Added

• New .runfunc function which can be used to execute a Python function in a separate process (or as a submitted cluster job), via the ~fsl.utils.run.func_to_cmd function (!390).
• New keys(), values(), and items() methods on the .Cache class (!391).

Changed

• The .run.func_to_cmd, .run.hold, and .run.job_output functions have been moved from fsl.utils.fslsub to the fsl.utils.run module (!390).

Deprecated

• The fsl.utils.fslsub module has been deprecated, and scheduled for removal in fslpy 4.0.0 (!390).

3.12.1 (Tuesday 23rd May 2023)

Fixed

• The fsl.scripts.Text2Vest now handles column vector inputs correctly (!387, !388).
• The .tempdir function was not changing back to the original working directory when the override argument was used (!388).

3.12.0 (Friday 19th May 2023)

Added

• New .randomise wrapper function.

Changed

• The .fslmaths wrapper function now allows the -dt and -odt options to be set (!381).
• Assertions (from the .assertions module) called within wrapper functions are now disabled if the command is to be submitted via fsl_sub (!382).
• The .Image class will now resolve symlinks when loading images from file (!383).

Fixed

• The .fslstats wrapper no longer overwrites the log option that is passed to ~.run.run, if a .wrapperconfig context is active (!381).

3.11.3 (Thursday 2nd March 2023)

Fixed

• Fixed another bug in the .dcm2niix function (!379).

3.11.2 (Monday 27th February 2023)

Fixed

• Fixed a bug in the .dcm2niix function (!376).
• Adjusted the .imrm and .imglob scripts to support incomplete wildcard patterns (e.g. img_?? matching img_01.nii.gz) (!377).

3.11.1 (Friday 24th February 2023)

Added

• New .featquery wrapper function (!374).

Fixed

• fixed the .fslstats wrapper to handle index masks (the -K option) with missing label values (!374).

3.11.0 (Monday 20th February 2023)

Added

• New .standard_space_roi, .fslswapdim, .fslmerge, .fslsplit, fslselectvols, and .fslcpgeom wrapper functions (!351, !354, !364).
• New fsl.wrappers.first wrapper functions (!355).
• New fsl.wrappers.bianca and fsl.wrappers.avwutils wrapper functions (!358).
• New fsl.wrappers.bedpostx and ~.wrappers.dtifit wrapper functions (!364).
• New ~fsl.wrappers.feat.feat, ~.melodic.fsl_regfilt and ~.melodic.fsl_glm wrapper functions (!364).
• New .oxford_asl and asl_file wrapper functions (!368).
• New .wrapperconfig context manager function, which allows the default values for arguments passed by the fsl.wrappers functions to the fsl.utils.run.run function to be changed (!352, !356).
• New .affine.mergeBounds function (!360).

Changed

• The fsl.wrappers.fslmaths.fslmaths and fsl.wrappers.fslstats.fslstats wrapper functions have been updated to accept arguments destined for fsl.utils.run.run (!352).
• .Mesh objects can now be created without indices/triangles - they can be assigned after creation (!360).
• The .dicom module will now preferentially call $FSLDIR/bin/dcm2niix, instead of calling the first dcm2niix on the $PATH (!365).
• The .applyArgStyle argmap argument can now be a callable which defines a rule which will be applied to all argument names (!366).
• The .applyArgStyle valmap argument now accepts a new EXPAND_LIST option, which allows sequences to be expanded as separate command-line options (!366).
• .Image objects can now be created without passing a nibabel.Nifti1Image (or similar) object, as long as a nibabel.Nifti1Header and a .DataManager are provided (!362).

Fixed

• Fixed a bug in the .Image.strval method (!353).

3.10.0 (Wednesday 29th June 2022)

Added

• New fsl.wrappers.eddy.eddy function, to replace .eddy_cuda. Note that this function will not work with FSL versions 6.0.5.2 or older (!348).

Deprecated

• The fsl.wrappers.eddy.eddy_cuda function has been deprecated in favour of the eddy function (!348).

3.9.6 (Wednesday 15th June 2022)

Added

• The .fslmaths wrapper now supports the -roi option, via the .fslmaths.roi method (!346).

3.9.5 (Thursday 2nd June 2022)

Changed

• Updated the .ensureIsImage function to support pathlib.Path objects (!343).

Fixed

• Some fixes in the .wrappers module (specifically in the .FileOrThing class) to better support pathlib.Path objects (!343).

3.9.4 (Friday 27th May 2022)

Changed

• Changed the behaviour of .Image.__getitem__ so that, if image data is accessed with a boolean mask array (e.g. image[mask > 0]), the image data is loaded into memory (!341).

3.9.3 (Friday 27th May 2022)

Fixed

• Fixed an issue in the ~.fslsub.func_to_cmd function (!339).

3.9.2 (Friday 20th May 2022)

Changed

• Added the .NIFTI_XFORM_TEMPLATE_OTHER identifier, an extension to the NIfTI standard (!337).

3.9.1 (Friday 13th May 2022)

Changed

• Adjusted the .applyArgStyle function so that it allows separate specification of the style to use for single-character arguments. This fixes some usage issues with commands such as FSL fast, which have regular --= arguments, but also single-character arguments which expect multiple positional values (!335).

3.9.0 (Tuesday 12th April 2022)

Added

• New .Image.niftiDataTypeSize method, which reports the number of bits per voxel, according to the NIfTI data type (!327).

Changed

• The .Image class no longer uses an .ImageWrapper to manage data access and assignment (!327).
• Semantics for accessing and modifying image data have changed. By default, image data access is now delegated to the underlying nibabel.Nifti1Image object (and so remains on disk by default). Image data can be loaded into memory by accessing the .Image.data property, or by modifying the data through .Image.__setitem__ (!327).
• The ~.fslsub.func_to_cmd function now uses dill instead of pickle for serialisation (!328).

Fixed

• Fixes to the .melodic and .eddy wrapper functions.

Deprecated

• The .imagewrapper module (and the .ImageWrapper class) is being migrated to FSLeyes (!327).
• The loadData, calcRange, and threaded arguments to the .Image class are deprecated and no longer have any effect (!327).
• The .Nifti.mapIndices method is deprecated (!327).
• The .Image.getImageWrapper, .Image.calcRange and .Image.loadData methods are deprecated and no longer have any effect (!327).

3.8.2 (Tuesday 15th February 2022)

Fixed

• The the .topup wrapper function now allows multiple file names to be passed to the --imain argument (!324).

3.8.1 (Tuesday 28th December 2021)

Fixed

• The .melodic wrapper function no longer requires its input argument to be a NIFTI image or file (!321).

3.8.0 (Thursday 23rd December 2021)

Added

• New .fslorient wrapper function (!315).
• The .Bitmap class has basic support for loading JPEG2000 images (!316).

Fixed

• Fixed an issue with API documentation generation (!317).

3.7.1 (Friday 12th November 2021)

Changed

• BIDS and dcm2niix .json sidecar files with control characters are now accepted (!312).

Fixed

• Fixed an issue with temporary input files created by fsl.wrappers functions not being deleted (!313).

3.7.0 (Friday 20th August 2021)

Added

• New fsl.wrappers.fsl_sub wrapper function for the fsl_sub command (!309).

Changed

• Performance of the .imglob, .imln, imtest, .imrm and .remove_ext scripts has been improved, by re-organising them to avoid unnecessary and expensive imports such as numpy (!310).
• The default behaviour of the fsl.utils.run.run function (and hence that of all fsl.wrappers functions) has been changed so that the standard output and error of the called command is now forwarded to the calling Python process, in addition to being returned from run as strings. In other words, the default behaviour of run('cmd'), is now equivalent to run('cmd', log={"tee":True}). The previous default behaviour can be achieved with run('cmd', log={"tee":False}) (!309).
• The fsl.utils.run.run and fsl.utils.run.runfsl functions (and hence all fsl.wrappers functions) have been modified to use fsl.wrappers.fsl_sub instead of fsl.utils.fslsub.submit. This is an internal change which should not affect the usage of the run, runfsl or wrapper functions (!309).

Deprecated

• fsl.utils.fslsub.SubmitParams and fsl.utils.fslsub.submit have been deprecated in favour of using the fsl.wrappers.fsl_sub wrapper function (!309).
• The fsl.utils.fslsub.info function has been deprecated in favour of using the fsl_sub.report function, from the separate fsl_sub Python library (!309).

3.6.4 (Tuesday 3rd August 2021)

Added

• New .epi_reg wrapper function (!306).
• New .fslmaths.kernel and .fslmaths.fmeanu options on the .fslmaths wrapper (!304).

3.6.3 (Wednesday 28th July 2021)

Changed

• When creating an Image object with loadData=False, the calcRange argument is ignored, as it would otherwise cause the data to be loaded (!301).

3.6.2 (Wednesday 23rd June 2021)

Changed

• The fsl.wrappers.fast wrapper passes -v to fast if v=True or verbose=True is specified.

3.6.1 (Thursday 27th May 2021)

Changed

• Removed the dataclasses backport from requirements (!297).

3.6.0 (Monday 19th April 2021)

Changed

• The fslpy API ocumentation is now hosted at https://open.win.ox.ac.uk/pages/fsl/fslpy (!290).
• The fsl and fsl.scripts packages have been changed from being pkgutil-style namespace packages to now being native namespace packages (!290).
• The .TaskThread now allows an error handler function to be specified, which is run on the .idle loop (!283).
• The .bids.loadMetadata function no long resolves sym-links when determining whether a file is contained within a BIDS data set (!287).
• The .Image class can now be created from a pathlib.Path object (!292).
• Some functions in the .path module can now be used with pathlib.Path objects (!293).

Deprecated

• Deprecated a number of GUI-specific properties in the fsl.utils.platform module, including frozen, haveGui, canHaveGui, inSSHSession, inVNCSession, wxPlatform, wxFlavour, glVersion, glRenderer, and glIsSoftwareRenderer. Equivalent functions are being added to the fsleyes-widgets library (!285).
• The fsl.utils.filetree package has been deprecated, and will be removed in a future version of fslpy - it is now published as a separate library on [PyPI](https://pypi.org/project/file-tree/) (!286).

Fixed

• Fixed an edge-case in the .gifti module, where a surface with a single triangle was being loaded incorrectly (!288).
• Fixed an issue in the ~.fslsub.func_to_cmd function, where it was unintentionally leaving flie handles open (!291).

3.5.3 (Tuesday 9th February 2021)

Fixed

• Fixed a bug in .featanalysis.loadClusterResults (!281).

3.5.2 (Friday 29th January 2021)

Fixed

• Adjusted the .dicom.scanDir function so that it will set a default value for SeriesDescription if it is not present in the dcm2niix json output (!279).
• Fixed some issues with API documentation generation (!279).

3.5.1 (Thursday 21st January 2021)

Added

• New .featanalysis.loadFsf function, for loading arbitrary .fsf files (!276).

Fixed

• Adjustments to .dicom tests to work with different versions of dcm2niix (!277).

3.5.0 (Wednesday 20th January 2021)

Added

• New fsl_anat.tree, for use with the ~fsl.utils.filetree package (!264).
• New .fsl_prepare_fieldmap wrapper function (!265).
• The .fslmaths wrapper now supports the fslmaths -s option via the .fslmaths.smooth method (!271).

Fixed

• Windows/WSL-specific workaround to the fsl.utils.run.run function to avoid console windows from popping up, when used from a graphical program (!272).

3.4.0 (Tuesday 20th October 2020)

Added

• New .tbss wrapper functions for TBSS commands.

Changed

• Calls to functions in the .assertions module are disabled when a wrapper function is called with cmdonly=True.

3.3.3 (Wednesday 13th October 2020)

Changed

• The .fileOrImage (and related) decorators will not manipulate the return value of a decorated function if an argument cmdonly=True is passed. This is so that wrapper functions will directly return the command that would be executed when cmdonly=True.

3.3.2 (Tuesday 12th October 2020)

Changed

• Most .wrapper functions now accept an argument called cmdonly which, if True, will cause the generated command-line call to be returned, instead of executed.

3.3.1 (Thursday 8th October 2020)

Changed

• The .affine.decompose and .affine.compose functions now have the ability to return/accept shear components.

Fixed

• Fixed a bug in the .affine.decompose function which was corrupting the scale estimates when given an affine containing shears.

3.3.0 (Tuesday 22nd September 2020)

Added

• New ported versions of various core FSL tools, including imrm, imln, imtest, fsl_abspath, remove_ext, Text2Vest, and Vest2Text.
• New .gps function, wrapping the FSL gps command.
• New .vest.loadVestFile and .vest.generateVest functions.

Changed

• Updates to the BIDS filetree specification.

Fixed

• The .CoefficientField class now works with alternate reference images (i.e. a reference image with different dimensions to that which was originally used when the non-linear transformation was calculated).

3.2.2 (Thursday 9th July 2020)

Changed

• The .fslsub.func_to_cmd function allows more fine-grained control over whether the script file is removed after the job has finished running.

3.2.1 (Tuesday 23rd June 2020)

Changed

• Minor updates to documentation.

3.2.0 (Thursday 11th June 2020)

Added

• A new .fslsub.hold function to wait on previously submitted jobs, to be used in place of the wait function.

Removed

• The .fslsub.wait (and .run.wait) function has been removed, as repeated calls to qstat can adversely affect the cluster job submission system.

3.1.0 (Thursday 21st May 2020)

Added

• New .cifti module, providing classes and functions for working with CIFTI data.
• New .winpath and wslpath functions for working with paths when using FSL in a Windows Subsystem for Linux (WSL) environment.
• New .wslcmd function for generating a path to a FSL command installed in a WSL environment.
• New .Platform.fslwsl attribute for detecting whether FSL is installed in a WSL environment.
• New .Image.niftiDataType property.
• The .FileTree class has been updated to allow creation of deep copies via the new .FileTree.copy method.

Changed

• .Image objects created from numpy arrays will be NIFTI1 or NIFTI2, depending on the value of the $FSLOUTPUTTYPE environment variable.

Fixed

• Updated the .fast wrapper to support some single-character command-line flags.

3.0.1 (Wednesday 15th April 2020)

Changed

• The .isMelodicDir function now accepts directories that do not end with .ica, as long as all required files are present.
• Added the dataclasses backport, so fslpy is now compatible with Python 3.6 again.

3.0.0 (Sunday 29th March 2020)

Added

• New wrapper functions for the FSL .fslstats, .prelude and applyxfm4D commands.
• New firstDot option to the .path.getExt, .path.removeExt, and .path.splitExt, functions, offering rudimentary support for double-barrelled filenames.
• The .nonlinear.applyDeformation function now accepts a premat affine, which is applied to the input image before the deformation field.
• New .SubmitParams class, providing a higer level interface for cluster submission.
• New .FileTree.load_json and .FileTree.save_json methods.

Changed

• fslpy now requires a minimum Python version of 3.7.
• The default value for the partial_fill option to .FileTree.read has been changed to False. Accordingly, the .FileTreeQuery calls the .FileTree.partial_fill method on the FileTree it is given.
• The .gifti.relatedFiles function now supports files with BIDS-style naming conventions.
• The .run.run and .run.runfsl functions now pass through any additional keyword arguments to subprocess.Popen or, if submit=True, to fslsub.submit.
• The .fslsub.submit function now accepts an env option, allowing environment variables to be specified.
• The .run.runfsl function now raises an error on attempts to run a command which is not present in $FSLDIR/bin/ (e.g. ls).
• The .bids module has been updated to support files with any extension, not just those in the core BIDS specification (.nii, .nii.gz, .json, .tsv).
• The return value of a function decorated with .fileOrImage, .fileOrArray, or .fileOrText is now accessed via an attribute called stdout, instead of output.
• Output files of functions decorated with .fileOrImage, .fileOrArray, or .fileOrText, which have been loaded via the .LOAD symbol, can now be accessed as attributes of the returned results object, in addition to being accessed as dict items.
• Wrapper functions decorated with the .fileOrImage, .fileOrArray, or .fileOrText decorators will now pass all arguments and return values through unchanged if an argument called submit is passed in, and is set to True (or any non-False value). Furthermore, in such a scenario a ValueError will be raised if any in-memory objects or LOAD symbols are passed.
• The .fileOrText decorator has been updated to work with input values - file paths must be passed in as pathlib.Path objects, so they can be differentiated from input values.
• Loaded .Image objects returned by fsl.wrappers functions are now named according to the wrapper function argument name.

Fixed

• Updated the .prepareArgs function to use shlex.split when preparing shell command arguments, instead of performing a naive whitespace split.
• Fixed some bugs in the .fslsub.info and .fslinfo.wait functions.
• Fixed the .DeformationField.transform method so it works with a single set of coordinates.
• .Image creation does not fail if loadMeta is set, and a sidecar file containing invalid JSON is present.

Removed

• Removed the deprecated .StatisticAtlas.proportions, .StatisticAtlas.coordProportions, and .StatisticAtlas.maskProportions methods.
• Removed the deprecated indexed option to .Image.__init__.
• Removed the deprecated .Image.resample method.
• Removed the deprecated .image.loadIndexedImageFile function.
• Removed the deprecatd .FileTreeQuery.short_names and .Match.short_name properties.
• Removed the deprecated .idle.inIdle, .idle.cancelIdle, .idle.idleReset, .idle.getIdleTimeout, and .idle.setIdleTimeout functions.
• Removed the deprecated resample.calculateMatrix function.

2.8.4 (Monday 2nd March 2020)

Added

• Added a new partial_fill option to .FileTree.read, which effectively eliminates any variables which only have one value. This was added to accommodate some behavioural changes that were introduced in 2.8.2.

2.8.3 (Friday 28th February 2020)

Fixed

• Fixed a bug in the .Image.save method.

2.8.2 (Thursday 27th February 2020)

Fixed

• Fixed some subtle bugs in the .filetree.utils.get_all function.

2.8.1 (Thursday 20th February 2020)

Fixed

• Fixed a bug where an error would be raised on attempts to load an image file without a BIDS-compatible name from a BIDS-like directory.

2.8.0 (Wednesday 29th January 2020)

Added

• New .Nifti.adjust method, for creating a copy of a .Nifti header with adjusted shape, pixdims, and affine. This can be useful for creating a resampling reference.
• New .affine.rescale function, for adjusting a scaling matrix.
• New .mghimage.voxToSurfMat function, for creating a voxel-to-freesurfer affine transform from any image.

Changed

• The .ImageWrapper now maintains its own image data cache, rather than depending on nibabel.
• Internal changes to avoid using the deprecated nibabel.dataobj_images.DataobjImage.get_data method.

Fixed

• Improved the algorithm used by the .mesh.needsFixing function.
• The .fslmaths.run method now accepts .wrappers.LOAD as an output specification.
• Fixed a bug in the .Mesh class to prevent indices from being loaded as floating point type.
• Fixed a bug in the .resample function.
• Fixed a bug in the .MGHImage class, which was causing pixdims to be overridden by scales derived from the affine.

Deprecated

• .calculateMatrix - its functionality has been moved to the .affine.rescale function.

2.7.0 (Wednesday 6th November 2019)

Added

• New until option to the .idle.block function.
• New .Idle.neverQueue setting, which can be used to force all tasks passed to .idle.idle to be executed synchronously.
• New .IdleLoop.synchronous context manager, to temporarily change the value of .IdleLoop.neverQueue.
• New .bids module, containing a few simple functions for working with BIDS datasets.
• New .image.loadMetadata function, and loadMeta option to the .Image class, to automatically find and load any sidecar JSON files associated with an image file.

Changed

• Internal reorganisation in the .idle module.

Fixed

• Fixed incorrect usage of setuptools.find_packages, which was causing unit tests to be installed.

Deprecated

• .idle.inIdle - replaced by .IdleLoop.inIdle.
• .idle.cancelIdle - replaced by .IdleLoop.cancelIdle.
• .idle.idleReser - replaced by .IdleLoop.idleReset.
• .idle.getIdleTimeout - replaced by .IdleLoop.callRate.
• .idle.setIdleTimeout - replaced by .IdleLoop.callRate.

2.6.2 (Monday 7th October 2019)

Changed

• Added a debugging hook in the .idle module.
• The .fslsub.submit function is now more flexible in the way it accepts the command and input arguments.
• The .run.prepareArgs function has been renamed (from _prepareArgs).

2.6.1 (Thursday 19th September 2019)

Changed

• fslpy is no longer tested against Python 3.5, and is now tested against Python 3.6, 3.7, and 3.8.

2.6.0 (Tuesday 10th September 2019)

Added

• New .Image.iscomplex attribute.
• Support for a new Statistic atlas type.

Changed

• The .Cache class has a new lru option, allowing it to be used as a least-recently-used cache.
• The fsl.utils.filetree module has been refactored to make it easier for the .query module to work with file tree hierarchies.
• The .LabelAtlas.get method has a new binary flag, allowing either a binary mask, or a mask with the original label value, to be returned.
• The .dicom module has been updated to work with the latest version of dcm2niix.

Deprecated

• .ProbabilisticAtlas.proportions, .ProbabilisticAtlas.maskProportions, and .ProbabilisticAtlas.labelProportions have been deprecated in favour of .StatisticAtlas.values, .StatisticAtlas.maskValues, and .StatisticAtlas.labelValues

2.5.0 (Tuesday 6th August 2019)

Added

• New .Image.getAffine method, for retrieving an affine between any of the voxel, FSL, or world coordinate systems.
• New fsl.transforms package, which contains classes and functions for working with linear and non-linear FLIRT and FNIRT transformations.
• New static methods .Nifti.determineShape, .Nifti.determineAffine, .Nifti.generateAffines, and .Nifti.identifyAffine.
• New prototype fsl.transforms.x5 module, for reading/writing linear and non-linear X5 files (preliminary release, subject to change).
• New prototype .fsl_convert_x5 .fsl_apply_x5 programs, for working with X5 transformations (preliminary release, subject to change).

Changed

• The .vest.looksLikeVestLutFile function has been made slightly more lenient.
• h5py has been added to the fslpy dependencies.

Deprecated

• The fsl.utils.transform module has been deprecated; its functions can now be found in the fsl.transforms.affine and fsl.transform.flirt modules.

2.4.0 (Wednesday July 24th 2019)

Added

• New .image.roi module, for extracting an ROI of an image, or expanding its field-of-view.

Changed

• The .resample_image script has been updated to support resampling of images with more than 3 dimensions.

2.3.1 (Friday July 5th 2019)

Fixed

• The .Bitmap class now supports greyscale images and palette images.

2.3.0 (Tuesday June 25th 2019)

Added

• New .Bitmap class, for loading bitmap images. The .Bitmap.asImage method can be used to convert a Bitmap into an .Image.
• The .Image class now has support for the RGB24 and RGBA32 NIfTI data types.
• New .Image.nvals property, for use with RGB24/RGBA32 images.
• New .LabelAtlas.get and ProbabilisticAtlas.get methods, which return an .Image for a specific region.
• The .AtlasDescription.find method also now a name parameter, allowing labels to be looked up by name.
• New .FileTree.defines and .FileTree.on_disk methods, to replace the .FileTree.exists method.

Fixed

• The .makeWriteable function will always create a copy of an array if its base is a bytes object.
• Fixed a bug in the .GitfitMesh.loadVertices method.
• Fixed a bug in the .Mesh.addVertices method where the wrong face normals could be used for newly added vertex sets.

2.2.0 (Wednesday May 8th 2019)

Added

• New .resample_image script.
• New .resample module (replacing the .Image.resample method), containing functions to resample an .Image.
• New .resample.resampleToPixdim and .resample.resampleToReference functions, convenience wrappers around .resample.resample.
• New .idle.block function.

Changed

• The .resample function (formerly .Image.resample) now accepts origin and matrix parameters, which can be used to adjust the alignment of the voxel grids of the input and output images.
• The .transform.decompose function now accepts both (3, 3) and (4, 4) matrices.

Fixed

• Minor fixes to some .filetree.filetree tree definitions.

Deprecated

• The .Image.resample method has been deprecated in favour of the .resample.resample function.

2.1.0 (Saturday April 13th 2019)

Added

• New tensor conversion routines in the ~fsl.data.dtifit module (Michiel Cottaar).
• New .makeWriteable function which ensures that a numpy.array is writeable, and creates a copy if necessary

Changed

• The .GiftiMesh class no longer creates copies of the mesh vertex/index arrays. This means that, these arrays will be flagged as read-only.
• The .Mesh class handles vertex data sets requiring different triangle unwinding orders, at the cost of potentially having to store two copies of the mesh indices.

Fixed

• The .FeatDesign class now handles "compressed" voxelwise EV files, such as those generated by PNM.

2.0.1 (Monday April 1st 2019)

Fixed

• Fixed a bug with the .gifti.relatedFiles function returning duplicate files.

2.0.0 (Friday March 20th 2019)

Added

• New fsl.utils.filetree package for defining and working with file/directory templates (Michiel Cottaar).
• Simple built-in .deprecated decorator.
• New fsl.data.utils module, which currently contains one function .guessType, which guesses the data type of a file/directory path.
• New .commonBase function for finding the common prefix of a set of file/directory paths.

Changed

• Removed support for Python 2.7 and 3.4.
• Minimum required version of nibabel is now 2.3.
• The .Image class now fully delegates to nibabel for managing file handles.
• The .GiftiMesh class can now load surface files which contain vertex data, and will accept surface files which end in .gii, rather than requiring files which end in .surf.gii.
• The name property of .Mesh instances can now be updated.

Removed

• Many deprecated items removed.

Deprecated

• Deprecated the .loadIndexedImageFile function, and the indexed flag to the .Image constructor.

1.13.3 (Friday February 8th 2019)

Fixed

• Fixed an issue with the .dicom.loadSeries using memory-mapping for image files that would subsequently be deleted.
• Fixed an issue in the .GiftiMesh class, where numpy/nibabel was returning read-only index arrays.

1.13.2 (Friday November 30th 2018)

Changed

• The .Image.resample method now supports images with more than three dimensions.
• The fsl.utils.fslsub.submit now returns the job-id as a string rather than a one-element tuple. It now also accepts a nested sequence of job ids rather than just a flat sequence. This will also changes the output from the function wrappers in fsl.wrappers if submitted.

Fixed

• Fix to the .ImageWrapper regarding complex data types.

1.13.1 (Friday November 23rd 2018)

Fixed

• Added a missing image attribute in the .VoxelwiseConfoundEV class.
• Make sure that FEAT Cluster objects (created by the .loadClusterResults function) contain p and logp attributes, even when cluster thresholding was not used.

1.13.0 (Thursday 22nd November 2018)

Added

• New wrapper functions for .fsl_anat, .applytopup (Martin Craig).
• New .fileOrText decorator for use in wrapper functions (Martin Craig).

Changed

• Various minor changes and enhancements to the FSL function .wrappers interfaces (Martin Craig).

Fixed

• The immv and imcp scripts now accept incorrect file extensions on input arguments.

1.12.0 (Sunday October 21st 2018)

Changed

• The extract_noise script has been renamed to .fsl_ents.
• Increased the minimum required version of dcm2niix in the fsl.data.dicom module.

Deprecated

• The extract_noise script.

1.11.1 (Friday September 14th 2018

Fixed

• Fixed a Python 2 incompatibility in the .settings module.

1.11.0 (Thursday September 13th 2018)

Added

• A couple of new convenience functions to the .settings module.

Changed

• Development (test and documentation dependencies) are no longer listed in setup.py - they now need to be installed manually.
• Removed conda build infrastructure.

1.10.3 (Sunday September 9th 2018)

Added

• The .parseVersionString function accepts (and ignores) local version identifer strings.

1.10.2 (Friday September 7th 2018)

Fixed

• The .Image.save method was not handling memory-mapped images correctly.

1.10.1 (Friday August 3rd 2018)

Changed

• Minor adjustmenets to improve Windows compatibility.

Fixed

• The .FEATImage.getCOPE method was returning PE images.

1.10.0 (Wednesday July 18th 2018)

Added

• A new script, .extract_noise, which can be used to extract ICA component time courses from a MELODIC ICA analysis.
• New .path.allFiles function which returns all files underneath a directory.
• The .fileOrImage and .fileOrArray decorators now support loading of files which are specified with an output basename.
• New .fast wrapper function for the FSL FAST tool.

Changed

• When using the .run.run function, the command output/error streams are now forwarded immediately.
• Removed dependency on pytest-runner.

1.9.0 (Monday June 4th 2018)

Added

• New .Image.data property method, for easy access to image data as a numpy array.
• New log option to the .run.run function, allowing more fine-grained control over sub-process output streams.
• New .Platform.fsldevdir property, allowing the $FSLDEVDIR environment variable to be queried/changed.

Changed

• .Image.ndims has been renamed to .Image.ndim, to align more closely with numpy naming conventions.
• The err and ret parameters to the .run.run function have been renamed to stderr and exitcode respectively.
• The .runfsl function will give priority to the $FSLDEVDIR environment variable if it is set.

Deprecated

• .Image.ndims.
• The err and ret parameters to .run.run.

1.8.1 (Friday May 11th 2018)

Changed

• The .fileOrImage decorator function now accepts .Image objects as well as nibabel image objects.

1.8.0 (Thursday May 3rd 2018)

Added

• New .wrappers package, containing wrapper functions for a range of FSL tools.
• New fsl.utils.run module, to replace the fsl.utils.callfsl module.
• New fsl.utils.fslsub module, containing a .fslsub.submit function which submits a cluster job via fsl_sub.
• Assertions (in the .assertions module) can be disabled with the new .assertions.disabled context manager.
• New fsl.utils.parse_data module containing various neuroimaging data constructors for use with argparse.
• The .memoize.skipUnchanged decorator has an invalidate function which allows its cache to be cleared.

Changed

• The .tempdir function has an option to not change to the newly created directory.

Deprecated

• The fsl.utils.callfsl module (replaced with fsl.utils.run).

1.7.2 (Monday March 19th 2018)

Added

• Added the .MGHImage.voxToSurfMat and related properties, giving access to the voxel-to-surface affine for an MGH image.

1.7.1 (Monday March 12th 2018)

Changed

• Adjusted .parseVersionString so it accepts .dev* suffixes.

Fixed

• Removed deprecated use of .imagewrapper.canonicalShape.

1.7.0 (Tuesday March 6th 2018)

Added

• The fsl.utils.assertions module contains a range of functions which can be used to assert that some condition is met.
• The fsl.utils.ensure module contains a range of functions (currently just one) which can be used to ensure that some condiution is met.

Changed

• The .settings module now saves its files in a format that is compatible with Python 2 and 3.
• The .tempdir function now accepts a root argument, which specifies the location in which the temporary directory should be created.
• An image's data source can now be set via .Image.__init__.
• .MGHImage objects now have a .MGHImage.save method.
• Adjustments to the conda package build and deployment process.
• The .ImageWrapper.canonicalShape function has been moved to the .data.image class.
• The .ImageWrapper.naninfrange function has been moved into its own .naninfrange module.

Fixed

• Fixed a bug in the .MutexFactory class.

Deprecated

• .ImageWrapper.canonicalShape (moved to the .data.image module)
• .ImageWrapper.naninfrange function (moved to the .naninfrange module)

1.6.8 (Monday February 12th 2018)

• The atlasq, immv, imcp and imglob scripts suppress some warnings.

1.6.7 (Friday February 9th 2018)

• More further adjustments to the conda package build.
• Adjustments to pypi source distribution - the requirements-extra.txt file was not being included.

1.6.6 (Thursday February 8th 2018)

• Further adjustments to the conda package build.

1.6.5 (Tuesday February 6th 2018)

• Adjustments to the conda package build.

1.6.4 (Monday February 5th 2018)

• The .platform module emits a warning if it cannot import wx.

1.6.3 (Friday February 2nd 2018)

• Minor enhancements to the .WeakFunctionRef class.
• Some bugfixes to the fsl.utils.imcp module, with respect to handling relative path names, moving file groups (e.g. .img/.hdr pairs), and non-existent directories.

1.6.2 (Tuesday January 30th 2018)

• Updates to the conda installation process.
• A new script is installed when fslpy is installed via pip or conda - atlasquery, which emulates the FSL atlasquery tool.

1.6.1 (Monday January 29th 2018)

• Removed lxml as a dependency - this was necessary in older versions of trimesh.

1.6.0 (Friday January 26th 2018)

• The new .Mesh class is now the base class for all mesh types. It has been written to allow multiple sets of vertices to be associated with a mesh object (to support e.g. white matter, inflated, spherical models for a GIFTI/freeusrfer mesh).
• The new .VTKMesh class must now be used for loading VTK model files, instead of the old .TriangleMesh class.
• The new .Mesh class uses the trimesh library (https://github.com/mikedh/trimesh) to perform various geometrical operations, accessible via new .Mesh.rayIntersection, .Mesh.planeIntersection, .Mesh.nearestVertex methods.
• The .Nifti and .Mesh classes have new methods allowing arbitrary metadata to be stored with the image, as key-value pairs. These are provided by a new mixin class, .Meta.
• Freesurer surface files and vertex data can now be loaded via the .FreesurferMesh class, in the new .freesurfer module.
• Freesurfer mgz / mgh image files can now be loaded via the new .mghimage module. Internally, these image files are converted to NIFTI
  • the .MGHImage class derives from the .Image class.
• Meta-data access methods on the .DicomImage class have been deprecated, as their functionality is provided by the new .Meta mixin.
• The .TriangleMesh class has been deprecated in favour of the new .Mesh class.
• Optional dependencies wxpython, indexed_gzip, trimesh, and rtree are now listed separately, so fslpy can be used without them (although relevant functionality will be disabled if they are not present).

1.5.4 (Wednesday January 10th 2018)

• Actually included the fix that was supposed to be in version 1.5.3.

1.5.3 (Tuesday January 9th 2018)

• Bug fix to .ImageWrapper.__expandCoverage - was not correctly handling large images with lots of nan values.

1.5.2 (Tuesday January 2nd 2018)

• Fixed issue with MANIFEST.in file.

1.5.1 (Thursday December 14th 2017)

• Fixed bug in .dicom.scanDir function related to data series ordering.

1.5.0 (Wednesday December 13th 2017)

• New module .dicom, which provides a thin wrapper on top of Chris Rorden's dcm2niix.
• New module .tempdir, which has a convenience function for creating temporary directories.
• Fixed small issue in .Image.dtype - making sure that it access image data via the .ImageWrapper, rather than via the Nifti1Image object.

1.4.2 (Tuesday December 5th 2017)

• New function .transform.rmsdev function, which implements the RMS deviation equation for comparing two affine transformations (FMRIB Technical Report TR99MJ1, available at https://www.fmrib.ox.ac.uk/datasets/techrep/).
• Some small bugfixes to the .atlasq and .atlases moduless.

1.4.1 (Thursday November 9th 2017)

• Fixed bug in setup.py.

1.4.0 (Thursday November 9th 2017)

• The .uniquePrefix function now raises a ~.path.PathError instead of a .ValueError, when an invalid path is provided.
• The fsl.utils.async module is now deprecated, as async will become a reserved word in Python 3.7. It has been renamed to fsl.utils.idle, with no other API changes.
• For image file pairs, the hdr extension now takes precedence over the img extension, when using the fsl.data.image.addExt (and related) functions.
• The fsl.utils.path.addExt function accepts a new parameter, unambiguous which causes it to allow an ambiguous prefix, and return all matching paths.
• New ~fsl.scripts.atlasq application, intended to replace the FSL atlasquery tool.
• New ~fsl.scripts.imglob application, intended to replace the FSL imglob tool.
• The .Image.resample method explicitly raises a ValueError if incompatible shapes are provided.

1.3.1 (Wednesday October 25th 2017)

• Fixed bug in .Platform.wxPlatform causing it to always return WX_UNKNOWN.

1.3.0 (Wednesday October 25th 2017)

• .Atlas classes can now pass kwargs through to the .Image constructor.
• .LabelAtlas image values no longer need to match the index of the label into the .AtlasDescription labels list. This means that label atlas XML files may contain non-sequential label values.
• .Cache now implements __getitem__ and __setitem__
• The .image.read_segments function (monkey-patched into nibabel) is deprecated, as it is no longer necessary as of nibabel 2.2.0.
• .platform.isWidgetAlive is deprecated in favour of an equivalent function in the fsleyes-widgets library.
• scipy is now explicitly listed as a requirement (this should have been done in 1.2.1).

1.2.2 (Saturday October 21st 2017)

• The .image.read_segments function is only monkey-patched into nibabel 2.1.0, as it breaks when used with 2.2.0.

1.2.1 (Saturday October 7th 2017)

• If an .Image is passed an existing nibabel header object, it creates a copy, rather than using the original.
• New .Image.resample method, which resamples the image data to a different resolution.
• New .LabelAtlas.coordLabel, .LabelAtlas.maskLabel, .ProbabilisticAtlas.coordProportions and .ProbabilisticAtlas.maskProportions methods. The coord methods perform coordinate queries in voxel or world coordinates, and the mask methods perform mask-based queries.

1.2.0 (Thursday September 21st 2017)

• fsl.data.image.Nifti.voxelsToScaledVoxels method deprecated in favour of new .Nifti.voxToScaledVoxMat and Nifti.scaledVoxToVoxMat properties.

1.1.0 (Monday September 11th 2017)

• The fsl package is now a pkgutil-style namespace package, so it can be used for different projects.
• Updates to fsl.data.image.Nifti and fsl.data.image.Image to add support for images with more than 4 dimensions:
  • New ndims property
  • is4DImage method deprecated

1.0.5 (Thursday August 10th 2017)

• New functions and further adjustments in fsl.utils.transform module:

• .transform.rotMatToAffine converts a (3, 3) rotation matrix into a (4, 4) affine.
• .transform.transformNormal applies an affine transform to one or more vectors.
• .transform.veclength calculates the length of a vector
• .transform.normalise normalises a vector
• .transform.scaleOffsetXform adjusted to have more flexibility with respect to inputs.
• .transform.decompose can return rotations either as three axis-angles, or as a rotation matrix

• Updates to fsl.data.mesh.TriangleMesh - vertices and indices are now property attributes. New lazily generated normals and vnormals properties (face and vertex normals respectively). Option to __init__ to fix the face winding order of a mesh.
• fsl.utils.memoize.memoize decorator made into a class rather than a function. The new .Memoize class has an invalidate method, which clears the cache.

1.0.4 (Friday July 14th 2017)

• Python 2/3 compatibility fix to fsl.utils.callfsl.
• Fix to fsl.utils.transform.scaleOffsetXform - accepts inputs that are not lists.
• fsl.utils.transform.compose accepts either a sequence of three axis angles, or a (3, 3) rotation matrix.

1.0.3 (Sunday June 11th 2017)

• Fix to fsl.utils.async which was breaking environments where multiple wx.App instances were being created.

1.0.2 (Thursday June 8th 2017)

• Python 2/3 compatibility fixes
• New fsl.version.patchVersion function.

1.0.1 (Sunday 4th June 2017)

• New version number parsing functions in fsl.version.

1.0.0 (Saturday May 27th 2017)

• Removed many GUI-related modules - they have been moved to the fsleyes-widgets project. The following modules have been removed:
  • fsl.utils.colourbarbitmap
  • fsl.utils.dialog
  • fsl.utils.imagepanel
  • fsl.utils.layout
  • fsl.utils.platform
  • fsl.utils.runwindow
  • fsl.utils.status
  • fsl.utils.textbitmap
  • fsl.utils.typedict
  • fsl.utils.webpage
• fsl.utils.settings module rewritten. It no longer uses wx, but instead stores plain-text and pickle files in the user's home directory.
• Software GL renderer test in fsl.utils.platform is more lenient
• New .AtlasLabel class
• .Image.__init__ allows arguments to be passed through to nibabel.load.
• New .Nifti.strval method to handle escaped strings in NIFTI headers.
• Python 2/3 compatibility fixes

0.11.0 (Thursday April 20th 2017)

• First public release as part of FSL 5.0.10