-
Notifications
You must be signed in to change notification settings - Fork 12
/
development.html
780 lines (744 loc) · 44.6 KB
/
development.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta property="og:title" content="Nilearn development process" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://nilearn.github.io/development.html" />
<meta property="og:site_name" content="Nilearn" />
<meta property="og:description" content="How to help?, How do we decide what code goes in?- Scope of the project, Who makes decisions., How to contribute to nilearn- Contribution Guidelines, PR Structure, Coding Style, Tests, Documentatio..." />
<meta property="og:image" content="https://nilearn.github.io/_static/nilearn-logo.png" />
<meta property="og:image:alt" content="Nilearn" />
<title>Nilearn: Statistical Analysis for NeuroImaging in Python — Machine learning for NeuroImaging</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/nature.css" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="_static/gallery.css" />
<link rel="stylesheet" type="text/css" href="_static/gallery-binder.css" />
<link rel="stylesheet" type="text/css" href="_static/gallery-dataframe.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/clipboard.min.js"></script>
<script src="_static/copybutton.js"></script>
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Nilearn maintenance process" href="maintenance.html" />
<link rel="prev" title="0.8.2.dev" href="whats_new.html" />
<meta content="True" name="HandheldFriendly">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0">
<meta name="keywords" content="nilearn, neuroimaging, python, neuroscience, machinelearning">
<script type="text/javascript">
function updateTopMenuPosition(height, width) {
if($(window).scrollTop() > height && $(window).outerWidth() > 1024) {
//begin to scroll
$('.related-wrapper').css("z-index", 1000);
$('.related-wrapper').css("position", "sticky");
$('.related-wrapper').css("top", 0);
$('.related-wrapper').css("width", width)
} else {
//lock it back into place
$('.related-wrapper').css("position", "relative");
$('.related-wrapper').css("top", 0)
}
}
$(function() {
var banner_height = $('#logo-banner').outerHeight();
var banner_width = $('#logo-banner').outerWidth();
var width = $('.related-wrapper').css("height", $('.related').outerHeight());
updateTopMenuPosition(banner_height, width);
$(window).scroll(function(event) {
updateTopMenuPosition(banner_height, width)
});
$(window).resize(function(event) {
var banner_width = $('#logo-banner').outerWidth();
var menu_height = $('.related').outerHeight();
$('.related').css("width", banner_width);
$('.related-wrapper').css("height", menu_height);
updateTopMenuPosition(banner_height, width)
})
});
</script>
<script type="text/javascript">
function updateSideBarPosition(top, offset, sections) {
var pos = $(window).scrollTop();
// Lock the table of content to a fixed position once we scroll enough
var topShift = 2 * offset;
if(pos > top + topShift + 1) {
// begin to scroll with sticky menu bar
var topShift = -topShift + 1;
if ($(window).outerWidth() < 1024) {
// compensate top menu that disappears
topShift -= offset + 1
}
$('.sphinxsidebarwrapper').css("position", "fixed");
$('.sphinxsidebarwrapper').css("top", topShift)
}
else {
//lock it back into place
$('.sphinxsidebarwrapper').css("position", "relative");
$('.sphinxsidebarwrapper').css("top",0)
}
// Highlight the current section
i = 0;
current_section = 0;
$('a.internal').removeClass('active');
for(i in sections) {
if(sections[i] > pos) {
break
}
if($('a.internal[href$="' + i + '"]').is(':visible')){
current_section = i
}
}
$('a.internal[href$="' + current_section + '"]').addClass('active');
$('a.internal[href$="' + current_section + '"]').parent().addClass('active')
}
$(function () {
// Lock the table of content to a fixed position once we scroll enough
var tocOffset = $('.related-wrapper').outerHeight();
var marginTop = parseFloat($('.sphinxsidebarwrapper').css('margin-top').replace(/auto/, 0));
var top = $('.sphinxsidebarwrapper').offset().top - marginTop;
sections = {};
url = document.URL.replace(/#.*$/, "");
// Grab positions of our sections
$('.headerlink').each(function(){
sections[this.href.replace(url, '')] = $(this).offset().top - 50
});
updateSideBarPosition(top, tocOffset, sections);
$(window).scroll(function(event) {
updateSideBarPosition(top, tocOffset, sections)
});
$(window).resize(function(event) {
tocOffset = $('.related-wrapper').outerHeight();
updateSideBarPosition(top, tocOffset, sections)
});
});
</script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-41920728-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head><body>
<div id="logo-banner">
<div class="logo">
<a href="index.html">
<img src="_static/nilearn-logo.png" alt="Nilearn logo" border="0" />
</a>
</div>
<!-- A tag cloud to make it easy for people to find what they are
looking for -->
<div class="tags">
<ul>
<li>
<big><a href="auto_examples/decoding/plot_haxby_anova_svm.html">SVM</a></big>
</li>
<li>
<small><a href="connectivity/parcellating.html">Ward
clustering</a></small>
</li>
<li>
<a href="decoding/searchlight.html">Searchlight</a>
</li>
<li>
<big><a href="connectivity/resting_state_networks.html">ICA</a></big>
</li>
<li>
<a href="manipulating_images/data_preparation.html">Nifti IO</a>
</li>
<li>
<a href="modules/reference.html#module-nilearn.datasets">Datasets</a>
</li>
</ul>
</div>
<div class="banner">
<h1>Nilearn:</h1>
<h2>Statistics for NeuroImaging in Python</h2>
</div>
<div class="search_form">
<div class="gcse-search" id="cse" style="width: 100%;"></div>
<script>
(function() {
var cx = '017289614950330089114:elrt9qoutrq';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
</script>
</div>
</div>
<div class=related-wrapper>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="py-modindex.html" title="Python Module Index"
>modules</a></li>
<li class="right" >
<a href="maintenance.html" title="Nilearn maintenance process"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="whats_new.html" title="0.8.2.dev"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Nilearn Home</a> | </li>
<li><a href="user_guide.html">User Guide</a> | </li>
<li><a href="auto_examples/index.html">Examples</a> | </li>
<li><a href="modules/reference.html">Reference</a> | </li>
<li id="navbar-about"><a href="authors.html">About</a>| </li>
<li><a href="glossary.html">Glossary</a>| </li>
<li><a href="bibliography.html">Bibliography</a>| </li>
<li id="navbar-ecosystem"><a href="http://www.nipy.org/">Nipy ecosystem</a></li>
<li class="nav-item nav-item-this"><a href="">Nilearn: Statistical Analysis for NeuroImaging in Python</a></li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="nilearn-development-process">
<span id="development-process"></span><h1>Nilearn development process<a class="headerlink" href="#nilearn-development-process" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#how-to-help" id="id7">How to help?</a></p></li>
<li><p><a class="reference internal" href="#how-do-we-decide-what-code-goes-in" id="id8">How do we decide what code goes in?</a></p>
<ul>
<li><p><a class="reference internal" href="#scope-of-the-project" id="id9">Scope of the project</a></p></li>
<li><p><a class="reference internal" href="#who-makes-decisions" id="id10">Who makes decisions</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#how-to-contribute-to-nilearn" id="id11">How to contribute to nilearn</a></p>
<ul>
<li><p><a class="reference internal" href="#contribution-guidelines" id="id12">Contribution Guidelines</a></p></li>
<li><p><a class="reference internal" href="#pr-structure" id="id13">PR Structure</a></p></li>
<li><p><a class="reference internal" href="#coding-style" id="id14">Coding Style</a></p></li>
<li><p><a class="reference internal" href="#tests" id="id15">Tests</a></p></li>
<li><p><a class="reference internal" href="#documentation" id="id16">Documentation</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#setting-up-your-environment" id="id17">Setting up your environment</a></p>
<ul>
<li><p><a class="reference internal" href="#installing" id="id18">Installing</a></p></li>
<li><p><a class="reference internal" href="#id6" id="id19">Contributing</a></p></li>
<li><p><a class="reference internal" href="#building-documentation" id="id20">Building documentation</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#additional-cases" id="id21">Additional cases</a></p>
<ul>
<li><p><a class="reference internal" href="#how-to-contribute-an-atlas" id="id22">How to contribute an atlas</a></p></li>
<li><p><a class="reference internal" href="#how-to-contribute-a-dataset-fetcher" id="id23">How to contribute a dataset fetcher</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#maintenance" id="id24">Maintenance</a></p></li>
</ul>
</div>
<div class="section" id="how-to-help">
<span id="contributing"></span><h2><a class="toc-backref" href="#id7">How to help?</a><a class="headerlink" href="#how-to-help" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><p>If you have a usage question : create a topic on <a class="reference external" href="https://neurostars.org/tag/nilearn">neurostars</a> with the nilearn tag</p></li>
<li><p>You think you discovered a bug ? Create <a class="reference external" href="https://github.com/nilearn/nilearn/issues/new/choose">an issue</a>
including a minimal runnable example to showcase it (using Nilearn data) as well as your OS and Nilearn version.</p></li>
<li><p>If you have an idea for a new feature, check if it is in the scope of the project
and feel free to open an issue to discuss it.</p></li>
<li><p>Want to contribute code ? Thank you very much!</p>
<ul>
<li><p>For new features, please be sure to create an issue first, to discuss
whether it can be included and its specifications.</p></li>
<li><p>To help with known issues, please check
<a class="reference external" href="https://github.com/nilearn/nilearn/labels/Good%20first%20issue">good first issues</a>
to get started, <a class="reference external" href="https://github.com/nilearn/nilearn/labels/Bug">known bugs</a>
or <a class="reference external" href="https://github.com/nilearn/nilearn/labels/Enhancement">proposed enhancements</a>.</p></li>
<li><p>In any case, before sending code, be sure to <strong>follow the</strong> <a class="reference internal" href="#id5">Contribution Guidelines</a>.</p></li>
<li><p>The section <a class="reference internal" href="#setting-up-your-environment">Setting up your environment</a> will get you ready to contribute.</p></li>
</ul>
</li>
<li><p>If you think documentation can be improved, you can directly send proposed
improvements in <a class="reference external" href="https://github.com/nilearn/nilearn/pulls">a pull request</a>.</p></li>
</ul>
</div>
<div class="section" id="how-do-we-decide-what-code-goes-in">
<h2><a class="toc-backref" href="#id8">How do we decide what code goes in?</a><a class="headerlink" href="#how-do-we-decide-what-code-goes-in" title="Permalink to this headline">¶</a></h2>
<div class="section" id="scope-of-the-project">
<h3><a class="toc-backref" href="#id9">Scope of the project</a><a class="headerlink" href="#scope-of-the-project" title="Permalink to this headline">¶</a></h3>
<p>Nilearn is an Open-source Python package for visualizing and analyzing human
brain MRI data.
It provides statistical and machine-learning tools for brain mapping,
connectivity estimation and predictive modelling.
It brings visualization tools with instructive documentation & open community.</p>
<p>Nilearn targets ease of use, but as Python code.
In other words, we will not add graphical user interfaces, but we want our
code to be as easy to understand as possible, with easy prototyping and
debugging, even for beginners in Python.</p>
<p>We are parsimonious in the way we add features to the project, as it
puts on weight.
To assess new features, our main concern is their usefulness to a number of
our users.
To make Nilearn high-quality and sustainable we also weigh their benefits
(i.e., new features, ease of use) with their cost (i.e., complexity of the code,
runtime of the examples). As a rule of thumb:</p>
<ul class="simple">
<li><p>To be accepted, new features must be <strong>in the scope of the project</strong> and
correspond to an <strong>established practice</strong> (typically as used in scientific
publications).</p></li>
<li><p>It must have a concrete use case, illustrated with a <strong>simple example</strong> in the
Nilearn documentation to teach it easily to end-users.</p></li>
<li><p>It must be <strong>thoroughly tested</strong>, and respect <strong>coding conventions</strong> of the
existing codebase.</p></li>
<li><p>Features introducing new dependencies will generally not be accepted.</p></li>
<li><p>Downloaders for new atlases are welcome if they comes with an example.</p></li>
<li><p>Downloaders for new datasets are usually discouraged. We will consider adding
fetchers only for light datasets which are needed to demo and teach features.</p></li>
</ul>
<p>Exhaustive criteria used in the review process are detailed in the <strong>contribution
guide below</strong>.
Be sure to read and follow them so that your code can be accepted quickly.</p>
</div>
<div class="section" id="who-makes-decisions">
<h3><a class="toc-backref" href="#id10">Who makes decisions</a><a class="headerlink" href="#who-makes-decisions" title="Permalink to this headline">¶</a></h3>
<p>We strongly aim to be a community oriented project where decisions are
made based on consensus according to the criteria described above.
Discussions are public, held on issues and pull requests in Github.
All modifications of the codebase are ultimately checked during a reviewing
process, where maintainers or contributors make sure they respect the
<a class="reference internal" href="#contribution-guidelines"><span class="std std-ref">Contribution Guidelines</span></a>.
To be merged, a pull request usually needs to be accepted by two maintainers.
In case a consensus does not emerge easily, the decisions are made by the
core contributors, i.e., people with write access to the repository, as
listed <a class="reference internal" href="authors.html#core-devs"><span class="std std-ref">here</span></a>.</p>
</div>
</div>
<div class="section" id="how-to-contribute-to-nilearn">
<h2><a class="toc-backref" href="#id11">How to contribute to nilearn</a><a class="headerlink" href="#how-to-contribute-to-nilearn" title="Permalink to this headline">¶</a></h2>
<p>This project, hosted on <a class="reference external" href="https://github.com/nilearn/nilearn">https://github.com/nilearn/nilearn</a>, is a community
effort, and everyone is welcome to contribute.
We value very much your feedback and opinion on features that should be
improved or added.
All discussions are public and held on relevant issues or pull requests.
To discuss your matter, please comment on a relevant
<a class="reference external" href="https://github.com/nilearn/nilearn/issues">issue</a> or open a new one.</p>
<p>The best way to contribute and to help the project is to start working on known
issues such as <a class="reference external" href="https://github.com/nilearn/nilearn/labels/Good%20first%20issue">good first issues</a>,
<a class="reference external" href="https://github.com/nilearn/nilearn/labels/Bug">known bugs</a> or
<a class="reference external" href="https://github.com/nilearn/nilearn/labels/Enhancement">proposed enhancements</a>.
If an issue does not already exist for a potential contribution, we ask that
you first open an <a class="reference external" href="https://github.com/nilearn/nilearn/issues">issue</a> before
sending a <a class="reference internal" href="maintenance.html#pull-request"><span class="std std-ref">Pull Requests</span></a> to discuss scope and potential design choices
in advance.</p>
<div class="section" id="contribution-guidelines">
<span id="id5"></span><h3><a class="toc-backref" href="#id12">Contribution Guidelines</a><a class="headerlink" href="#contribution-guidelines" title="Permalink to this headline">¶</a></h3>
<p>When modifying the codebase, we ask every contributor to respect common
guidelines.
Those are inspired from <a class="reference external" href="https://scikit-learn.org/stable/developers/contributing.html#contributing-code">scikit-learn</a>
and ensure Nilearn remains simple to understand, efficient and maintainable.
For example, code needs to be tested and those tests need to run quickly in order
not to burden the development process.
To keep continuous integration efficient with our limited infrastructure,
running all the examples must lead to downloading a limited amount of data
(gigabytes) and execute in a reasonable amount of time (less than an hour).
Those guidelines will hence be enforced during the reviewing process.
The section <a class="reference internal" href="#setting-up-your-environment">Setting up your environment</a> will help you to quickly get familiar
with the tools we use for development and deployment.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 23%" />
<col style="width: 17%" />
<col style="width: 60%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"></th>
<th class="head"><p>Which PR ?</p></th>
<th class="head"><p>Guidelines</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><a class="reference internal" href="#pr-structure">PR Structure</a></p></td>
<td><p>Any</p></td>
<td><ul class="simple">
<li><p>Clear name</p></li>
<li><p>Link issue through mention :”Closes #XXXX”</p></li>
<li><p>Clearly outline goals and changes proposed</p></li>
<li><p>Doesn’t include “unrelated” code change</p></li>
<li><p>Add entry in “doc/whats_new.rst”</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="#coding-style">Coding Style</a></p></td>
<td><p>Any</p></td>
<td><ul class="simple">
<li><p>Variables, functions, arguments have clear names</p></li>
<li><p>Easy to read, <a class="reference external" href="https://www.python.org/dev/peps/pep-0008/">PEP8</a></p></li>
<li><p>Public functions have docstring (<a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc</a> format)</p></li>
<li><p>Low redundancy</p></li>
<li><p>No new dependency</p></li>
<li><p>Backward compatibility</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#tests">Tests</a></p></td>
<td><ul class="simple">
<li><p>Bugfixes</p></li>
<li><p>New features</p></li>
</ul>
</td>
<td><ul class="simple">
<li><p>Test type is adapted to function behavior</p></li>
<li><p>Tests pass continuous integration</p></li>
<li><p>Coverage doesn’t decrease</p></li>
<li><p>Fast, using small mocked data</p></li>
<li><p>Atomic (one per function) and seeded</p></li>
<li><p>For Bugfixes: non-regression test</p></li>
</ul>
</td>
</tr>
<tr class="row-odd"><td><p>Examples</p></td>
<td><p>New features</p></td>
<td><ul class="simple">
<li><p>Clearly showcase benefits</p></li>
<li><p>Run in a few seconds</p></li>
<li><p>Use light data (generated or from Nilearn)</p></li>
<li><p>Renders well after build</p></li>
</ul>
</td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="#documentation">Documentation</a></p></td>
<td><p>Any</p></td>
<td><ul class="simple">
<li><p>Simple and didactic</p></li>
<li><p>Links to relevant examples</p></li>
<li><p>Renders well after build</p></li>
<li><p>Doesn’t include code</p></li>
</ul>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="pr-structure">
<h3><a class="toc-backref" href="#id13">PR Structure</a><a class="headerlink" href="#pr-structure" title="Permalink to this headline">¶</a></h3>
<p>A new pull request must have a clear scope, conveyed through its name, a
reference to the issue it targets (through the exact mention “Closes #XXXX”),
and a synthetic summary of its goals and main steps.
When working on big contributions, we advise contributors to split them into
several PRs when possible.
This has the benefit of making code changes clearer, making PRs easier to review,
and overall smoothening the whole process.
No changes unrelated to the PR should be included.</p>
<p>When relevant, PR names should also include tags if they fall in various
categories.
When opening a PR, the authors should include the [WIP] tag in its name, or use
github draft mode. When ready for review, they should switch the tag to [MRG] or
can switch it back to normal mode.
Other tags can describe the PR content : [FIX] for a bugfix, [DOC] for a
change in documentation or examples, [ENH] for a new feature and [MAINT] for
maintenance changes.</p>
</div>
<div class="section" id="coding-style">
<h3><a class="toc-backref" href="#id14">Coding Style</a><a class="headerlink" href="#coding-style" title="Permalink to this headline">¶</a></h3>
<p>Nilearn codebase follow <a class="reference external" href="https://www.python.org/dev/peps/pep-0008/">PEP8</a> styling.
The main conventions we enforce are : line length < 80, spaces around operators,
meaningful variable names, function names are underscore separated
(e.g., <code class="docutils literal notranslate"><span class="pre">a_nice_function</span></code>) and as short as possible,
public functions exposed in their parent module’s init file,
private function names preceded with a “_” and very explicit,
classes in CamelCase, 2 empty lines between functions or classes.
Each function and class must come with a “docstring” at the top of the function
code, using <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc</a> formatting.
They must summarize what the function does and document every parameter.</p>
</div>
<div class="section" id="tests">
<h3><a class="toc-backref" href="#id15">Tests</a><a class="headerlink" href="#tests" title="Permalink to this headline">¶</a></h3>
<p>When fixing a bug, the first step is to write a minimal test that fails because
of it, and then write the bugfix to make this test pass.
For new code you should have roughly one test_function per function covering
every line and testing the logic of the function.
They should run on small mocked data, cover a representative range of parameters.</p>
<p>Tests must be seeded to avoid random failures.
For objects using random seeds (e.g. scikit-learn estimators), pass either
a <cite>np.random.RandomState</cite> or an <cite>int</cite> as the seed.
When your test use random numbers, those must be generated through:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">rng</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">RandomState</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="n">my_number</span> <span class="o">=</span> <span class="n">rng</span><span class="o">.</span><span class="n">normal</span><span class="p">()</span>
</pre></div>
</div>
<p>To check your changes worked and didn’t break anything run <cite>pytest nilearn</cite>.
To do quicker checks it’s possible to run only a subset of tests:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pytest</span> <span class="o">-</span><span class="n">v</span> <span class="n">test_module</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
</div>
<div class="section" id="documentation">
<h3><a class="toc-backref" href="#id16">Documentation</a><a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h3>
<p>Documentation must be understandable by people from different backgrounds.
The “narrative” documentation should be an introduction to the concepts of
the library.
It includes very little code and should first help the user figure out which
parts of the library he needs and then how to use it.
It must be full of links, of easily-understandable titles, colorful boxes and
figures.</p>
<p>Examples take a hands-on approach focused on a generic usecase from which users
will be able to adapt code to solve their own problems.
They include plain text for explanations, python code and its output and
most importantly figures to depict its results.
Each example should take only a few seconds to run.</p>
<p>To build our documentation, we are using
<a class="reference external" href="https://www.sphinx-doc.org/en/master/usage/quickstart.html">sphinx</a> for the
main documentation and
<a class="reference external" href="https://sphinx-gallery.github.io/stable/index.html">sphinx-gallery</a> for the
example tutorials. If you want to work on those, check out next section to
learn how to use those tools to build documentation.</p>
</div>
</div>
<div class="section" id="setting-up-your-environment">
<span id="git-repo"></span><h2><a class="toc-backref" href="#id17">Setting up your environment</a><a class="headerlink" href="#setting-up-your-environment" title="Permalink to this headline">¶</a></h2>
<div class="section" id="installing">
<h3><a class="toc-backref" href="#id18">Installing</a><a class="headerlink" href="#installing" title="Permalink to this headline">¶</a></h3>
<p>Here are the key steps you need to go through to copy the repo before contributing:</p>
<ol class="arabic">
<li><p>fork the repo from github (fork button in the top right corner of our <a class="reference external" href="https://github.com/nilearn/nilearn">main github page</a>) and clone your fork locally:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">git</span><span class="nd">@github</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="o"><</span><span class="n">your_username</span><span class="o">>/</span><span class="n">nilearn</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
</li>
<li><p>(optional but highly recommended) set up a conda environment to work on and activate it:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">create</span> <span class="o">-</span><span class="n">n</span> <span class="n">nilearn</span>
<span class="n">conda</span> <span class="n">activate</span> <span class="n">nilearn</span>
</pre></div>
</div>
</li>
<li><p>install the forked version of <cite>nilearn</cite>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">.</span> <span class="o">-</span><span class="n">e</span>
</pre></div>
</div>
</li>
<li><p>install development dependencies:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">r</span> <span class="n">requirements</span><span class="o">-</span><span class="n">dev</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
</li>
<li><p>check that all tests pass with (this can take a while):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pytest</span> <span class="n">nilearn</span>
</pre></div>
</div>
</li>
</ol>
</div>
<div class="section" id="id6">
<h3><a class="toc-backref" href="#id19">Contributing</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
<p>Here are the key steps you need to go through to contribute code to <cite>nilearn</cite>:</p>
<ol class="arabic">
<li><p>open or join an already existing issue explaining what you want to work on</p></li>
<li><p>on your fork, create a new branch from main:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">your_branch</span>
</pre></div>
</div>
</li>
<li><p>implement and commit your changes on this branch (don’t forget to write tests!)</p></li>
<li><p>run the tests locally (to go faster, only run tests which are relevant to what
you work on with, for example):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pytest</span> <span class="o">-</span><span class="n">v</span> <span class="n">nilearn</span><span class="o">/</span><span class="n">plotting</span><span class="o">/</span><span class="n">tests</span><span class="o">/</span><span class="n">test_surf_plotting</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
</li>
<li><p>push your changes to your online fork:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">push</span>
</pre></div>
</div>
</li>
<li><p>in github, open a pull request from your online fork to the main repo
(most likely from <cite>your_fork:your_branch</cite> to <cite>nilearn:main</cite>).</p></li>
<li><p>check that all continuous integration tests pass</p></li>
</ol>
<p>For more details about the Fork Clone Push workflows, read <a class="reference external" href="https://guides.github.com/activities/forking/">here</a>.</p>
</div>
<div class="section" id="building-documentation">
<h3><a class="toc-backref" href="#id20">Building documentation</a><a class="headerlink" href="#building-documentation" title="Permalink to this headline">¶</a></h3>
<p>If you wish to build documentation:</p>
<ol class="arabic">
<li><p>First, ensure that you have installed sphinx and sphinx-gallery. When in your
fork top folder, you can install the required packages using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">r</span> <span class="n">requirements</span><span class="o">-</span><span class="n">build</span><span class="o">-</span><span class="n">docs</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
</li>
<li><p>Then go to <code class="docutils literal notranslate"><span class="pre">nilearn/examples</span></code> or <code class="docutils literal notranslate"><span class="pre">nilearn/doc</span></code> and make needed changes
using <a class="reference external" href="https://www.sphinx-doc.org/en/2.0/usage/restructuredtext/basics.html">reStructuredText files</a></p></li>
<li><p>You can now go to <cite>nilearn/doc</cite> and build the examples locally:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">html</span><span class="o">-</span><span class="n">strict</span>
</pre></div>
</div>
<p>or, if you do not have make install (for instance under Windows):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">sphinx</span> <span class="o">-</span><span class="n">b</span> <span class="n">html</span> <span class="o">-</span><span class="n">d</span> <span class="n">_build</span><span class="o">/</span><span class="n">doctrees</span> <span class="o">.</span> <span class="n">_build</span><span class="o">/</span><span class="n">html</span>
</pre></div>
</div>
<p>if you don’t need the plots, a quicker option is:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">html</span><span class="o">-</span><span class="n">noplot</span>
</pre></div>
</div>
</li>
<li><p>Visually review the output in <code class="docutils literal notranslate"><span class="pre">nilearn/doc/_build/html/auto_examples/</span></code>.
If all looks well and there were no errors, commit and push the changes.</p></li>
<li><p>You can now open a Pull Request from Nilearn’s Pull Request page.</p></li>
<li><p>Request the CI builds the full documentation from your branch:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">--</span><span class="n">allow</span><span class="o">-</span><span class="n">empty</span> <span class="o">-</span><span class="n">m</span> <span class="s2">"[circle full] request full build"</span>
</pre></div>
</div>
</li>
</ol>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>When generating documentation locally, you can build only specific files
to reduce building time. To do so, use the <code class="docutils literal notranslate"><span class="pre">filename_pattern</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">sphinx</span> <span class="o">-</span><span class="n">D</span> <span class="n">sphinx_gallery_conf</span><span class="o">.</span><span class="n">filename_pattern</span><span class="o">=</span>\\
<span class="n">plot_decoding_tutorial</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">b</span> <span class="n">html</span> <span class="o">-</span><span class="n">d</span> <span class="n">_build</span><span class="o">/</span><span class="n">doctrees</span> <span class="o">.</span> <span class="n">_build</span><span class="o">/</span><span class="n">html</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="additional-cases">
<h2><a class="toc-backref" href="#id21">Additional cases</a><a class="headerlink" href="#additional-cases" title="Permalink to this headline">¶</a></h2>
<div class="section" id="how-to-contribute-an-atlas">
<h3><a class="toc-backref" href="#id22">How to contribute an atlas</a><a class="headerlink" href="#how-to-contribute-an-atlas" title="Permalink to this headline">¶</a></h3>
<p>We want atlases in nilearn to be internally consistent. Specifically,
your atlas object should have three attributes (as with the existing
atlases):</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">description</span></code> (bytes): A text description of the atlas. This should be
brief but thorough, describing the source (paper), relevant information
related to its construction (modality, dataset, method), and, if there is
more than one map, a description of each map.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">labels</span></code> (list): a list of string labels corresponding to each atlas
label, in the same (numerical) order as the atlas labels</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">maps</span></code> (list or string): the path to the nifti image, or a list of paths</p></li>
</ul>
<p>In addition, the atlas will need to be called by a fetcher. For example, see <a class="reference external" href="https://github.com/nilearn/nilearn/blob/main/nilearn/datasets/atlas.py">here</a>.</p>
<p>Finally, as with other features, please provide a test for your atlas.
Examples can be found <a class="reference external" href="https://github.com/nilearn/nilearn/blob/main/nilearn/datasets/tests/test_atlas.py">here</a></p>
</div>
<div class="section" id="how-to-contribute-a-dataset-fetcher">
<h3><a class="toc-backref" href="#id23">How to contribute a dataset fetcher</a><a class="headerlink" href="#how-to-contribute-a-dataset-fetcher" title="Permalink to this headline">¶</a></h3>
<p>The <a class="reference internal" href="modules/reference.html#module-nilearn.datasets" title="nilearn.datasets"><code class="xref py py-mod docutils literal notranslate"><span class="pre">nilearn.datasets</span></code></a> module provides functions to download some
neuroimaging datasets, such as <a class="reference internal" href="modules/generated/nilearn.datasets.fetch_haxby.html#nilearn.datasets.fetch_haxby" title="nilearn.datasets.fetch_haxby"><code class="xref py py-func docutils literal notranslate"><span class="pre">nilearn.datasets.fetch_haxby</span></code></a> or
<a class="reference internal" href="modules/generated/nilearn.datasets.fetch_atlas_harvard_oxford.html#nilearn.datasets.fetch_atlas_harvard_oxford" title="nilearn.datasets.fetch_atlas_harvard_oxford"><code class="xref py py-func docutils literal notranslate"><span class="pre">nilearn.datasets.fetch_atlas_harvard_oxford</span></code></a>. The goal is not to provide a comprehensive
collection of downloaders for the most widely used datasets, and this would be
outside the scope of this project. Rather, this module provides data downloading utilities that are
required to showcase nilearn features in the example gallery.</p>
<p>Downloading data takes time and large datasets slow down the build of the
example gallery. Moreover, downloads can fail for reasons we do not control,
such as a web service that is temporarily unavailable. This is frustrating for
users and a major issue for continuous integration (new code cannot be merged
unless the examples run successfully on the CI infrastructure). Finally,
datasets or the APIs that provide them sometimes change, in which case the
downloader needs to be adapted.</p>
<p>As for any contributed feature, before starting working on a new downloader,
we recommend opening an issue to discuss whether it is necessary or if existing
downloaders could be used instead.</p>
<p>To add a new fetcher, <code class="docutils literal notranslate"><span class="pre">nilearn.datasets.utils</span></code> provides some helper functions,
such as <code class="docutils literal notranslate"><span class="pre">_get_dataset_dir</span></code> to find a directory where the dataset is or will be
stored according to the user’s configuration, or <code class="docutils literal notranslate"><span class="pre">_fetch_files</span></code> to load files
from the disk or download them if they are missing.</p>
<p>The new fetcher, as any other function, also needs to be tested (in the relevant
submodule of <code class="docutils literal notranslate"><span class="pre">nilearn.datasets.tests</span></code>). When the tests run, the fetcher does
not have access to the network and will not actually download files. This is to
avoid spurious failures due to unavailable network or servers, and to avoid
slowing down the tests with long downloads.
The functions from the standard library and the <code class="docutils literal notranslate"><span class="pre">requests</span></code> library that
nilearn uses to download files are mocked: they are replaced with dummy
functions that return fake data.</p>
<p>Exactly what fake data is returned can be configured through the object
returned by the <code class="docutils literal notranslate"><span class="pre">request_mocker</span></code> pytest fixture, defined in
<code class="docutils literal notranslate"><span class="pre">nilearn.datasets._testing</span></code>. The docstrings of this module and the <code class="docutils literal notranslate"><span class="pre">Sender</span></code>
class it contains provide information on how to write a test using this fixture.
Existing tests can also serve as examples.</p>
</div>
</div>
<div class="section" id="maintenance">
<h2><a class="toc-backref" href="#id24">Maintenance</a><a class="headerlink" href="#maintenance" title="Permalink to this headline">¶</a></h2>
<p>More information about the project organization, conventions, and maintenance
process can be found there : <a class="reference internal" href="maintenance.html#maintenance-process"><span class="std std-ref">Nilearn maintenance process</span></a>.</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h4> Giving credit </h4>
<ul class="simple">
<li><p>Please consider <a href="authors.html#citing">citing the
papers</a>.</p></li>
</ul>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Nilearn development process</a><ul>
<li><a class="reference internal" href="#how-to-help">How to help?</a></li>
<li><a class="reference internal" href="#how-do-we-decide-what-code-goes-in">How do we decide what code goes in?</a><ul>
<li><a class="reference internal" href="#scope-of-the-project">Scope of the project</a></li>
<li><a class="reference internal" href="#who-makes-decisions">Who makes decisions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#how-to-contribute-to-nilearn">How to contribute to nilearn</a><ul>
<li><a class="reference internal" href="#contribution-guidelines">Contribution Guidelines</a></li>
<li><a class="reference internal" href="#pr-structure">PR Structure</a></li>
<li><a class="reference internal" href="#coding-style">Coding Style</a></li>
<li><a class="reference internal" href="#tests">Tests</a></li>
<li><a class="reference internal" href="#documentation">Documentation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#setting-up-your-environment">Setting up your environment</a><ul>
<li><a class="reference internal" href="#installing">Installing</a></li>
<li><a class="reference internal" href="#id6">Contributing</a></li>
<li><a class="reference internal" href="#building-documentation">Building documentation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#additional-cases">Additional cases</a><ul>
<li><a class="reference internal" href="#how-to-contribute-an-atlas">How to contribute an atlas</a></li>
<li><a class="reference internal" href="#how-to-contribute-a-dataset-fetcher">How to contribute a dataset fetcher</a></li>
</ul>
</li>
<li><a class="reference internal" href="#maintenance">Maintenance</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="whats_new.html"
title="previous chapter">0.8.2.dev</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="maintenance.html"
title="next chapter">Nilearn maintenance process</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© The nilearn developers 2010-2021.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 4.0.2.
<span style="padding-left: 5ex;">
<a href="_sources/development.rst.txt"
rel="nofollow">Show this page source</a>
</span>
</div>
</body>
</html>