neurosynchro: the main module

Train and use artificial neural network approximations (“regressions”) of synchrotron radiative transfer coefficients as a function of various physical input parameters.

The meat of the neural network code is in the impl module to avoid importing Keras unless needed.

The top-level module of neurosynchro does not actually include any neural-network functionality: such functionality requires loading the keras module, which is very slow to initialize. Instead, this module contains generic code for dealing with training set data and radiative transfer coefficients:

Loading Training Set Data

neurosynchro.basic_load(datadir, drop_metadata=True)[source]

Load a directory of textual tables (such as training set data).

Call signature

datadir
A path to a directory of textual tables; format described below.
drop_metadata (default True)
If true, columns marked as metadata will be dropped from the returned table.
Return value
A pandas.DataFrame of data, concatenating all of the input tables.

The data format is documented in Make Your Training Set. Briefly, each file in datadir whose name ends with .txt will be loaded as a table using pandas.read_table(). The recommended format is tab-separated values with a single header row. Column names should end in type identifiers such as (lin) to identify their roles, although this function ignores this information except to drop columns whose names end in (meta) if so directed.

Working With Radiative Transfer Coefficients

neurosynchro.detrivialize_stokes_basis(coeffs, psi)[source]

Re-express coefficients in a basis in which the magnetic field can rotate on the sky.

Arguments

coeffs
Radiative transfer coefficients in the Stokes basis where the Stokes U axis is aligned with the magnetic field. This is an array of shape (S, 8) where S is the shape of psi. Along the inner axis of the array, the coefficients are: (j_I, alpha_I, j_Q, alpha_Q, j_V, alpha_V, rho_Q, rho_V). This is the representation returned by neurosynchro.impl.PhysicalApproximator.compute_all_nontrivial().
psi
The angle(s) between the magnetic field as projected on the sky and some invariant Stokes U axis, in radians. XXX: sign convention?

Return value

An array of radiative transfer coefficients in which the Stokes U terms are no longer trivial. The shape is (S, 11). Along the inner axis of the array, the coefficients are: (j_I, alpha_I, j_Q, alpha_Q, j_U, alpha_U, j_V, alpha_V, rho_Q, rho_U, rho_V).

Details

Synchrotron calculations are generally performed in a basis in which the Stokes U axis is aligned with the magnetic field, which means that the corresponding radiative transfer coefficients are zero (“trivial”). In actual work, however, the magnetic field orientation is not guaranteed to be constant along the direction of propagation. If the Stokes U axis is held fixed along the integration, the Stokes U coefficients become nontrivial. This function transforms coefficients from the former basis to the latter.

See Shcherbakov & Huang (2011MNRAS.410.1052S), equations 50-51. Note that the linear polarization axis rotates at twice the rate that psi does, because linear polarization is an orientation not an angle.

Mappings

class neurosynchro.Mapping(name)[source]

An abstract base class for parameter transformations.

Mapping classes are used to translate the physical parameters fed into neurosynchro into normalized values that are easier to work with numerically. You will not normally need to use them directly.

classmethod from_info_and_samples(info, phys_samples)[source]

Create a new Mapping from a dictionary of information and a set of samples.

Call signature

info
A dictionary of attributes, passed into Mapping.from_dict().
phys_samples
A 1D Numpy array of samples of this parameter, in no particular order.
Return value
A new instance of Mapping (or one of its subclasses) with initialized bounds parameters.
classmethod from_dict(info, load_bounds=True)[source]

Deserialize an ordered dictionary into a new Mapping instance.

Call signature

info
A dictionary of parameters, as generated by Mapping.to_dict().
load_bounds (default: True)
If true, deserialize bounds information such as the maximum and minimum observed physical values. If False, these are left uninitialized.
Return value
A new Mapping instance.
phys_to_norm(phys)[source]

Map “physical” parameters to normalized values

Argument

phys
An array of “physical” input values (see How Neurosynchro transforms parameters).

Return values

This method returns a tuple (normalized, oos).

normalized
The normalized versions of the input data.
oos
An array of booleans of the same shape as the input data. True values indicate inputs that were out of the sample that was used to define the mapping.
norm_to_phys(norm)[source]

Map “normalized” parameters to “physical” values

Argument

norm
An array of “normalized” input values (see How Neurosynchro transforms parameters).

Return values

This method returns a tuple (phys, oos).

phys
The physical versions of the input data.
oos
An array of booleans of the same shape as the input data. True values indicate inputs that were out of the sample that was used to define the mapping.
to_dict()[source]

Serialize this Mapping into an ordered dictionary.

neurosynchro.mapping_from_info_and_samples(info, phys_samples)[source]

Create a Mapping subclass from configuration data and sample data.

Call signature

info
A dictionary of configuration info, loaded from nn_config.toml or created by Mapping.to_dict().
phys_samples
A 1D array of training data used to initialize the bounds of this mapping.
Return value
A new Mapping instance. The particular subclass used depends on the maptype setting, as documented in the Map Types.
neurosynchro.mapping_from_dict(info)[source]

Create a Mapping subclass from configuration data.

Call signature

info
A dictionary of configuration info, loaded from nn_config.toml or created by Mapping.to_dict().
Return value
A new Mapping instance. The particular subclass used depends on the maptype setting, as documented in the Map Types.

Unlike mapping_from_info_and_samples(), the bounds data are not initialized if they are not already defined in the configuration dictionary.