Skip to content

Commit

Permalink
docstrings prontas
Browse files Browse the repository at this point in the history
  • Loading branch information
@viniciusdutra314
viniciusdutra314 committed Jan 24, 2025
1 parent fba573a commit 42ccf72
Show file tree
Hide file tree
Showing 6 changed files with 277 additions and 191 deletions.
113 changes: 46 additions & 67 deletions LabIFSC2/_arrays.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,25 +10,21 @@

@obrigar_tipos
def nominais(arrayMedidas : np.ndarray,unidade:str) -> np.ndarray:
'''*get_nominais* Transforma um array/lista (Sequência) de medidas em
um arrays somente com seus valores nominais
Args:
arrayMedidas (Sequence | np.ndarray): array com medidas
Returns:
arrayNominais (Sequence | np.ndarray): array valores nominais
"""
Converte um array de objetos Medida para um array de valores nominais em uma unidade especificada.
Args:
arrayMedidas (np.ndarray): Array de objetos Medida.
unidade (str): Unidade para a conversão dos valores nominais. Use 'si' para unidades do Sistema Internacional.
Returns:
np.ndarray: Array de valores nominais convertidos para a unidade especificada.
Raises:
TypeError: Se algum dos valores no array não for um objeto Medida.
"""


Raises:
ValueError: Se algum valor não for uma Medida
Examples:
>>> import LabIFSC2 as lab
>>> import numpy as np
>>> array = np.array([lab.Medida(4, 0.2),lab.Medida(35, 3), lab.Medida(-97, 1)])
>>> lab.get_nominais(array)
array([ 4., 35., -97.])
'''
if not (isinstance(arrayMedidas[0],Medida)):
raise TypeError('Os valores do array não são Medidas')
if unidade=='si':
Expand All @@ -38,22 +34,20 @@ def nominais(arrayMedidas : np.ndarray,unidade:str) -> np.ndarray:

@obrigar_tipos
def incertezas(arrayMedidas : np.ndarray,unidade:str) -> np.ndarray:
'''*get_incertezas* Transforma um array/lista (Sequência) de medidas em
um arrays somente com suas incertezas
Args:
arrayMedidas (Sequence[Medida]): array com medidas
Returns:
arrayIncertezas(np.ndarray[Medida]) : array com incertezas
"""
Converte um array de objetos Medida para um array de incertezas em uma unidade especificada.
Args:
arrayMedidas (np.ndarray): Array de objetos Medida.
unidade (str): Unidade para a conversão das incertezas. Use 'si' para unidades do Sistema Internacional.
Returns:
np.ndarray: Array de incertezas convertidas para a unidade especificada.
Raises:
TypeError: Se algum dos valores no array não for um objeto Medida.
"""

Examples:
>>> import LabIFSC2 as lab
>>> import numpy as np
>>> array = np.array([lab.Medida(4, 0.2),lab.Medida(35, 3), lab.Medida(-97, 1)])
>>> lab.get_incertezas(array)
array([0.2, 3. , 1. ])
'''
if not (isinstance(arrayMedidas[0],Medida)):
raise TypeError('Os valores do array não são Medidas')
if unidade=='si':
Expand All @@ -63,54 +57,39 @@ def incertezas(arrayMedidas : np.ndarray,unidade:str) -> np.ndarray:


@obrigar_tipos
def linspaceM(a:Real,b:Real,n : int,
unidade : str,incertezas : Real ,) -> np.ndarray:
"""Gera um array com N Medidas de valor nominal [a,b]
A incerteza será constante caso 'incertezas' for um número,
mas se ela for um array cada Medida terá a respectiva incerteza.
A unidade será a mesma e é opcional
def linspaceM(a:Real,b:Real,n : int,unidade:str,incertezas:Real) -> np.ndarray:
"""Gera um array de Medidas com valores igualmente espaçados.
Args:
`a` (Number): Menor nominal
`b` (Number): Maior nominal
`n` (int): Número de Medidas
`incertezas` (Number | Sequence[Number]): incerteza ou array de incertezas
`unidade` (str): unidade das medidas
a (Real): O valor inicial do intervalo.
b (Real): O valor final do intervalo.
n (int): O número de elementos no array.
unidade (str): A unidade das medidas.
incertezas (Real): A incerteza associada a cada medida.
Returns:
arrayM (np.ndarray[Medida]): array de Medidas
Examples:
>>> import LabIFSC2 as lab
>>> import numpy as np
>>> a=1 ; b=5 ; N=3
>>> tempo=lab.linspace(a,b,N,0.1,'s')
>>> tempo
array([(1.0±0.1)s, (3.0±0.1)s, (5.0±0.1)s], dtype=object)
>>> tempo**2
(1.0±0.2)s... (4.0±0.4)s ... (25±1)s]
Esse é um exemplo com poucos pontos para que
seja possível observar uma diferença significativa
entre as Medidas
np.ndarray: Um array de objetos Medida com valores igualmente espaçados.
"""
return np.array([Medida(i,unidade,incertezas) for i in np.linspace(float(a),float(b),n)],dtype=object)


@obrigar_tipos
def arrayM(nominais:np.ndarray | Sequence ,unidade:str,incerteza:Real) ->np.ndarray:
'''Converte um array de números em um array de Medidas
"""
Cria um array de objetos Medida a partir de valores nominais, unidade e incerteza.
Args:
nominais (Sequence[Number]): valores nominais
incerteza (Number): incerteza associada a cada medição
unidade (str): unidade das medições
nominais (np.ndarray | Sequence): Uma sequência de valores nominais.
unidade (str): A unidade de medida.
incerteza (Real): A incerteza associada aos valores nominais.
Returns:
arrayM (np.ndarray[Medida]): array de Medidas
np.ndarray: Um array de objetos Medida.
Raises:
TypeError: Se os valores do array não forem números reais.
"""

'''
if not (isinstance(nominais[0],Real)):
raise TypeError('Os valores do array não são números reais')

Expand Down
115 changes: 65 additions & 50 deletions LabIFSC2/_medida.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,16 +46,18 @@ class Medida:
@obrigar_tipos
def __init__(self,nominal:Real | list,unidade : str,incerteza : Real):
"""
Representa uma medida física com um valor nominal, incerteza e unidade.
A classe Medida é usada para converter unidades e propagar incertezas
de maneira simples, se comportando para vários propósitos como um número
Atributos:
nominal (Real): O valor nominal da medida.
incerteza (Real): A incerteza associada à medida.
unidade (str): A unidade da medida.
Inicializa uma instância da classe com valores nominais, unidade e incerteza.
Args:
nominal (Real | list): Valor nominal ou uma lista de valores nominais.
unidade (str): Unidade de medida.
incerteza (Real): Incerteza associada ao valor nominal.
Raises:
ValueError: Se a incerteza for negativa.
ValueError: Se a lista de medidas tiver menos de 2 elementos.
"""

if incerteza<0: raise ValueError("Incerteza não pode ser negativa")

if isinstance(nominal,list):
Expand All @@ -77,12 +79,32 @@ def __init__(self,nominal:Real | list,unidade : str,incerteza : Real):

@obrigar_tipos
def nominal(self:'Medida',unidade:str) -> float:
"""
Retorna o valor nominal da medida na unidade especificada.
Args:
unidade (str): A unidade na qual o valor nominal deve ser retornado.
Se 'si', retorna o valor em unidades do Sistema Internacional (SI).
Returns:
float: O valor nominal da medida na unidade especificada.
"""
if unidade.lower()=='si':
return float(self._nominal.to_base_units().magnitude)
else:
return float(self._nominal.to(unidade).magnitude)
@obrigar_tipos
def incerteza(self:'Medida',unidade:str) -> float:
"""
Retorna a incerteza da medida na unidade especificada.
Args:
unidade (str): A unidade na qual a incerteza deve ser retornado.
Se 'si', retorna o valor em unidades do Sistema Internacional (SI).
Returns:
float: O valor da incerteza da medida na unidade especificada.
"""
if unidade.lower()=='si':
return float(self._incerteza.to_base_units().magnitude)
else:
Expand Down Expand Up @@ -320,21 +342,21 @@ def __pos__(self) -> 'Medida':

@obrigar_tipos
def probabilidade_de_estar_entre(self,a:Real,b:Real,unidade:str) -> float:
''' Retorna a probabilidade que a Medida
esteja entre [a,b] usando o histograma como
referencia
"""
Calcula a probabilidade de uma medida estar entre dois valores especificados.
Args:
`a` (Number): Extremo inferior
`b`(Number): Extremo superior
a (Real): O valor inferior do intervalo.
b (Real): O valor superior do intervalo.
unidade (str): A unidade de medida dos valores a e b.
Returns:
`probabilidade`: (Number) probabilidade de estar entre [a,b]
float: A probabilidade de a medida estar entre os valores a e b.
Raises:
ValueError: Se `a` for maior que `b`
'''

ValueError: Se o valor de `a` for maior que `b`.
ValueError: Se a unidade fornecida não for compatível com a unidade da medida.
"""
if a>b: raise ValueError("a deve ser menor que b")
if not self._nominal.is_compatible_with(unidade):
raise ValueError(f"Unidade {unidade} não é compatível com a unidade da medida")
Expand All @@ -353,18 +375,20 @@ def probabilidade_de_estar_entre(self,a:Real,b:Real,unidade:str) -> float:

@obrigar_tipos
def intervalo_de_confiança(self:'Medida',p:Real,unidade:str) -> list:
''' Retorna o intervalo de confiança para a Medida
com base no histograma
"""
Calcula o intervalo de confiança para a medida.
Args:
`p` (float): Probabilidade de estar dentro do intervalo
Returns:- p) < 1e-2
`intervalo`: (tuple) intervalo de confiança
p (Real): Probabilidade associada ao intervalo de confiança. Deve estar entre 0 e 1.
unidade (str): Unidade de medida para o intervalo de confiança.
Returns:
list: Lista contendo os limites inferior e superior do intervalo de confiança.
Raises:
ValueError: Se `p` não estiver entre 0 e 1
'''
ValueError: Se `p` não estiver entre 0 e 1.
"""

if not 0<float(p)<=1: raise ValueError("p deve estar 0 e 1")

elif p==1: return [float(min(self.histograma.magnitude)),float(max(self.histograma.magnitude))]
Expand Down Expand Up @@ -402,30 +426,21 @@ class Comparacao(Enum):
INCONCLUSIVO = "inconclusivo"

@obrigar_tipos
def comparar_medidas(medida1: Medida, medida2: Medida,
sigma_inferior : float=2,sigma_superior:float=3) -> Comparacao:
def comparar_medidas(medida1: Medida, medida2: Medida, sigma_inferior: float = 2, sigma_superior: float = 3) -> Comparacao:
"""
Compara duas medidas considerando suas incertezas e retorna o resultado da comparação.
Args:
`medida1` (Medida) A primeira medida a ser comparada.
`medida2` (Medida) A segunda medida a ser comparada.
`sigmas_customizados` (list[Number], opcional): Lista contendo dois valores sigma.
O primeiro sigma é usado para determinar se as medidas são iguais.
O segundo sigma é usado para determinar se as medidas são diferentes.
O valor padrão é [2, 3].
medida1 (Medida): A primeira medida a ser comparada.
medida2 (Medida): A segunda medida a ser comparada.
sigma_inferior (float, opcional): O fator sigma inferior para considerar as medidas equivalentes. Default é 2.
sigma_superior (float, opcional): O fator sigma superior para considerar as medidas diferentes. Default é 3.
Returns:
`Comparacao` (Enum):
- `Comparacao.IGUAIS`: Se as medidas são consideradas iguais.
- `Comparacao.DIFERENTES`: Se as medidas são consideradas diferentes.
- `Comparacao.INCONCLUSIVO`: Se a comparação é inconclusiva.
Comparacao: O resultado da comparação, que pode ser EQUIVALENTES, DIFERENTES ou INCONCLUSIVO.
Raises:
ValueError: Se o sigma para serem consideradas iguais for maior que o sigma para serem diferentes.
ValueError: Se o sigma_inferior for maior que o sigma_superior.
"""

diferenca_nominal=abs(medida1._nominal-medida2._nominal)
Expand Down
Loading

0 comments on commit 42ccf72

Please sign in to comment.