ASPISpy package
----------------

Intro
^^^^^

ASPISpy is a package of code that allows access to the data contained in ASPIS database and other
various community databases, to perform client-side specific analyses of this data and to
visualize it. The data available are of two types: data in the internal database produced by the CAESAR
community and information on external data in other databases. Along with access to the data, the
ASPISpy package contains code packages that can be imported as package objects, with which to perform
analysis and/or visualization of the data.

The criterion of ASPISpy is to act as a collector for the data and analysis software of the Space Weather (SWx) Italian
community and to foster cooperation within the community. In fact, one can use the data and analysis
methods developed by the community and, likewise, share one’s own data and methods. Indeed, we
have defined a standard template in ASPISpy for generic data analysis code, and provide a how-to for
developers in the SWx community to convert their own code into the standard template, making it
easily usable for the entire ASPISpy community in a standard way. In this way ASPISpy’s primary goal
is to promote collaboration and cooperation within the SWx community. It facilitates the sharing
of data and analysis methods among researchers, enabling them to benefit from each other’s work. In
summary, ASPISpy is a tool designed to streamline the access, analysis, and sharing of 
data and analysis methods within the SWx community. It aims to enhance collaboration and
standardization, making it easier for researchers to work with and build upon each other’s work in the
field of SWX and astrophysics in general.

Functions
^^^^^^^^^

The functions of the ASPISpy module are conceived to implement the following key components of the
ASPIS service:

1. Access for Advanced Users: ASPISpy is designed to cater to advanced users in the SWx
community. It offers a set of functions that can be executed programmatically through a Python
interpreter. This capability allows users to perform more complex computations and analysis tasks,
surpassing the limitations of a web application.

2. Basic Visualization Tools: While ASPISpy provides basic visualization tools/functions, it also en-
courages users to leverage other freely available modules like Sunpy and Astropy for more ad-
vanced visualization needs. This approach ensures compatibility and flexibility.

3. Ready-to-Use Python Snippets: ASPISpy intends to provide ready-to-use Python code snippets.
These snippets are designed to assist entry-level users, making it easier for them to get started
with the module. Advanced users can further customize these code snippets to suit their specific
research requirements.

4. Integration with User Programs: The expectation is that advanced users of ASPISpy will seam-
lessly integrate the functions provided by the module into their own analysis and visualization pro-
grams. This promotes flexibility and allows users to tailor their solutions to their research needs.

5. Structured Information in the Database: ASPISpy relies on structured information within the database.
This information likely includes details about various SWx entities such as phenomena,
data descriptions, and chains, which are essential for conducting meaningful analyses.

6. Data Outside the Database: ASPISpy is designed to work with data that exists outside the database
but corresponds to the descriptions available within the database. This flexibility allows researchers
to combine data from various sources to enhance their analysis.
In summary, ASPISpy is a versatile tool that caters to both entry-level and advanced users in the
SWx community. It provides functions for querying, visualizing, analyzing, and modeling astro-
physical data. The inclusion of code snippets and use case examples simplifies the usage for a broad
range of researchers, and advanced users can extend and customize the functionality to meet their spe-
cific research objectives.

Installation
^^^^^^^^^^^^

**ASPISpy needs python 3.9 and higher to run.**

To install ASPISpy, a user typically needs to follow these general steps. Please note that the specific
installation process may vary depending on the availability and distribution method of ASPISpy. The user
has to ensure that Python is installed on the system before proceeding. 

The user can install ASPISpy using pip, which is the Python package manager:

``mkdir aspispy``

``cd aspispy``

``curl -get -O https://caesar.iaps.inaf.it/wp-content/uploads/aspispy/aspis-0.2.2-py3-none-any.whl``

``sudo -H pip3 install aspis-0.2.2-py3-none-any.whl``

The command is used to install a Python package from a Wheel file (.whl) using pip3 with adminis-
trative privileges (via sudo). The specific package being installed is "aspis-0.2.2-py3-none-any.whl".

Here’s a breakdown of the command:

* sudo: It is used to run the pip3 command with superuser privileges, which may be necessary for system-wide installations.
* -H: This flag is used to set the home directory to the target user’s home directory. It can help avoid potential issues with environment variables when using sudo.
* pip3: This is the Python package manager for Python 3.
* install: It’s the pip command to install packages.
* aspis-0.2.2-py3-none-any.whl: This is Wheel file that you want to install.

If everything is set up correctly, running this command install the ASPIS package version 0.2.2 from
the provided Wheel file. Note that version number may have changed.

Use case example
^^^^^^^^^^^^^^^^

Here we show an example of the way a user can use a specific product of the ASPISpy package.
from aspis import products as aps
from datetime import datetime

product input:

``V0 = 1846 #* u.km / u.s``

``sigma_V0 = 362 #* u.km / u.s``

``Time_UTC = datetime ( 2017 , 9 , 6 , 14 , 1 , 0)``

call the class:

``obj = aps . pdbm ()``

compute the CME:

``obj . process (V0 , sigma_V0 , Time_UTC )``

compute the CME on target = Earth:

``obj . run ()``

plot:

``plt = obj . plot ( savefig = True )``

``plt = obj . plot ( type = ’ Travel time ’, savefig = True )``

``plt = obj . plot ( type = ’ ICME velocity ’, savefig = True )``

This example code performs the following steps:

#.  Import necessary modules and classes from the "aspis" package.
#.  Define input parameters, namely the initial velocity (V0), its uncertainty (sigma_V0), and a times-tamp (Time_UTC).
#.  Create an instance of the "pdbm" class from the "aspis.products" module.
#.  Use this instance to compute the CME (Coronal Mass Ejection) model parameters based on the provided input.
#.  Predict the behavior of the CME when it reaches its target, which is the Earth in this case.
#.  Generate and save plots related to the CME modeling and prediction including "Travel time" and "ICME velocity."

Additionally, it’s essential to check the specific classes and methods used in the script to understand
their usage and any additional requirements for proper execution.

Code snippets and standardization
.................................

The idea of ASPISpy is that code developed by different members of the Space Weather community in contiguous 
fields can be made available to each other and shared in exactly the same way as is usually done
with data. In the area of data, standardization of formats and thus the use of databases in which to store
information in a consistent and shared manner has been adopted for years. As for software, the situation
is more complex because codes have very heterogeneous characteristics among themselves and code
groupings still have strong limitations. Inspired by some recent experiences aimed at standardizing the
use of codes and comparing the performance of different methods on the same data, ASPISpy aims to
provide a structural scheme with the ability to make the use of code developed by different members of
the Space Weather community for even different purposes available to the entire community.

In particular, ASPIS provides four main functions:

``class < class_name >:``

``def __init__ ( self ) -> None :``

``# initialize parameters``

``def process ( self ):``

``# process data``

``def run ( self ):``

``# run method``

``def plot ( self ):``

``# plot results``

These functions have been thought with the following purposes:

* the "init" function is used to instantiate the object that will perform the data analysis by initializing the necessary parameters

* the "process" function is for analyzing the data according to a predetermined pattern

* the "run" function is for using the predetermined model

* the "plot" function is for making visible the parameters, data used and outputs of the model

All four functions are parameterizable so as to ensure that complex codes that depend on parameter
structures can be framed in the ASPIS system and can therefore perform tasks according to different
patterns.
The proposed structure is based on the following consideration: advanced methods for data analysis
in the field of SWx (and beyond) fall into two main classes: methods supported by a physical
model and those that lack it. The former are estimation problems - direct or inverse - for which the
"process" function should be implemented as the procedure for solving the inverse problem, meaning that
the optimization method that solves the inverse problem should be implemented in this part. In the "run"
section, the code that, conversely, solves the forward problem should be inserted. Regarding methods of
data analysis without a model, namely estimation or statistical learning methods, the "process" and "run"
functions correspond, respectively, to the training or learning process of the introduced (non-physical)
model and to the prediction procedure associated with the trained model. This concept resembles the
“fit” and “predict” methods of the “scikit-learn” library used in the significantly more homogeneous case of
matrix problem
