# binoculars package

## Subpackages

- binoculars.backends package
  - Submodules
  - binoculars.backends.bm25 module
    - `EDFInput`
      - `EDFInput.apply_mask()`
      - `EDFInput.generate_jobs()`
      - `EDFInput.get_destination_options()`
      - `EDFInput.get_images()`
      - `EDFInput.list_images()`
      - `EDFInput.parse_config()`
      - `EDFInput.process_job()`
    - `EH2SCD`
      - `EH2SCD.monitor_counter`
      - `EH2SCD.parse_config()`
      - `EH2SCD.process_image()`
      - `EH2SCD.qconv`
    - `HKLProjection`
      - `HKLProjection.get_axis_labels()`
      - `HKLProjection.project()`
    - `HKProjection`
      - `HKProjection.get_axis_labels()`
      - `HKProjection.project()`
    - `QProjection`
      - `QProjection.get_axis_labels()`
      - `QProjection.project()`
    - `QinpProjection`
      - `QinpProjection.get_axis_labels()`
      - `QinpProjection.project()`
  - binoculars.backends.example module
    - `Input`
      - `Input.generate_jobs()`
      - `Input.get_destination_options()`
      - `Input.parse_config()`
      - `Input.process_job()`
    - `QProjection`
      - `QProjection.get_axis_labels()`
      - `QProjection.project()`
  - binoculars.backends.id03 module
    - `CylindricalQProjection`
      - `CylindricalQProjection.get_axis_labels()`
      - `CylindricalQProjection.project()`
    - `EH1`
      - `EH1.get_point_params()`
      - `EH1.monitor_counter`
      - `EH1.parse_config()`
      - `EH1.process_image()`
    - `EH2`
      - `EH2.get_point_params()`
      - `EH2.monitor_counter`
      - `EH2.parse_config()`
      - `EH2.process_image()`
    - `GammaDelta`
      - `GammaDelta.get_axis_labels()`
      - `GammaDelta.project()`
    - `GammaDeltaMu`
      - `GammaDeltaMu.get_axis_labels()`
      - `GammaDeltaMu.project()`
    - `GammaDeltaTheta`
      - `GammaDeltaTheta.get_axis_labels()`
      - `GammaDeltaTheta.project()`
    - `GisaxsDetector`
      - `GisaxsDetector.find_edfs()`
      - `GisaxsDetector.get_point_params()`
      - `GisaxsDetector.monitor_counter`
      - `GisaxsDetector.parse_config()`
      - `GisaxsDetector.process_image()`
    - `HKLProjection`
      - `HKLProjection.get_axis_labels()`
      - `HKLProjection.project()`
    - `HKProjection`
      - `HKProjection.get_axis_labels()`
      - `HKProjection.project()`
    - `ID03Input`
      - `ID03Input.apply_mask()`
      - `ID03Input.dbg_pointno`
      - `ID03Input.dbg_scanno`
      - `ID03Input.find_edfs()`
      - `ID03Input.generate_jobs()`
      - `ID03Input.get_delayed_jobs()`
      - `ID03Input.get_delayed_scan()`
      - `ID03Input.get_destination_options()`
      - `ID03Input.get_images()`
      - `ID03Input.get_scan()`
      - `ID03Input.get_scan_params()`
      - `ID03Input.get_wavelength()`
      - `ID03Input.is_aborted()`
      - `ID03Input.is_zap()`
      - `ID03Input.parse_config()`
      - `ID03Input.process_job()`
      - `ID03Input.target()`
      - `ID03Input.wait_for_points()`
    - `QProjection`
      - `QProjection.get_axis_labels()`
      - `QProjection.project()`
    - `QTransformation`
      - `QTransformation.get_axis_labels()`
      - `QTransformation.parse_config()`
      - `QTransformation.project()`
    - `Qpp`
      - `Qpp.get_axis_labels()`
      - `Qpp.project()`
    - `SphericalQProjection`
      - `SphericalQProjection.get_axis_labels()`
      - `SphericalQProjection.project()`
    - `ThetaLProjection`
      - `ThetaLProjection.get_axis_labels()`
      - `ThetaLProjection.project()`
    - `TwoThetaProjection`
      - `TwoThetaProjection.get_axis_labels()`
      - `TwoThetaProjection.project()`
    - `load_matrix()`
    - `nrQProjection`
      - `nrQProjection.get_axis_labels()`
      - `nrQProjection.project()`
    - `pixels`
      - `pixels.get_axis_labels()`
      - `pixels.project()`
    - `specularangles`
      - `specularangles.get_axis_labels()`
      - `specularangles.project()`
  - binoculars.backends.id03_xu module
    - `EH2`
      - `EH2.get_point_params()`
      - `EH2.monitor_counter`
      - `EH2.parse_config()`
      - `EH2.process_image()`
      - `EH2.qconv`
      - `EH2.ty`
    - `HKLProjection`
      - `HKLProjection.get_axis_labels()`
      - `HKLProjection.project()`
    - `HKProjection`
      - `HKProjection.get_axis_labels()`
      - `HKProjection.project()`
    - `ID03Input`
      - `ID03Input.apply_mask()`
      - `ID03Input.find_edfs()`
      - `ID03Input.generate_jobs()`
      - `ID03Input.get_destination_options()`
      - `ID03Input.get_images()`
      - `ID03Input.get_scan()`
      - `ID03Input.get_scan_params()`
      - `ID03Input.parse_config()`
      - `ID03Input.process_job()`
    - `QProjection`
      - `QProjection.get_axis_labels()`
      - `QProjection.project()`
  - binoculars.backends.sixs module
  - Module contents

## Submodules

## binoculars.backend module

class binoculars.backend.InputBase(config)

  Bases: `ConfigurableObject`

  Generate and process Job()s.

  Note: there is no guarantee that generate_jobs() and process_jobs() will be called on the same instance, not even in the same process or on the same computer!

  generate_jobs(command)

    Receives command from user, yields Job() instances

  get_destination_options(command)

    Receives the same command as generate_jobs(), but returns dictionary that will be used to .format() the dispatcher:destination configuration value.

  parse_config(config)
  process_job(job)

    Receives a Job() instance, yields (intensity, args_to_be_sent_to_a_Projection_instance)

    > Job()s could have been pickle’d and distributed over a cluster

class binoculars.backend.Job(**kwargs)

  Bases: `object`

  weight = 1.0

class binoculars.backend.ProjectionBase(config)

  Bases: `ConfigurableObject`

  get_axis_labels()
  parse_config(config)
  project(*args)

binoculars.backend.get_dispatcher(config, main, default=None)

binoculars.backend.get_input(config, default=None)

binoculars.backend.get_projection(config, default=None)

## binoculars.dispatcher module

class binoculars.dispatcher.Destination

  Bases: `object`

  config = None
  filename = None
  final_filenames()
  limits = None
  opts: Dict[Any, Any] = {}
  overwrite = None
  retrieve()
  set_config(conf)
  set_final_filename(filename, overwrite)
  set_final_options(opts)
  set_limits(limits)
  set_memory()
  set_tmp_filename(filename)
  store(verse)
  type = None
  value = None

class binoculars.dispatcher.DispatcherBase(config, main)

  Bases: `ConfigurableObject`

  has_specific_task()
  parse_config(config)
  process_jobs(jobs)
  send(verses)
  sum(results)

class binoculars.dispatcher.Local(config, main)

  Bases: `ReentrantBase`

  actions = ('user', 'job')
  parse_config(config)
  prepare_config(job)
  process_jobs(jobs)
  run_specific_task(command)
  sum(results)

class binoculars.dispatcher.Oar(config, main)

  Bases: `ReentrantBase`

  actions = ('user', 'process')
  oar_cleanup(jobs)
  oarstat(jobid)
  oarsub(*args)
  oarwait(jobs, remaining=0)
  parse_config(config)
  process_jobs(jobs)
  run_specific_task(command)
  static subprocess_run(*command)
  sum(results)

class binoculars.dispatcher.ReentrantBase(config, main)

  Bases: `DispatcherBase`

  actions: Tuple[str, ...] = ('user',)
  has_specific_task()
  parse_config(config)
  run_specific_task(command)

class binoculars.dispatcher.SingleCore(config, main)

  Bases: `DispatcherBase`

  process_jobs(jobs)
  sum(results)

## binoculars.errors module

exception binoculars.errors.BackendError

  Bases: `ExceptionBase`

exception binoculars.errors.CommunicationError

  Bases: `ExceptionBase`

exception binoculars.errors.ConfigError

  Bases: `ExceptionBase`

exception binoculars.errors.ExceptionBase

  Bases: `Exception`

exception binoculars.errors.FileError

  Bases: `ExceptionBase`

exception binoculars.errors.HDF5FileError

  Bases: `FileError`

exception binoculars.errors.SubprocessError

  Bases: `ExceptionBase`

binoculars.errors.addmessage(args, errormsg)

## binoculars.fit module

class binoculars.fit.AutoDimensionFit(space, guess=None)

  Bases: `FitBase`

class binoculars.fit.FitBase(space, guess=None)

  Bases: `object`

  fitdata = None
  guess = None
  parameters = None
  result = None
  summary = None

class binoculars.fit.Gaussian1D(space, guess=None, loc=None)

  Bases: `PeakFitBase`

  static func(grid, params)

class binoculars.fit.Lorentzian(space, guess=None)

  Bases: `AutoDimensionFit`

  dimensions = {1: <class 'binoculars.fit.Lorentzian1D'>, 2: <class 'binoculars.fit.PolarLorentzian2D'>}

class binoculars.fit.Lorentzian1D(space, guess=None, loc=None)

  Bases: `PeakFitBase`

  static func(grid, params)
  set_guess(maximum, argmax, linparams)

class binoculars.fit.Lorentzian1DNoBkg(space, guess=None, loc=None)

  Bases: `PeakFitBase`

  static func(grid, params)
  set_guess(maximum, argmax, linparams)

class binoculars.fit.Lorentzian2D(space, guess=None, loc=None)

  Bases: `PeakFitBase`

  static func(grid, params)
  set_guess(maximum, argmax, linparams)

class binoculars.fit.Lorentzian2Dnobkg(space, guess=None, loc=None)

  Bases: `PeakFitBase`

  static func(grid, params)
  set_guess(maximum, argmax, linparams)

class binoculars.fit.PeakFitBase(space, guess=None, loc=None)

  Bases: `FitBase`

class binoculars.fit.PolarLorentzian2D(space, guess=None, loc=None)

  Bases: `PeakFitBase`

  static func(grid, params)
  integrate_signal()
  set_guess(maximum, argmax, linparams)

class binoculars.fit.PolarLorentzian2Dnobkg(space, guess=None, loc=None)

  Bases: `PeakFitBase`

  static func(grid, params)
  set_guess(maximum, argmax, linparams)

class binoculars.fit.Voigt1D(space, guess=None, loc=None)

  Bases: `PeakFitBase`

  static func(grid, params)
  set_guess(maximum, argmax, linparams)

binoculars.fit.get_class_by_name(name)

binoculars.fit.rot2d(x, y, th)

binoculars.fit.rot3d(x, y, z, th, ph)

## binoculars.main module

class binoculars.main.Main(config, command)

  Bases: `object`

  clone_config()
  classmethod from_args(args)
  classmethod from_object(config, command)
  get_reentrant()
  process_job(job)
  run(command)

class binoculars.main.Split(config, command)

  Bases: `Main`

  process_job(job)
  run()

binoculars.main.multiprocessing_main(xxx_todo_changeme)

  note the double parenthesis for map() convenience

binoculars.main.parse_args(args)

binoculars.main.parse_commandline_config_option(s)

## binoculars.plot module

class binoculars.plot.DraggableColorbar(cbar, mappable)

  Bases: `object`

  connect()
  disconnect()
  key_press(event)
  on_motion(event)
  on_press(event)
  on_release(event)

binoculars.plot.get_clipped_norm(data, clipping=0.0, log=True)

binoculars.plot.plot(space: Space, fig: Figure, ax: Axes, log: bool = True, loglog: bool = False, clipping: float = 0.0, fit: bool | None = None, norm: float | None = None, colorbar: bool = True, labels: bool = True, interpolation: str = 'nearest', **plotopts) → List[Line2D]

## binoculars.space module

class binoculars.space.Axes(axes)

  Bases: `object`

  Luxurious tuple of Axis objects.

  property dimension
  classmethod fromarray(arr)
  classmethod fromfile(filename: str) → Axes
  index(obj: Axis | int | str) → int
  property memory_size
  property npoints
  restricted_key(key)
  toarray()
  tofile(filename)

class binoculars.space.Axis(min, max, res, label=None)

  Bases: `object`

  Represents a single dimension finite discrete grid centered at 0.

  Important attributes: min lower bound max upper bound res step size / resolution label human-readable identifier

  min, max and res are floats, but internally only integer operations are used. In particular min = imin * res, max = imax * res

  get_index(value: float | slice | ndarray) → int | slice | ndarray
  is_compatible(other)
  property max
  property min
  rebin(factor)
  rebound(min, max)
  restrict(value: float | slice) → float | slice
  restrict_slice(value: slice) → slice

class binoculars.space.EmptySpace(config=None, metadata=None)

  Bases: `object`

  Convenience object for sum() and friends. Treated as zero for addition. Does not share a base class with Space for simplicity.

  tofile(filename)

    Store EmptySpace in HDF5 file.

class binoculars.space.EmptyVerse

  Bases: `object`

  Convenience object for sum() and friends. Treated as zero for addition.

  property dimension
  spaces = [EmptySpace]

class binoculars.space.Multiverse(spaces)

  Bases: `object`

  A collection of spaces with basic support for addition. Only to be used when processing data. This makes it possible to process multiple limit sets in a combination of scans

  property dimension
  classmethod fromfile(file)

    Load Multiverse from HDF5 file.

  tofile(filename)

class binoculars.space.Space(axes, config=None, metadata=None)

  Bases: `object`

  Main data-storing object in BINoculars. Data is represented on an n-dimensional rectangular grid. Per grid point, the number of photons (~ intensity) and the number of original data points (pixels) contribution is stored.

  Important attributes:

    axes Axes instances describing range and stepsizes of each of the dimensions photons n-dimension numpy float array, total intensity per grid point contribitions n-dimensional numpy integer array, number of original datapoints (pixels) per grid point dimension n

  argmax()

    Returns data coordinates of grid point with maximum intensity.

  property config

    util.ConfigFile instance describing configuration file used to create this Space instance

  copy()

    Returns a copy of self. Numpy data is not shared, but the Axes object is.

  property dimension
  classmethod from_image(resolutions, labels, coordinates, intensity, weights, limits=None)

    Create Space from image data.

    resolutions n-tuple of axis resolutions labels n-tuple of axis labels coordinates n-tuple of data coordinate arrays intensity data intensity array

  classmethod fromfile(file: str, key: Sequence[slice] | None = None) → Space

    Load Space from HDF5 file.

    file filename string or h5py.Group instance key sliced (subset) loading, should be an n-tuple of slice()s in data coordinates

  get()

    Returns normalized photon count.

  get_grid() → Tuple[ndarray]

    Returns the data coordinates of each grid point, as n-tuple of n-dimensinonal arrays. Basically numpy.mgrid() in data coordinates.

  get_key(key: float | slice | Tuple[float | slice | ndarray, ...] | List[float | slice | ndarray]) → Tuple[int | slice | ndarray, ...]

    Convert the n-dimensional interval described by key (as used by e.g. __getitem__()) from data coordinates to indices.

  get_masked() → MaskedArray

    Returns photons/contributions, but with divide-by-zero’s masked out.

  get_variance()
  max(axis=None)

    Returns maximum intensity.

  property memory_size

    Returns approximate memory consumption of this Space. Only considers size of .photons and .contributions, does not take into account the overhead.

  property metadata

    util.MetaData instance describing metadata used to create this Space instance

  property npoints
  process_image(coordinates, intensity, weights)

    Load image data into Space.

    coordinates n-tuple of data coordinate arrays intensity data intensity array weights weights array, supply numpy.ones_like(intensity) for equal weights

  project(axis: str | int, *more_axes) → Space

    Reduce dimensionality of Space by projecting onto ‘axis’. All data (photons, contributions) is summed along this axis.

    axis the label of the axis or the index *more_axis also project on these axes

  rebin(resolutions)

    Change bin size.

    resolution n-tuple of floats, new resolution of each axis

  reorder(labels)

    Change order of axes.

  slice(axis, key)

    Single-axis slice.

    axis label or index of axis to slice key something like slice(lower_data_range, upper_data_range)

  tofile(filename)

    Store Space in HDF5 file.

  transform_coordinates(resolutions, labels, transformation)
  trim()

    Reduce total size of Space by trimming zero-contribution data points on the boundaries.

binoculars.space.axis_offset(space, label, offset)

binoculars.space.bkgsubtract(space, bkg)

binoculars.space.chunked_sum(verses: Iterable[Multiverse], chunksize=10) → EmptyVerse | Multiverse

  Calculate sum of iterable of Multiverse instances. Creates intermediate sums to avoid growing a large space at every summation.

  verses iterable of Multiverse instances chunksize number of Multiverse instances in each intermediate sum

binoculars.space.dstack(spaces, dindices, dlabel, dresolution)

binoculars.space.get_axis_values(axes, axis, resolution=None) → ndarray

binoculars.space.get_bins(ax: Axis, resolution: float) → ndarray

binoculars.space.iterate_over_axis(space, axis, resolution=None)

binoculars.space.iterate_over_axis_keys(axes, axis, resolution=None)

binoculars.space.make_compatible(spaces)

binoculars.space.silence_numpy_errors()

  Silence numpy warnings about zero division. Normal usage of Space() will trigger these warnings.

binoculars.space.sum(spaces)

  Calculate sum of iterable of Space instances.

binoculars.space.sum_onto(a, axis)

  Numpy convenience. Project all dimensions of an array onto an axis, i.e. apply sum() to all axes except the one given.

binoculars.space.union_axes(axes)

binoculars.space.union_unequal_axes(axes)

binoculars.space.verse_sum(verses: Generator[Multiverse, None, None]) → Multiverse

## binoculars.util module

class binoculars.util.ConfigFile(origin='n/a', command=[])

  Bases: `MetaBase`

  classmethod fromfile(filename)
  classmethod fromtxtfile(filename, command=[], overrides=[])
  tofile(filename)
  totxtfile(filename)

class binoculars.util.ConfigSection(**kwargs)

  Bases: `object`

  copy()

class binoculars.util.ConfigSectionGroup(origin='n/a')

  Bases: `object`

class binoculars.util.ConfigurableObject(config)

  Bases: `object`

  parse_config(config)

class binoculars.util.MetaBase(label=None, section=None)

  Bases: `object`

  add_section(label, section=None)
  copy()
  classmethod fromserial(s)
  serialize()

class binoculars.util.MetaData

  Bases: `object`

  add_dataset(dataset)
  classmethod fromfile(filename)
  classmethod fromserial(s)
  serialize()
  tofile(filename)

class binoculars.util.OrderedOperation(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None, deprecated=False)

  Bases: `Action`

binoculars.util.argparse_common_arguments(parser, *args)

binoculars.util.as_string(text)

binoculars.util.atomic_write(filename)

  Atomically write data into ‘filename’ using a temporary file and os.rename()

  Rename on success, clean up on failure (any exception).

  Example: with atomic_write(filename) as tmpfile

  > with open(tmpfile, ‘w’) as fp:

  >   fp.write(…)

binoculars.util.best_effort_atomic_rename(src, dest)

binoculars.util.chunk_slicer(count, chunksize)

  yields slice() objects that split an array of length ‘count’ into equal sized chunks of at most ‘chunksize’

binoculars.util.cluster_jobs(jobs, target_weight)

binoculars.util.cluster_jobs2(jobs, target_weight)

  Taking the first n jobs that together add up to target_weight. Here as opposed to cluster_jobs the total number of jobs does not have to be known beforehand

binoculars.util.filename_enumerator(filename, start=0)

binoculars.util.find_unused_filename(filename)

binoculars.util.find_unused_label(label, labellist)

binoculars.util.format_bytes(bytes)

binoculars.util.get_backend_configkeys(modname, classname)

binoculars.util.get_backends()

binoculars.util.get_base(modname, base)

binoculars.util.get_configkeys(cls)

binoculars.util.get_dispatcher_configkeys(classname)

binoculars.util.get_dispatchers()

binoculars.util.get_input_configkeys(modname, classname)

binoculars.util.get_inputs(module)

binoculars.util.get_projection_configkeys(modname, classname)

binoculars.util.get_projections(module)

binoculars.util.get_python_executable()

binoculars.util.grouper(iterable, n)

binoculars.util.handle_ordered_operations(space, args, auto3to2=False)

binoculars.util.label_enumerator(label, start=0)

binoculars.util.limit_to_filelabel(s)

binoculars.util.loop_delayer(delay)

  Delay a loop such that it runs at most once every ‘delay’ seconds. Usage example: delay = loop_delayer(5) while some_condition:

  > next(delay) do_other_tasks

binoculars.util.open_h5py(fn, mode)

binoculars.util.packet_slicer(length, size=1024)

binoculars.util.parse_bool(s)

binoculars.util.parse_configcode(line)

binoculars.util.parse_dict(config, option, default=None) → dict

binoculars.util.parse_float(config, option, default=None)

binoculars.util.parse_multi_range(s)

binoculars.util.parse_pairs(s)

binoculars.util.parse_range(r)

binoculars.util.parse_transform_args(transform)

binoculars.util.parse_tuple(s, length=None, type=<class 'str'>)

binoculars.util.pickle_load(fileobj)

binoculars.util.register_python_executable(scriptname)

binoculars.util.serialize(space, command)

binoculars.util.socket_recieve(RequestHandler)

binoculars.util.socket_send(ip, port, mssg)

binoculars.util.space_to_edf(space, filename)

binoculars.util.space_to_npy(space, filename)

binoculars.util.space_to_txt(space, filename)

binoculars.util.status(line, eol=False)

  Prints a status line to sys.stdout, overwriting the previous one. Set eol to True to append a newline to the end of the line

binoculars.util.statuscl()

  Clears the status line, shortcut for status(‘’)

binoculars.util.statuseol()

  Starts a new status line, keeping the previous one intact

binoculars.util.statusnl(line)

  Shortcut for status(…, eol=True)

binoculars.util.transformation_from_expressions(space, exprs)

binoculars.util.uniqid()

binoculars.util.wait_for_file(file, timeout=None)

binoculars.util.wait_for_files(filelist, timeout=None)

  Wait until the files in ‘filelist’ have appeared, for a maximum of ‘timeout’ seconds. Returns True on success, False on timeout.

binoculars.util.yield_when_exists(filelist, timeout=None)

  Wait for files in ‘filelist’ to appear, for a maximum of ‘timeout’ seconds, yielding them in arbitrary order as soon as they appear. If ‘filelist’ is a set, it will be modified in place, and on timeout it will contain the files that have not appeared yet.

binoculars.util.zpi_load(filename)

binoculars.util.zpi_save(obj, filename)

## Module contents

binoculars.fitspace(space, function, guess=None)

  fit the space data.

  Parameters space: binoculars space function: list

  > a string with the name of the desired function. supported are: lorentzian (automatically selects 1d or 2d), gaussian1d and voigt1d

  guess: list

    a list of length N with the resolution per label

  Returns A binoculars fit object.

  Examples: >>> fit = binoculars.fitspace(space, ‘lorentzian’) >>> print(fit.summary)

  > I: 1.081e-07 +/- inf loc: 0.3703 +/- inf gamma: 0.02383 +/- inf slope: 0.004559 +/- inf offset: -0.001888 +/- inf

      >>> parameters = fit.parameters
      >>> data = fit.fitdata
      >>> binoculars.plotspace(space, fit = data)

binoculars.info(filename)

  Explore the file without loading the file, or after loading the file

  Parameters filename: filename or space

  Examples: >>> print binoculars.info(‘test.hdf5’) Axes (3 dimensions, 46466628 points, 531.0 MB) {

  > Axis H (min=-0.1184, max=0.0632, res=0.0008, count=228) Axis K (min=-1.1184, max=-0.9136, res=0.0008, count=257) Axis L (min=0.125, max=4.085, res=0.005, count=793)

  } ConfigFile{

  > [dispatcher] [projection] [input]

  } origin = test.hdf5 >>> space = binoculars.load(‘test.hdf5’) >>> print binoculars.info(space) Axes (3 dimensions, 46466628 points, 531.0 MB) {

  > Axis H (min=-0.1184, max=0.0632, res=0.0008, count=228) Axis K (min=-1.1184, max=-0.9136, res=0.0008, count=257) Axis L (min=0.125, max=4.085, res=0.005, count=793)

  } ConfigFile{

  > [dispatcher] [projection] [input]

  } origin = test.hdf5

binoculars.load(filename, key=None)

  Parameters filename: string

  > Only hdf5 files are acceptable

  key: a tuple with slices in as much dimensions as the space is

  Returns A binoculars space

  Examples: >>> space = binoculars.load(‘test.hdf5’) >>> space Axes (3 dimensions, 2848 points, 33.0 kB) {

  > Axis qx (min=-0.01, max=0.0, res=0.01, count=2) Axis qy (min=-0.04, max=-0.01, res=0.01, count=4) Axis qz (min=0.48, max=4.03, res=0.01, count=356)

  }

binoculars.plotspace(space, log=True, clipping=0.0, fit=None, norm=None, colorbar=True, labels=True, **plotopts)

  plots a space with the correct axes. The space can be either one or two dimensinal.

  Parameters space: binoculars space

  > the space containing the data that needs to be plotted

  log: bool

    axes or colorscale logarithmic

  clipping: 0 < float < 1

    cuts a lowest and highst value on the color scale

  fit: numpy.ndarray

  > same shape and the space. If one dimensional the fit will be overlayed.

  norm: matplotlib.colors

    object defining the colorscale

  colorbar: bool

    show or not show the colorbar

  labels: bool

    show or not show the labels

  plotopts: keyword arguments

    keywords that will be accepted by matplotlib.pyplot.plot or matplotlib.pyplot.imshow

  Examples: >>> space Axes (3 dimensions, 2848 points, 33.0 kB) {

  > Axis qx (min=-0.01, max=0.0, res=0.01, count=2) Axis qy (min=-0.04, max=-0.01, res=0.01, count=4) Axis qz (min=0.48, max=4.03, res=0.01, count=356)

  } >>> binoculars.plotspace(‘test.hdf5’)

binoculars.run(args)

  Parameters args: string

  > String as if typed in terminal. The string must consist of the location of the configuration file and the command for specifying the jobs that need to be processed. All additonal configuration file overides can be included

  Returns A tuple of binoculars spaces

  Examples: >>> space = binoculars.run(‘config.txt 10’) >>> space[0] Axes (3 dimensions, 2848 points, 33.0 kB) {

  > Axis qx (min=-0.01, max=0.0, res=0.01, count=2) Axis qy (min=-0.04, max=-0.01, res=0.01, count=4) Axis qz (min=0.48, max=4.03, res=0.01, count=356)

  }

binoculars.save(filename, space)

  Save a space to file

  Parameters filename: string

  > filename to which the data is saved. ‘.txt’, ‘.hdf5’ are supported.

  space: binoculars space

    the space containing the data that needs to be saved

  Examples: >>> space Axes (3 dimensions, 2848 points, 33.0 kB) {

  > Axis qx (min=-0.01, max=0.0, res=0.01, count=2) Axis qy (min=-0.04, max=-0.01, res=0.01, count=4) Axis qz (min=0.48, max=4.03, res=0.01, count=356)

  } >>> binoculars.save(‘test.hdf5’, space)

binoculars.transform(space, labels, resolutions, exprs)

  transformation of the coordinates.

  Parameters space: binoculars space labels: list

  > a list of length N with the labels

  resolutions: list

    a list of length N with the resolution per label

  exprs: list

    a list of length N with strings containing the expressions that will be evaluated. all numpy funtions can be called without adding ‘numpy.’ to the functions.

  Returns A binoculars space of dimension N with labels and resolutions specified in the input

  Examples: >>> space = binoculars.load(‘test.hdf5’) >>> space Axes (3 dimensions, 2848 points, 33.0 kB) {

  > Axis qx (min=-0.01, max=0.0, res=0.01, count=2) Axis qy (min=-0.04, max=-0.01, res=0.01, count=4) Axis qz (min=0.48, max=4.03, res=0.01, count=356)

  } >>> newspace = binoculars.transform(space, [‘twotheta’], [0.003], [‘2 * arcsin(0.51 * (sqrt(qx**2 + qy**2 + qz**2) / (4 * pi)) / (pi * 180))’]) # noqa >>> newspace Axes (1 dimensions, 152 points, 1.0 kB) {

  > Axis twotheta (min=0.066, max=0.519, res=0.003, count=152)

  }