galactocentric_frame_defaults

class astropy.coordinates.galactocentric_frame_defaults[source]

Bases: astropy.utils.state.ScienceState

This class controls the global setting of default values for the frame attributes in the Galactocentric frame, which may be updated in future versions of astropy. Note that when using Galactocentric, changing values here will not affect any attributes that are set explicitly by passing values in to the Galactocentric initializer. Modifying these defaults will only affect the frame attribute values when using the frame as, e.g., Galactocentric or Galactocentric() with no explicit arguments.

This class controls the parameter settings by specifying a string name, with the following pre-specified options:

  • ‘pre-v4.0’: The current default value, which sets the default frame attribute values to their original (pre-astropy-v4.0) values.

  • ‘v4.0’: The attribute values as updated in Astropy version 4.0.

  • ‘latest’: An alias of the most recent parameter set (currently: ‘v4.0’)

Alternatively, user-defined parameter settings may be registered, with register(), and used identically as pre-specified parameter sets. At minimum, registrations must have unique names and a dictionary of parameters with keys “galcen_coord”, “galcen_distance”, “galcen_v_sun”, “z_sun”, “roll”. See examples below.

This class also tracks the references for all parameter values in the attribute references, as well as any further information the registry. The pre-specified options can be extended to include similar state information as user-defined parameter settings – for example, to add parameter uncertainties.

The preferred method for getting a parameter set and metadata, by name, is get_from_registry() since it ensures the immutability of the registry.

See Controlling the Default Frame Parameters for more information.

Examples

The default Galactocentric frame parameters can be modified globally:

>>> from astropy.coordinates import galactocentric_frame_defaults
>>> _ = galactocentric_frame_defaults.set('v4.0') 
>>> Galactocentric() 
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
    (266.4051, -28.936175)>, galcen_distance=8.122 kpc, galcen_v_sun=(12.9, 245.6, 7.78) km / s, z_sun=20.8 pc, roll=0.0 deg)>
>>> _ = galactocentric_frame_defaults.set('pre-v4.0') 
>>> Galactocentric() 
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
    (266.4051, -28.936175)>, galcen_distance=8.3 kpc, galcen_v_sun=(11.1, 232.24, 7.25) km / s, z_sun=27.0 pc, roll=0.0 deg)>

The default parameters can also be updated by using this class as a context manager:

>>> with galactocentric_frame_defaults.set('pre-v4.0'):
...     print(Galactocentric()) 
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
    (266.4051, -28.936175)>, galcen_distance=8.3 kpc, galcen_v_sun=(11.1, 232.24, 7.25) km / s, z_sun=27.0 pc, roll=0.0 deg)>

Again, changing the default parameter values will not affect frame attributes that are explicitly specified:

>>> import astropy.units as u
>>> with galactocentric_frame_defaults.set('pre-v4.0'):
...     print(Galactocentric(galcen_distance=8.0*u.kpc)) 
<Galactocentric Frame (galcen_coord=<ICRS Coordinate: (ra, dec) in deg
    (266.4051, -28.936175)>, galcen_distance=8.0 kpc, galcen_v_sun=(11.1, 232.24, 7.25) km / s, z_sun=27.0 pc, roll=0.0 deg)>

Additional parameter sets may be registered, for instance to use the Dehnen & Binney (1998) measurements of the solar motion. We can also add metadata, such as the 1-sigma errors. In this example we will modify the required key “parameters”, change the recommended key “references” to match “parameters”, and add the extra key “error” (any key can be added):

>>> state = galactocentric_frame_defaults.get_from_registry("v4.0")
>>> state["parameters"]["galcen_v_sun"] = (10.00, 225.25, 7.17) * (u.km / u.s)
>>> state["references"]["galcen_v_sun"] = "https://ui.adsabs.harvard.edu/full/1998MNRAS.298..387D"
>>> state["error"] = {"galcen_v_sun": (0.36, 0.62, 0.38) * (u.km / u.s)}
>>> galactocentric_frame_defaults.register(name="DB1998", **state)

Just as in the previous examples, the new parameter set can be retrieved with:

>>> state = galactocentric_frame_defaults.get_from_registry("DB1998")
>>> print(state["error"]["galcen_v_sun"])  
[0.36 0.62 0.38] km / s

Attributes Summary

parameters

references

Methods Summary

get_from_registry(name)

Return Galactocentric solar parameters and metadata given string names for the parameter sets.

get_solar_params_from_string(arg)

Deprecated since version v4.2.

register(name, parameters[, references])

Register a set of parameters.

validate(value)

Validate the value and convert it to its native type, if necessary.

Attributes Documentation

parameters
references

Methods Documentation

classmethod get_from_registry(name: str)[source]

Return Galactocentric solar parameters and metadata given string names for the parameter sets. This method ensures the returned state is a mutable copy, so any changes made do not affect the registry state.

Returns
statedict

Copy of the registry for the string name. Should contain, at minimum:

  • “parameters”: dict

    Galactocentric solar parameters

  • “references”Dict[str, Union[str, Sequence[str]]]

    References for “parameters”. Fields are str or sequence of str.

Raises
KeyError

If invalid string input to registry to retrieve solar parameters for Galactocentric frame.

classmethod get_solar_params_from_string(arg)[source]

Deprecated since version v4.2: The get_solar_params_from_string method is deprecated and may be removed in a future version. Use get_from_registry instead.

Return Galactocentric solar parameters given string names for the parameter sets.

Returns
parametersdict

Copy of Galactocentric solar parameters from registry

Raises
KeyError

If invalid string input to registry to retrieve solar parameters for Galactocentric frame.

classmethod register(name: str, parameters: dict, references=None, **meta: dict)[source]

Register a set of parameters.

Parameters
namestr

The registration name for the parameter and metadata set.

parametersdict

The solar parameters for Galactocentric frame.

referencesdict or None, optional

References for contents of parameters. None becomes empty dict.

**meta: dict, optional

Any other properties to register.

classmethod validate(value)[source]

Validate the value and convert it to its native type, if necessary.