Documentation restructure by draffelt · Pull Request #890 · MRtrix3/mrtrix3

draffelt · 2017-01-24T12:46:31Z

Hi Guys,
Check out the new documentation on the 'doc_restructure' branch on read the docs.

Some things to note:

Removal of basic tutorials and advanced workflows section. Replaced with dedicated sections for features.
Updated description of the main MRtrix functionality, as I mentioned before, I know it's not quite comprehensive but to not make it too long, I've only included features that have their own section in the docs. Feel free to modify
Because the list of MRtrix commands is way down the bottom, I've added this small page to aid discover-ability of commands for new users. Note that it would be nice eventually to have a table with a one line description for all commands (pulled automatically from the command synopsis.).
Fixel Image format docs. Would be great to have another set of eyes over this
Changed DWI Modelling section to CSD. On the assumption that currently we would not really recommend doing anything thing else, so it's unlikey that we will make tutorials for other models. We can always change this if we do. Note I've moved the lmax stuff from the FAQ into this section.
Troubleshooting has been moved from getting stated to the end. With some grouping of display, and hanging related issues.
FAQ currently in the troubleshooting section. @thijsdhollander unfortunately if I put it in its own section, then the section caption is not linkable, so it needs to be listed again below the section caption.
Global intensity normalisation has a dedicated page in concepts
Tips and Tricks section. I've currently add a tutorial for batch processing with the foreach script (since this is now heavily used in the FBA tutorials).
FBA instructions for single-shell, multi-tissue CSD, as well as some basics on how to display FBA results with streamlines, and compute effect sizes. Note that the FBA instructions are much more detailed, and have more explicit steps. Users can now copy and paste from start to finish, providing they start off with the recommend layout of files. Basically the old instructions only gave vague descriptions of the inputs and outputs, and not explicit file names. This got tricky when trying to explain the steps working on the new fixel format, so I opted for more explicit instructions.
Added NOTE about citation MRtrix to before you install
@Lestropie , this and this tutorial have fairly similar names. Not sure if you want to do anything about this.

- Updated lmax description to reflect inclusion of amp2response. - Revised description of fixel format. - Renamed labelconvert tutorial to reduce conflict with structural connectome construction tutorial.

Lestropie · 2017-01-25T01:52:58Z

Fixel Image format docs. Would be great to have another set of eyes over this

Done; have a look. You didn't actually state anywhere that the indices for all fixels within a voxel must be / are inferred to be sequential. :-P

Still concerned that this is not sufficiently compatible with models generated through bootstrapping (and therefore FMRIB will reject the idea). For instance:

Easily identified as a data file type because the size of the image is 1 in the 3rd dimension: If a model has p parameters per fixel but also b bootstraps, they might have an image that's n x p x b.
All DWI models must specify the direction of each fixel.: With bootstrapping, each fixel doesn't have a 'fixed' direction; there's a large number of separate realisations of the fixel model, and each has a unique direction for each fixel. bedpostx does generate images for mean azimuth and mean elevation of each fixel, but technically to do this properly you can't just average across bootstrap realisations, you need to do some form of fixel correspondence, since the ordering isn't guaranteed to be equivalent. I see this as a requirement for many MRtrix3 commands, including the current state of the mrview fixel tool, but I'm not sure if it should be a 100% hard rule.

Added NOTE about citation MRtrix to before you install

I've been telling people to not cite the 2012 paper and just give the website / GitHub. For the analyses most people are doing, none of it will actually be described in that paper; the only thing in common is the name. Yes it means less citations for Donald, but that's just how I feel about it.

@Lestropie , this and this tutorial have fairly similar names. Not sure if you want to do anything about this.

Done.

Edit: Has the ISMRM HCP connectome tutorial disappeared?

- Command-line usage: Re-arrange order of entries, with simpler & more frequently-used features nearer the top; examples for ordering of options on command-line; more cases where command-line ordering does matter. - Image data: Separate fixel formats (new and legacy) from generic image formats, and slightly rename titles accordingly. - Hanging or crashing: More detail on inadequate RAM error, extend to apply to fixelcfestats; add section on inadequate storage for Python scripts. - Various tweaks.

draffelt · 2017-01-25T07:08:13Z

Done; have a look.

Thanks, looks good

Easily identified as a data file type because the size of the image is 1 in the 3rd dimension: If a model has p parameters per fixel but also b bootstraps, they might have an image that's n x p x b.

I guess they could have 1 file per bootstrap...bit silly I know. I guess not all packages/applications have to take this format on board. Personally I'm not going to have any time to drive this as a standard (I start my new job in 2.5 weeks). So I guess it's up to everyone else to decide on if they want to push it to be standardised and written up.

All DWI models must specify the direction of each fixel.: With bootstrapping, each fixel doesn't have a 'fixed' direction.

Clearly this format won't work for "All DWI models". Think I'll rename it to "fixel-based DWI models".

Has the ISMRM HCP connectome tutorial disappeared?

No, I just forgot to add the .rst extension when I renamed it. It's back now.

draffelt · 2017-01-27T06:10:12Z

@jdtournier I'm assuming you are happy with the restructure? Will merge it into tag_0.3.16 if so

jdtournier

Sure, no problem with the documentation at all. There's still a few things missing, but the structure looks good. Missing bits include a page on the humble single-shell CSD, which is notably absent from the CSD section (could also discuss the soft vs hard constraint issue) and simple targeted tractography, TDI, tract-wise measues of e.g. FA, etc (i.e. not quantitative connectivity - probably requires its own section) - mustn't forget that this probably makes up the bulk of our regular users...

thijsdhollander

All good! There's indeed some gaps to fill still, but the structure is good and allows for it nicely. 👍

draffelt added 30 commits January 18, 2017 09:33

create troubleshooting section in docs

605618e

formatting changes to troubleshooting docs

3f6b6d7

formatting changes to troubleshooting docs depth

90a5d34

further reshuffle of docs layout

7f90d6c

Fixed some docs issue with previous commit

3328924

test docs list of commands menu depth

8a8c9db

test docs list of commands menu depth

a11c8cd

Added MRtrix Commands and Scripts section in docs

01d4c3b

Fix typo in previous commit

500e317

Fix issues with previous commit

94f0316

Fix issues with previous commit

93978bf

Try to rename some internal references in docs

6a4b58e

Fix issues with previous commit

3ce2482

Fix issues with previous commit

e25659f

Fix docs referencing issue

05775a1

Fix docs referencing issue

d292f38

Fix docs referencing issue

2fbc4ba

Fix docs referencing issue

10fb303

Fix docs referencing issue

69e8dfb

Changes to global intensity normalisation docs

a7f2042

Fix typos in global intensity normalisation docs

a2e005d

few improvements to the global intensity normalisation docs

b53acca

intitial changes to single-shell FDC FBA instructions

7e32790

Added batch processing with foreach tutorial to docs

d175d43

added tips and tricks to the docs menu

dd7a87d

fix a few erros in batch processing docs

7d18189

Fix bug in dwipreproc

1c3054a

Initial changes to FBA docs using foreach

b177a5e

Further changes to FBA docs

97f6c01

Further changes to FBA docs

7dac911

draffelt added 9 commits January 24, 2017 15:25

Changes to multi-tissue CSD FBA docs

5223d51

Changes to multi-tissue CSD FBA docs

a3557b2

More tweaks to FBA docs

b128483

More tweaks to FBA docs

b9fb3ff

Added tutorial for displaying FBA results with streamlines

0efd5c1

Fix include issue in FBA docs

f3cbf26

Fix include issue in FBA docs

22d2974

Fix typos in FBA docs

acd5105

docs/fixel_based_analysis/computing_effect_size_wrt_controls.rst

9c48bf9

draffelt requested review from Lestropie, jdtournier and thijsdhollander January 24, 2017 12:46

Docs: Revisions to restructure

b8ee2a6

- Updated lmax description to reflect inclusion of amp2response. - Revised description of fixel format. - Renamed labelconvert tutorial to reduce conflict with structural connectome construction tutorial.

Lestropie and others added 3 commits January 25, 2017 16:48

small update to FBA effect size docs

2888eaf

fixed bad rename of HCP tutorial file in docs

291bc65

draffelt added 7 commits January 25, 2017 17:09

Change minor wording in fixel image format docs

445da4d

FBA docs: fix error in fixel analysis mask step

2b69fc1

FBA docs: fix error in fod warping step

6e020fc

FBA docs: fixed issue with fixel analysis mask calculation

4381a6e

FBA docs: improve template masking in mt tutorial

5fcff78

FBA docs: fix typo in previous commit

034ec63

FBA docs: simplify some fixel steps

715b588

jdtournier approved these changes Jan 27, 2017

View reviewed changes

draffelt merged commit bbe9d8d into tag_0.3.16 Jan 29, 2017

draffelt deleted the doc_restructure branch January 29, 2017 05:35

thijsdhollander reviewed Jan 30, 2017

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation restructure#890

Documentation restructure#890
draffelt merged 65 commits into
tag_0.3.16from
doc_restructure

draffelt commented Jan 24, 2017

Uh oh!

Lestropie commented Jan 25, 2017 •

edited

Loading

Uh oh!

draffelt commented Jan 25, 2017

Uh oh!

draffelt commented Jan 27, 2017

Uh oh!

jdtournier left a comment

Uh oh!

thijsdhollander left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

draffelt commented Jan 24, 2017

Uh oh!

Lestropie commented Jan 25, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

draffelt commented Jan 25, 2017

Uh oh!

draffelt commented Jan 27, 2017

Uh oh!

jdtournier left a comment

Choose a reason for hiding this comment

Uh oh!

thijsdhollander left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Lestropie commented Jan 25, 2017 •

edited

Loading