# Conflicts:
#   src/postprocessor/grouper.py

refactor(postproc): make birth event legend label an argument

See merge request aliby!7

WHY IS THIS CHANGE NEEDED?:
- when using single_birth_plot routine, user can change the label in
  the legend that indicates birth events

HOW DOES THE CHANGE SOLVE THE PROBLEM?:
- remove hard-coding of the 'birth event' label by making it an argument
  with the default of 'birth event'.
- this preserves backwards compatibility as i'm creating a new argument
  and the existing argument names are the same

WHAT SIDE EFFECTS DOES THIS CHANGE HAVE?:
- backwards compatibility: existing uses of this routine in scripts will
  produce 'budding event' in plots rather than 'birth event'; if a user
  wants to use 'birth event', they can simply define the argument
  birth_label='birth event'.

EVIDENCE THAT COMMIT WORKS:
- works with a random time series and a binary mask-like numpy array,
  and i can change the legend label

REFERENCES:
- issue #36

WHY IS THIS CHANGE NEEDED?:
- IndexError raised when NameGrouper used to define a grouper object
  and then when .concat_signal() was invoked

HOW DOES THE CHANGE SOLVE THE PROBLEM?:
- effectively reverted to aliby@252915c6
- the two commits leading up to that one solved the problem: first by
  changing chainer's assumption that all experiments have a GFP channel,
  then updated references to renamed variables

WHAT SIDE EFFECTS DOES THIS CHANGE HAVE?:
- risks: may have broken somewhere upstream not otherwise specified yet

EVIDENCE THAT COMMIT WORKS:
- running grouper works

REFERENCES:
- issue #35

WHY IS THIS CHANGE NEEDED?:
- invoked grouper (which used chainer, which in turn is based on
  Signal), encountered AttributeError: 'Chainer' object has no
  attributes 'candidate_channels'

HOW DOES THE CHANGE SOLVE THE PROBLEM?:
- chainer used to rely on av_channels in
  extraction/core/functions/defaults.py, so renamed that to
  candidate_channels
- added a candidate_channels attribute to Signal object to fulfil references

WHY IS THIS CHANGE NEEDED?:
- grouper (which usues chainer) breaks if it accesses a channel that is
  not GFP

HOW DOES THE CHANGE SOLVE THE PROBLEM?:
- chainer assumes all experiments have a GFP channel; this was
  hard-coded in line 29 in chainer.py

WHAT SIDE EFFECTS DOES THIS CHANGE HAVE?:
- yet to test

EVIDENCE THAT COMMIT WORKS:
- pipelines pending

REFERENCES:
- ...